client_golang/prometheus/metric.go

176 lines
6.5 KiB
Go
Raw Normal View History

// Copyright 2014 The Prometheus 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 prometheus
import (
"strings"
"time"
"github.com/gogo/protobuf/proto"
2015-02-27 18:12:59 +03:00
dto "github.com/prometheus/client_model/go"
)
const separatorByte byte = 255
// A Metric models a single sample value with its meta data being exported to
// Prometheus. Implementations of Metric in this package are Gauge, Counter,
// Histogram, Summary, and Untyped.
type Metric interface {
// Desc returns the descriptor for the Metric. This method idempotently
// returns the same descriptor throughout the lifetime of the
Allow error reporting during metrics collection and simplify Register(). Both are interface changes I want to get in before public announcement. They only break rare usage cases, and are always easy to fix, but still we want to avoid breaking changes after a wider announcement of the project. The change of Register() simply removes the return of the Collector, which nobody was using in practice. It was just bloating the call syntax. Note that this is different from RegisterOrGet(), which is used at various occasions where you want to register something that might or might not be registered already, but if it is, you want the previously registered Collector back (because that's the relevant one). WRT error reporting: I first tried the obvious way of letting the Collector methods Describe() and Collect() return error. However, I had to conclude that that bloated _many_ calls and their handling in very obnoxious ways. On the other hand, the case where you actually want to report errors during registration or collection is very rare. Hence, this approach has the wrong trade-off. The approach taken here might at first appear clunky but is in practice quite handy, mostly because there is almost no change for the "normal" case of "no special error handling", but also because it plays well with the way descriptors and metrics are handled (via channels). Explaining the approach in more detail: - During registration / describe: Error handling was actually already in place (for invalid descriptors, which carry an error anyway). I only added a convenience function to create an invalid descriptor with a given error on purpose. - Metrics are now treated in a similar way. The Write method returns an error now (the only change in interface). An "invalid metric" is provided that can be sent via the channel to signal that that metric could not be collected. It alse transports an error. NON-GOALS OF THIS COMMIT: This is NOT yet the major improvement of the whole registry part, where we want a public Registry interface and plenty of modular configurations (for error handling, various auto-metrics, http instrumentation, testing, ...). However, we can do that whole thing without breaking existing interfaces. For now (which is a significant issue) any error during collection will either cause a 500 HTTP response or a panic (depending on registry config). Later, we definitely want to have a possibility to skip (and only report somehow) non-collectible metrics instead of aborting the whole scrape.
2015-01-12 21:16:09 +03:00
// Metric. The returned descriptor is immutable by contract. A Metric
// unable to describe itself must return an invalid descriptor (created
// with NewInvalidDesc).
Desc() *Desc
// Write encodes the Metric into a "Metric" Protocol Buffer data
// transmission object.
//
// Metric implementations must observe concurrency safety as reads of
// this metric may occur at any time, and any blocking occurs at the
// expense of total performance of rendering all registered
// metrics. Ideally, Metric implementations should support concurrent
// readers.
//
// While populating dto.Metric, it is the responsibility of the
// implementation to ensure validity of the Metric protobuf (like valid
// UTF-8 strings or syntactically valid metric and label names). It is
// recommended to sort labels lexicographically. (Implementers may find
// LabelPairSorter useful for that.) Callers of Write should still make
// sure of sorting if they depend on it.
Allow error reporting during metrics collection and simplify Register(). Both are interface changes I want to get in before public announcement. They only break rare usage cases, and are always easy to fix, but still we want to avoid breaking changes after a wider announcement of the project. The change of Register() simply removes the return of the Collector, which nobody was using in practice. It was just bloating the call syntax. Note that this is different from RegisterOrGet(), which is used at various occasions where you want to register something that might or might not be registered already, but if it is, you want the previously registered Collector back (because that's the relevant one). WRT error reporting: I first tried the obvious way of letting the Collector methods Describe() and Collect() return error. However, I had to conclude that that bloated _many_ calls and their handling in very obnoxious ways. On the other hand, the case where you actually want to report errors during registration or collection is very rare. Hence, this approach has the wrong trade-off. The approach taken here might at first appear clunky but is in practice quite handy, mostly because there is almost no change for the "normal" case of "no special error handling", but also because it plays well with the way descriptors and metrics are handled (via channels). Explaining the approach in more detail: - During registration / describe: Error handling was actually already in place (for invalid descriptors, which carry an error anyway). I only added a convenience function to create an invalid descriptor with a given error on purpose. - Metrics are now treated in a similar way. The Write method returns an error now (the only change in interface). An "invalid metric" is provided that can be sent via the channel to signal that that metric could not be collected. It alse transports an error. NON-GOALS OF THIS COMMIT: This is NOT yet the major improvement of the whole registry part, where we want a public Registry interface and plenty of modular configurations (for error handling, various auto-metrics, http instrumentation, testing, ...). However, we can do that whole thing without breaking existing interfaces. For now (which is a significant issue) any error during collection will either cause a 500 HTTP response or a panic (depending on registry config). Later, we definitely want to have a possibility to skip (and only report somehow) non-collectible metrics instead of aborting the whole scrape.
2015-01-12 21:16:09 +03:00
Write(*dto.Metric) error
Create a public registry interface and separate out HTTP exposition General context and approch =========================== This is the first part of the long awaited wider refurbishment of `client_golang/prometheus/...`. After a lot of struggling, I decided to not go for one breaking big-bang, but cut things into smaller steps after all, mostly to keep the changes manageable and easy to review. I'm aiming for having the invasive breaking changes concentrated in as few steps as possible (ideally one). Some steps will not be breaking at all, but typically there will be breaking changes that only affect quite special cases so that 95+% of users will not be affected. This first step is an example for that, see details below. What's happening in this commit? ================================ This step is about finally creating an exported registry interface. This could not be done by simply export the existing internal implementation because the interface would be _way_ too fat. This commit introduces a qutie lean `Registry` interface (compared to the previous interval implementation). The functions that act on the default registry are retained (with very few exceptions) so that most use cases won't see a change. However, several of those are deprecated now to clean up the namespace in the future. The default registry is kept in the public variable `DefaultRegistry`. This follows the example of the http package in the standard library (cf. `http.DefaultServeMux`, `http.DefaultClient`) with the same implications. (This pattern is somewhat disputed within the Go community but I chose to go with the devil you know instead of creating something more complex or even disallowing any changes to the default registry. The current approach gives everybody the freedom to not touch DefaultRegistry or to do everything with a custom registry to play save.) Another important part in making the registry lean is the extraction of the HTTP exposition, which also allows for customization of the HTTP exposition. Note that the separation of metric collection and exposition has the side effect that managing the MetricFamily and Metric protobuf objects in a free-list or pool isn't really feasible anymore. By now (with better GC in more recent Go versions), the returns were anyway dimisishing. To be effective at all, scrapes had to happen more often than GC cycles, and even then most elements of the protobufs (everything excetp the MetricFamily and Metric structs themselves) would still cause allocation churn. In a future breaking change, the signature of the Write method in the Metric interface will be adjusted accordingly. In this commit, avoiding breakage is more important. The following issues are fixed by this commit (some solved "on the fly" now that I was touching the code anyway and it would have been stupid to port the bugs): https://github.com/prometheus/client_golang/issues/46 https://github.com/prometheus/client_golang/issues/100 https://github.com/prometheus/client_golang/issues/170 https://github.com/prometheus/client_golang/issues/205 Documentation including examples have been amended as required. What future changes does this commit enable? ============================================ The following items are not yet implemented, but this commit opens the possibility of implementing these independently. - The separation of the HTTP exposition allows the implementation of other exposition methods based on the Registry interface, as known from other Prometheus client libraries, e.g. sending the metrics to Graphite. Cf. https://github.com/prometheus/client_golang/issues/197 - The public `Registry` interface allows the implementation of convenience tools for testing metrics collection. Those tools can inspect the collected MetricFamily protobufs and compare them to expectation. Also, tests can use their own testing instance of a registry. Cf. https://github.com/prometheus/client_golang/issues/58 Notable non-goals of this commit ================================ Non-goals that will be tackled later ------------------------------------ The following two issues are quite closely connected to the changes in this commit but the line has been drawn deliberately to address them in later steps of the refurbishment: - `InstrumentHandler` has many known problems. The plan is to create a saner way to conveniently intrument HTTP handlers and remove the old `InstrumentHandler` altogether. To keep breakage low for now, even the default handler to expose metrics is still using the old `InstrumentHandler`. This leads to weird naming inconsistencies but I have deemed it better to not break the world right now but do it in the change that provides better ways of instrumenting HTTP handlers. Cf. https://github.com/prometheus/client_golang/issues/200 - There is work underway to make the whole handling of metric descriptors (`Desc`) more intuitive and transparent for the user (including an ability for less strict checking, cf. https://github.com/prometheus/client_golang/issues/47). That's quite invasive from the perspective of the internal code, namely the registry. I deliberately kept those changes out of this commit. - While this commit adds new external dependency, the effort to vendor anything within the library that is not visible in any exported types will have to be done later. Non-goals that _might_ be tackled later --------------------------------------- There is a strong and understandable urge to divide the `prometheus` package into a number of sub-packages (like `registry`, `collectors`, `http`, `metrics`, …). However, to not run into a multitude of circular import chains, this would need to break every single existing usage of the library. (As just one example, if the ubiquitious `prometheus.MustRegister` (with more than 2,000 uses on GitHub alone) is kept in the `prometheus` package, but the other registry concerns go into a new `registry` package, then the `prometheus` package would import the `registry` package (to call the actual register method), while at the same time the `registry` package needs to import the `prometheus` package to access `Collector`, `Metric`, `Desc` and more. If we moved `MustRegister` into the `registry` package, thousands of code lines would have to be fixed (which would be easy if the world was a mono repo, but it is not). If we moved everything else the proposed registry package needs into packages of their own, we would break thousands of other code lines.) The main problem is really the top-level functions like `MustRegister`, `Handler`, …, which effectively pull everything into one package. Those functions are however very convenient for the easy and very frequent use-cases. This problem has to be revisited later. For now, I'm trying to keep the amount of exported names in the package as low as possible (e.g. I unexported expvarCollector in this commit because the NewExpvarCollector constructor is enough to export, and it is now consistent with other collectors, like the goCollector). Non-goals that won't be tackled anytime soon -------------------------------------------- Something that I have played with a lot is "streaming collection", i.e. allow an implementation of the `Registry` interface that collects metrics incrementally and serves them while doing so. As it has turned out, this has many many issues and makes the `Registry` interface very clunky. Eventually, I made the call that it is unlikely we will really implement streaming collection; and making the interface more clunky for something that might not even happen is really a big no-no. Note that the `Registry` interface only creates the in-memory representation of the metric family protobufs in one go. The serializaton onto the wire can still be handled in a streaming fashion (which hasn't been done so far, without causing any trouble, but might be done in the future without breaking any interfaces). What are the breaking changes? ============================== - Signatures of functions pushing to Pushgateway have changed to allow arbitrary grouping (which was planned for a long time anyway, and now that I had to work on the Push code anyway for the registry refurbishment, I finally did it, cf. https://github.com/prometheus/client_golang/issues/100). With the gained insight that pushing to the default registry is almost never the right thing, and now that we are breaking the Push call anyway, all the Push functions were moved to their own package, which cleans up the namespace and is more idiomatic (pushing Collectors is now literally done by `push.Collectors(...)`). - The registry is doing more consistency checks by default now. Past creators of inconsistent metrics could have masked the problem by not setting `EnableCollectChecks`. Those inconsistencies will now be detected. (But note that a "best effort" metrics collection is now possible with `HandlerOpts.ErrorHandling = ContinueOnError`.) - `EnableCollectChecks` is gone. The registry is now performing some of those checks anyway (see previous item), and a registry with all of those checks can now be created with `NewPedanticRegistry` (only used for testing). - `PanicOnCollectError` is gone. This behavior can now be configured when creating a custom HTTP handler.
2016-07-20 18:11:14 +03:00
// TODO(beorn7): The original rationale of passing in a pre-allocated
// dto.Metric protobuf to save allocations has disappeared. The
// signature of this method should be changed to "Write() (*dto.Metric,
// error)".
}
// Opts bundles the options for creating most Metric types. Each metric
// implementation XXX has its own XXXOpts type, but in most cases, it is just be
// an alias of this type (which might change when the requirement arises.)
//
// It is mandatory to set Name and Help to a non-empty string. All other fields
// are optional and can safely be left at their zero value.
type Opts struct {
// Namespace, Subsystem, and Name are components of the fully-qualified
// name of the Metric (created by joining these components with
// "_"). Only Name is mandatory, the others merely help structuring the
// name. Note that the fully-qualified name of the metric must be a
// valid Prometheus metric name.
Namespace string
Subsystem string
Name string
// Help provides information about this metric. Mandatory!
//
// Metrics with the same fully-qualified name must have the same Help
// string.
Help string
// ConstLabels are used to attach fixed labels to this metric. Metrics
// with the same fully-qualified name must have the same label names in
// their ConstLabels.
//
// ConstLabels are only used rarely. In particular, do not use them to
// attach the same labels to all your metrics. Those use cases are
// better covered by target labels set by the scraping Prometheus
// server, or by one specific metric (e.g. a build_info or a
// machine_role metric). See also
// https://prometheus.io/docs/instrumenting/writing_exporters/#target-labels,-not-static-scraped-labels
ConstLabels Labels
}
// BuildFQName joins the given three name components by "_". Empty name
// components are ignored. If the name parameter itself is empty, an empty
// string is returned, no matter what. Metric implementations included in this
// library use this function internally to generate the fully-qualified metric
// name from the name component in their Opts. Users of the library will only
// need this function if they implement their own Metric or instantiate a Desc
// (with NewDesc) directly.
func BuildFQName(namespace, subsystem, name string) string {
if name == "" {
return ""
}
switch {
case namespace != "" && subsystem != "":
return strings.Join([]string{namespace, subsystem, name}, "_")
case namespace != "":
return strings.Join([]string{namespace, name}, "_")
case subsystem != "":
return strings.Join([]string{subsystem, name}, "_")
}
return name
}
// LabelPairSorter implements sort.Interface. It is used to sort a slice of
// dto.LabelPair pointers. This is useful for implementing the Write method of
// custom metrics.
type LabelPairSorter []*dto.LabelPair
func (s LabelPairSorter) Len() int {
return len(s)
}
func (s LabelPairSorter) Swap(i, j int) {
s[i], s[j] = s[j], s[i]
}
func (s LabelPairSorter) Less(i, j int) bool {
return s[i].GetName() < s[j].GetName()
}
Allow error reporting during metrics collection and simplify Register(). Both are interface changes I want to get in before public announcement. They only break rare usage cases, and are always easy to fix, but still we want to avoid breaking changes after a wider announcement of the project. The change of Register() simply removes the return of the Collector, which nobody was using in practice. It was just bloating the call syntax. Note that this is different from RegisterOrGet(), which is used at various occasions where you want to register something that might or might not be registered already, but if it is, you want the previously registered Collector back (because that's the relevant one). WRT error reporting: I first tried the obvious way of letting the Collector methods Describe() and Collect() return error. However, I had to conclude that that bloated _many_ calls and their handling in very obnoxious ways. On the other hand, the case where you actually want to report errors during registration or collection is very rare. Hence, this approach has the wrong trade-off. The approach taken here might at first appear clunky but is in practice quite handy, mostly because there is almost no change for the "normal" case of "no special error handling", but also because it plays well with the way descriptors and metrics are handled (via channels). Explaining the approach in more detail: - During registration / describe: Error handling was actually already in place (for invalid descriptors, which carry an error anyway). I only added a convenience function to create an invalid descriptor with a given error on purpose. - Metrics are now treated in a similar way. The Write method returns an error now (the only change in interface). An "invalid metric" is provided that can be sent via the channel to signal that that metric could not be collected. It alse transports an error. NON-GOALS OF THIS COMMIT: This is NOT yet the major improvement of the whole registry part, where we want a public Registry interface and plenty of modular configurations (for error handling, various auto-metrics, http instrumentation, testing, ...). However, we can do that whole thing without breaking existing interfaces. For now (which is a significant issue) any error during collection will either cause a 500 HTTP response or a panic (depending on registry config). Later, we definitely want to have a possibility to skip (and only report somehow) non-collectible metrics instead of aborting the whole scrape.
2015-01-12 21:16:09 +03:00
type invalidMetric struct {
desc *Desc
err error
}
// NewInvalidMetric returns a metric whose Write method always returns the
// provided error. It is useful if a Collector finds itself unable to collect
// a metric and wishes to report an error to the registry.
func NewInvalidMetric(desc *Desc, err error) Metric {
return &invalidMetric{desc, err}
}
func (m *invalidMetric) Desc() *Desc { return m.desc }
func (m *invalidMetric) Write(*dto.Metric) error { return m.err }
type timestampedMetric struct {
Metric
t time.Time
}
func (m timestampedMetric) Write(pb *dto.Metric) error {
e := m.Metric.Write(pb)
pb.TimestampMs = proto.Int64(m.t.Unix()*1000 + int64(m.t.Nanosecond()/1000000))
return e
}
// NewMetricWithTimestamp returns a new Metric wrapping the provided Metric in a
// way that it has an explicit timestamp set to the provided Time. This is only
// useful in rare cases as the timestamp of a Prometheus metric should usually
// be set by the Prometheus server during scraping. Exceptions include mirroring
// metrics with given timestamps from other metric
// sources.
//
// NewMetricWithTimestamp works best with MustNewConstMetric,
// MustNewConstHistogram, and MustNewConstSummary, see example.
//
// Currently, the exposition formats used by Prometheus are limited to
// millisecond resolution. Thus, the provided time will be rounded down to the
// next full millisecond value.
func NewMetricWithTimestamp(t time.Time, m Metric) Metric {
return timestampedMetric{Metric: m, t: t}
}