From 8e1eec57c40efd068cc73e66dbcfc0b759fa8116 Mon Sep 17 00:00:00 2001 From: RainbowMango Date: Tue, 24 Sep 2019 19:59:00 +0800 Subject: [PATCH] Extend prometheus.Desc --- .../src/k8s.io/component-base/metrics/desc.go | 179 ++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 staging/src/k8s.io/component-base/metrics/desc.go diff --git a/staging/src/k8s.io/component-base/metrics/desc.go b/staging/src/k8s.io/component-base/metrics/desc.go new file mode 100644 index 00000000000..28e086e4eaa --- /dev/null +++ b/staging/src/k8s.io/component-base/metrics/desc.go @@ -0,0 +1,179 @@ +/* +Copyright 2019 The Kubernetes Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package metrics + +import ( + "fmt" + "sync" + + "github.com/blang/semver" + "github.com/prometheus/client_golang/prometheus" + + "k8s.io/klog" +) + +var hiddenFlag = "metricsshouldbehidden" + +// Desc is a prometheus.Desc extension. +// +// Use NewDesc to create new Desc instances. +type Desc struct { + // fqName has been built from Namespace, Subsystem, and Name. + fqName string + // help provides some helpful information about this metric. + help string + // constLabels is the label names. Their label values are variable. + constLabels Labels + // variableLabels contains names of labels for which the metric + // maintains variable values. + variableLabels []string + + // promDesc is the descriptor used by every Prometheus Metric. + promDesc *prometheus.Desc + + // stabilityLevel represents the API guarantees for a given defined metric. + stabilityLevel StabilityLevel + // deprecatedVersion represents in which version this metric be deprecated. + deprecatedVersion string + + isDeprecated bool + isHidden bool + isCreated bool + createLock sync.RWMutex + markDeprecationOnce sync.Once + createOnce sync.Once + deprecateOnce sync.Once + hideOnce sync.Once + annotateOnce sync.Once +} + +// NewDesc extends prometheus.NewDesc with stability support. +// +// The stabilityLevel should be valid stability label, such as "metrics.ALPHA" +// and "metrics.STABLE"(Maybe "metrics.BETA" in future). Default value "metrics.ALPHA" +// will be used in case of empty or invalid stability label. +// +// The deprecatedVersion represents in which version this Metric be deprecated. +// The deprecation policy outlined by the control plane metrics stability KEP. +func NewDesc(fqName string, help string, variableLabels []string, constLabels Labels, + stabilityLevel StabilityLevel, deprecatedVersion string) *Desc { + d := &Desc{ + fqName: fqName, + help: help, + variableLabels: variableLabels, + constLabels: constLabels, + } + + // TODO(RainbowMango): replace by stabilityLevel.setDefault() after PR(https://github.com/kubernetes/kubernetes/pull/82957) be merged. + if stabilityLevel == "" { + d.stabilityLevel = ALPHA + } else { + d.stabilityLevel = stabilityLevel + } + + d.deprecatedVersion = deprecatedVersion + + return d +} + +// String formats the Desc as a string. +// The stability metadata maybe annotated in 'HELP' section if called after registry, +// otherwise not. +func (d *Desc) String() string { + if d.isCreated { + return d.promDesc.String() + } + + return prometheus.NewDesc(d.fqName, d.help, d.variableLabels, prometheus.Labels(d.constLabels)).String() +} + +// toPrometheusDesc transform self to prometheus.Desc +func (d *Desc) toPrometheusDesc() *prometheus.Desc { + return d.promDesc +} + +// DeprecatedVersion returns a pointer to the Version or nil +func (d *Desc) DeprecatedVersion() *semver.Version { + return parseSemver(d.deprecatedVersion) + +} + +func (d *Desc) determineDeprecationStatus(version semver.Version) { + selfVersion := d.DeprecatedVersion() + if selfVersion == nil { + return + } + d.markDeprecationOnce.Do(func() { + if selfVersion.LTE(version) { + d.isDeprecated = true + } + if ShouldShowHidden() { + klog.Warningf("Hidden metrics(%s) have been manually overridden, showing this very deprecated metric.", d.fqName) + return + } + if shouldHide(&version, selfVersion) { + klog.Warningf("This metric(%s) has been deprecated for more than one release, hiding.", d.fqName) + d.isHidden = true + } + }) +} + +// IsHidden returns if metric will be hidden +func (d *Desc) IsHidden() bool { + return d.isHidden +} + +// IsDeprecated returns if metric has been deprecated +func (d *Desc) IsDeprecated() bool { + return d.isDeprecated +} + +func (d *Desc) markDeprecated() { + d.deprecateOnce.Do(func() { + d.help = fmt.Sprintf("(Deprecated since %s) %s", d.deprecatedVersion, d.help) + }) +} + +// markHidden mark a special flag to 'HELP'. +// The metrics marked with this flag will be ignored when collecting automatically. +func (d *Desc) markHidden() { + d.hideOnce.Do(func() { + d.help = fmt.Sprintf("(%s) %s", hiddenFlag, d.help) + }) +} + +func (d *Desc) annotateStabilityLevel() { + d.annotateOnce.Do(func() { + d.help = fmt.Sprintf("[%v] %v", d.stabilityLevel, d.help) + }) +} + +func (d *Desc) initialize() { + d.annotateStabilityLevel() + // this actually creates the underlying prometheus desc. + d.promDesc = prometheus.NewDesc(d.fqName, d.help, d.variableLabels, prometheus.Labels(d.constLabels)) +} + +func (d *Desc) initializeDeprecatedDesc() { + d.markDeprecated() + d.initialize() +} + +func (d *Desc) initializeHiddenDesc() { + d.markHidden() + d.initializeDeprecatedDesc() +}