prometheus

package

v1.23.2Latest Latest

This package is not in the latest version of its module.

Go to latest Published: Sep 5, 2025 License:Apache-2.0Imports:27Imported by:68,437

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/prometheus/client_golang

README ¶

See.

Documentation¶

Rendered for

Overview¶

Package prometheus is the core instrumentation package. It provides metricsprimitives to instrument code for monitoring. It also offers a registry formetrics. Sub-packages allow to expose the registered metrics via HTTP(package promhttp) or push them to a Pushgateway (package push). There isalso a sub-package promauto, which provides metrics constructors withautomatic registration.

All exported functions and methods are safe to be used concurrently unlessspecified otherwise.

A Basic Example¶

As a starting point, a very basic usage example:

package mainimport ("log""net/http""github.com/prometheus/client_golang/prometheus""github.com/prometheus/client_golang/prometheus/promhttp")type metrics struct {cpuTemp  prometheus.GaugehdFailures *prometheus.CounterVec}func NewMetrics(reg prometheus.Registerer) *metrics {m := &metrics{cpuTemp: prometheus.NewGauge(prometheus.GaugeOpts{Name: "cpu_temperature_celsius",Help: "Current temperature of the CPU.",}),hdFailures: prometheus.NewCounterVec(prometheus.CounterOpts{Name: "hd_errors_total",Help: "Number of hard-disk errors.",},[]string{"device"},),}reg.MustRegister(m.cpuTemp)reg.MustRegister(m.hdFailures)return m}func main() {// Create a non-global registry.reg := prometheus.NewRegistry()// Create new metrics and register them using the custom registry.m := NewMetrics(reg)// Set values for the new created metrics.m.cpuTemp.Set(65.3)m.hdFailures.With(prometheus.Labels{"device":"/dev/sda"}).Inc()// Expose metrics and custom registry via an HTTP server// using the HandleFor function. "/metrics" is the usual endpoint for that.http.Handle("/metrics", promhttp.HandlerFor(reg, promhttp.HandlerOpts{Registry: reg}))log.Fatal(http.ListenAndServe(":8080", nil))}

This is a complete program that exports two metrics, a Gauge and a Counter,the latter with a label attached to turn it into a (one-dimensional) vector.It register the metrics using a custom registry and exposes them via an HTTP serveron the /metrics endpoint.

Metrics¶

The number of exported identifiers in this package might appear a bitoverwhelming. However, in addition to the basic plumbing shown in the exampleabove, you only need to understand the different metric types and theirvector versions for basic usage. Furthermore, if you are not concerned withfine-grained control of when and how to register metrics with the registry,have a look at the promauto package, which will effectively allow you toignore registration altogether in simple cases.

Above, you have already touched the Counter and the Gauge. There are two moreadvanced metric types: the Summary and Histogram. A more thorough descriptionof those four metric types can be found in the Prometheus docs:https://prometheus.io/docs/concepts/metric_types/

In addition to the fundamental metric types Gauge, Counter, Summary, andHistogram, a very important part of the Prometheus data model is thepartitioning of samples along dimensions called labels, which results inmetric vectors. The fundamental types are GaugeVec, CounterVec, SummaryVec,and HistogramVec.

While only the fundamental metric types implement the Metric interface, boththe metrics and their vector versions implement the Collector interface. ACollector manages the collection of a number of Metrics, but for convenience,a Metric can also “collect itself”. Note that Gauge, Counter, Summary, andHistogram are interfaces themselves while GaugeVec, CounterVec, SummaryVec,and HistogramVec are not.

To create instances of Metrics and their vector versions, you need a suitable…Opts struct, i.e. GaugeOpts, CounterOpts, SummaryOpts, or HistogramOpts.

Custom Collectors and constant Metrics¶

While you could create your own implementations of Metric, most likely youwill only ever implement the Collector interface on your own. At a firstglance, a custom Collector seems handy to bundle Metrics for commonregistration (with the prime example of the different metric vectors above,which bundle all the metrics of the same name but with different labels).

There is a more involved use case, too: If you already have metricsavailable, created outside of the Prometheus context, you don't need theinterface of the various Metric types. You essentially want to mirror theexisting numbers into Prometheus Metrics during collection. An ownimplementation of the Collector interface is perfect for that. You can createMetric instances “on the fly” using NewConstMetric, NewConstHistogram, andNewConstSummary (and their respective Must… versions). NewConstMetric is usedfor all metric types with just a float64 as their value: Counter, Gauge, anda special “type” called Untyped. Use the latter if you are not sure if themirrored metric is a Counter or a Gauge. Creation of the Metric instancehappens in the Collect method. The Describe method has to return separateDesc instances, representative of the “throw-away” metrics to be createdlater. NewDesc comes in handy to create those Desc instances. Alternatively,you could return no Desc at all, which will mark the Collector “unchecked”.No checks are performed at registration time, but metric consistency willstill be ensured at scrape time, i.e. any inconsistencies will lead to scrapeerrors. Thus, with unchecked Collectors, the responsibility to not collectmetrics that lead to inconsistencies in the total scrape result lies with theimplementer of the Collector. While this is not a desirable state, it issometimes necessary. The typical use case is a situation where the exactmetrics to be returned by a Collector cannot be predicted at registrationtime, but the implementer has sufficient knowledge of the whole system toguarantee metric consistency.

The Collector example illustrates the use case. You can also look at thesource code of the processCollector (mirroring process metrics), thegoCollector (mirroring Go metrics), or the expvarCollector (mirroring expvarmetrics) as examples that are used in this package itself.

If you just need to call a function to get a single float value to collect asa metric, GaugeFunc, CounterFunc, or UntypedFunc might be interestingshortcuts.

Advanced Uses of the Registry¶

While MustRegister is the by far most common way of registering a Collector,sometimes you might want to handle the errors the registration might cause.As suggested by the name, MustRegister panics if an error occurs. With theRegister function, the error is returned and can be handled.

An error is returned if the registered Collector is incompatible orinconsistent with already registered metrics. The registry aims forconsistency of the collected metrics according to the Prometheus data model.Inconsistencies are ideally detected at registration time, not at collecttime. The former will usually be detected at start-up time of a program,while the latter will only happen at scrape time, possibly not even on thefirst scrape if the inconsistency only becomes relevant later. That is themain reason why a Collector and a Metric have to describe themselves to theregistry.

So far, everything we did operated on the so-called default registry, as itcan be found in the global DefaultRegisterer variable. With NewRegistry, youcan create a custom registry, or you can even implement the Registerer orGatherer interfaces yourself. The methods Register and Unregister work in thesame way on a custom registry as the global functions Register and Unregisteron the default registry.

There are a number of uses for custom registries: You can use registries withspecial properties, see NewPedanticRegistry. You can avoid global state, asit is imposed by the DefaultRegisterer. You can use multiple registries atthe same time to expose different metrics in different ways. You can useseparate registries for testing purposes.

Also note that the DefaultRegisterer comes registered with a Collector for Goruntime metrics (via NewGoCollector) and a Collector for process metrics (viaNewProcessCollector). With a custom registry, you are in control and decideyourself about the Collectors to register.

HTTP Exposition¶

The Registry implements the Gatherer interface. The caller of the Gathermethod can then expose the gathered metrics in some way. Usually, the metricsare served via HTTP on the /metrics endpoint. That's happening in the exampleabove. The tools to expose metrics via HTTP are in the promhttp sub-package.

Pushing to the Pushgateway¶

Function for pushing to the Pushgateway can be found in the push sub-package.

Graphite Bridge¶

Functions and examples to push metrics from a Gatherer to Graphite can befound in the graphite sub-package.

Other Means of Exposition¶

More ways of exposing metrics can easily be added by following the approachesof the existing implementations.

Index¶

Examples¶

Constants¶

View Source

const (// DefMaxAge is the default duration for which observations stay// relevant.DefMaxAgetime.Duration = 10 *time.Minute// DefAgeBuckets is the default number of buckets used to calculate the// age of observations.DefAgeBuckets = 5// DefBufCap is the standard buffer size for collecting Summary observations.DefBufCap = 500)

Default values for SummaryOpts.

View Source

const DefNativeHistogramZeroThreshold = 2.938735877055719e-39

DefNativeHistogramZeroThreshold is the default value forNativeHistogramZeroThreshold in the HistogramOpts.

The value is 2^-128 (or 0.5*2^-127 in the actual IEEE 754 representation),which is a bucket boundary at all possible resolutions.

View Source

const ExemplarMaxRunes = 128

ExemplarMaxRunes is the max total number of runes allowed in exemplar labels.

View Source

const NativeHistogramZeroThresholdZero = -1

NativeHistogramZeroThresholdZero can be used as NativeHistogramZeroThresholdin the HistogramOpts to create a zero bucket of width zero, i.e. a zerobucket that only receives observations of precisely zero.

Variables¶

View Source

var (DefaultRegistererRegisterer = defaultRegistryDefaultGathererGatherer   = defaultRegistry)

DefaultRegisterer and DefaultGatherer are the implementations of theRegisterer and Gatherer interface a number of convenience functions in thispackage act on. Initially, both variables point to the same Registry, whichhas a process collector (currently on Linux only, see NewProcessCollector)and a Go collector (see NewGoCollector, in particular the note aboutstop-the-world implication with Go versions older than 1.9) alreadyregistered. This approach to keep default instances as global state mirrorsthe approach of other packages in the Go standard library. Note that thereare caveats. Change the variables with caution and only if you understand theconsequences. Users who want to avoid global state altogether should not usethe convenience functions and act on custom instances instead.

View Source

var (CounterMetricTypePtr = func() *dto.MetricType { d :=dto.MetricType_COUNTER; return &d }()GaugeMetricTypePtr   = func() *dto.MetricType { d :=dto.MetricType_GAUGE; return &d }()UntypedMetricTypePtr = func() *dto.MetricType { d :=dto.MetricType_UNTYPED; return &d }())

View Source

var DefBuckets = []float64{.005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10}

DefBuckets are the default Histogram buckets. The default buckets aretailored to broadly measure the response time (in seconds) of a networkservice. Most likely, however, you will be required to define bucketscustomized to your use case.

View Source

var V2 = v2{}

V2 is a struct that can be referenced to access experimental API that mightbe present in v2 of client golang someday. It offers extended functionalityof v1 with slightly changed API. It is acceptable to use some pieces from v1and e.g `prometheus.NewGauge` and some from v2 e.g. `prometheus.V2.NewDesc`in the same codebase.

Functions¶

funcBuildFQName ¶

func BuildFQName(namespace, subsystem, namestring)string

BuildFQName joins the given three name components by "_". Empty namecomponents are ignored. If the name parameter itself is empty, an emptystring is returned, no matter what. Metric implementations included in thislibrary use this function internally to generate the fully-qualified metricname from the name component in their Opts. Users of the library will onlyneed this function if they implement their own Metric or instantiate a Desc(with NewDesc) directly.

funcDescribeByCollect ¶added inv0.9.0

func DescribeByCollect(cCollector, descs chan<- *Desc)

DescribeByCollect is a helper to implement the Describe method of a customCollector. It collects the metrics from the provided Collector and sendstheir descriptors to the provided channel.

If a Collector collects the same metrics throughout its lifetime, itsDescribe method can simply be implemented as:

func (c customCollector) Describe(ch chan<- *Desc) {DescribeByCollect(c, ch)}

However, this will not work if the metrics collected change dynamically overthe lifetime of the Collector in a way that their combined set of descriptorschanges as well. The shortcut implementation will then violate the contractof the Describe method. If a Collector sometimes collects no metrics at all(for example vectors like CounterVec, GaugeVec, etc., which only collectmetrics after a metric with a fully specified label set has been accessed),it might even get registered as an unchecked Collector (cf. the Registermethod of the Registerer interface). Hence, only use this shortcutimplementation of Describe if you are certain to fulfill the contract.

The Collector example demonstrates a use of DescribeByCollect.

funcExponentialBuckets ¶

func ExponentialBuckets(start, factorfloat64, countint) []float64

ExponentialBuckets creates 'count' regular buckets, where the lowest buckethas an upper bound of 'start' and each following bucket's upper bound is'factor' times the previous bucket's upper bound. The final +Inf bucket isnot counted and not included in the returned slice. The returned slice ismeant to be used for the Buckets field of HistogramOpts.

The function panics if 'count' is 0 or negative, if 'start' is 0 or negative,or if 'factor' is less than or equal 1.

funcExponentialBucketsRange ¶added inv0.12.1

func ExponentialBucketsRange(minBucket, maxBucketfloat64, countint) []float64

ExponentialBucketsRange creates 'count' buckets, where the lowest bucket is'min' and the highest bucket is 'max'. The final +Inf bucket is not countedand not included in the returned slice. The returned slice is meant to beused for the Buckets field of HistogramOpts.

The function panics if 'count' is 0 or negative, if 'min' is 0 or negative.

funcLinearBuckets ¶

func LinearBuckets(start, widthfloat64, countint) []float64

LinearBuckets creates 'count' regular buckets, each 'width' wide, where thelowest bucket has an upper bound of 'start'. The final +Inf bucket is notcounted and not included in the returned slice. The returned slice is meantto be used for the Buckets field of HistogramOpts.

The function panics if 'count' is zero or negative.

funcMakeLabelPairs ¶added inv0.12.1

func MakeLabelPairs(desc *Desc, labelValues []string) []*dto.LabelPair

MakeLabelPairs is a helper function to create protobuf LabelPairs from thevariable and constant labels in the provided Desc. The values for thevariable labels are defined by the labelValues slice, which must be in thesame order as the corresponding variable labels in the Desc.

This function is only needed for custom Metric implementations. See MetricVecexample.

funcMustRegister ¶

func MustRegister(cs ...Collector)

MustRegister registers the provided Collectors with the DefaultRegisterer andpanics if any error occurs.

MustRegister is a shortcut for DefaultRegisterer.MustRegister(cs...). Seethere for more details.

funcNewPidFileFn ¶added inv0.12.1

func NewPidFileFn(pidFilePathstring) func() (int,error)

NewPidFileFn returns a function that retrieves a pid from the specified file.It is meant to be used for the PidFn field in ProcessCollectorOpts.

funcRegister ¶

func Register(cCollector)error

Example¶

package mainimport ("fmt""net/http""github.com/prometheus/client_golang/prometheus""github.com/prometheus/client_golang/prometheus/promhttp")func main() {// Imagine you have a worker pool and want to count the tasks completed.taskCounter := prometheus.NewCounter(prometheus.CounterOpts{Subsystem: "worker_pool",Name:      "completed_tasks_total",Help:      "Total number of tasks completed.",})// This will register fine.if err := prometheus.Register(taskCounter); err != nil {fmt.Println(err)} else {fmt.Println("taskCounter registered.")}// Don't forget to tell the HTTP server about the Prometheus handler.// (In a real program, you still need to start the HTTP server...)http.Handle("/metrics", promhttp.Handler())// Now you can start workers and give every one of them a pointer to// taskCounter and let it increment it whenever it completes a task.taskCounter.Inc() // This has to happen somewhere in the worker code.// But wait, you want to see how individual workers perform. So you need// a vector of counters, with one element for each worker.taskCounterVec := prometheus.NewCounterVec(prometheus.CounterOpts{Subsystem: "worker_pool",Name:      "completed_tasks_total",Help:      "Total number of tasks completed.",},[]string{"worker_id"},)// Registering will fail because we already have a metric of that name.if err := prometheus.Register(taskCounterVec); err != nil {fmt.Println("taskCounterVec not registered:", err)} else {fmt.Println("taskCounterVec registered.")}// To fix, first unregister the old taskCounter.if prometheus.Unregister(taskCounter) {fmt.Println("taskCounter unregistered.")}// Try registering taskCounterVec again.if err := prometheus.Register(taskCounterVec); err != nil {fmt.Println("taskCounterVec not registered:", err)} else {fmt.Println("taskCounterVec registered.")}// Bummer! Still doesn't work.// Prometheus will not allow you to ever export metrics with// inconsistent help strings or label names. After unregistering, the// unregistered metrics will cease to show up in the /metrics HTTP// response, but the registry still remembers that those metrics had// been exported before. For this example, we will now choose a// different name. (In a real program, you would obviously not export// the obsolete metric in the first place.)taskCounterVec = prometheus.NewCounterVec(prometheus.CounterOpts{Subsystem: "worker_pool",Name:      "completed_tasks_by_id",Help:      "Total number of tasks completed.",},[]string{"worker_id"},)if err := prometheus.Register(taskCounterVec); err != nil {fmt.Println("taskCounterVec not registered:", err)} else {fmt.Println("taskCounterVec registered.")}// Finally it worked!// The workers have to tell taskCounterVec their id to increment the// right element in the metric vector.taskCounterVec.WithLabelValues("42").Inc() // Code from worker 42.// Each worker could also keep a reference to their own counter element// around. Pick the counter at initialization time of the worker.myCounter := taskCounterVec.WithLabelValues("42") // From worker 42 initialization code.myCounter.Inc()                                   // Somewhere in the code of that worker.// Note that something like WithLabelValues("42", "spurious arg") would// panic (because you have provided too many label values). If you want// to get an error instead, use GetMetricWithLabelValues(...) instead.notMyCounter, err := taskCounterVec.GetMetricWithLabelValues("42", "spurious arg")if err != nil {fmt.Println("Worker initialization failed:", err)}if notMyCounter == nil {fmt.Println("notMyCounter is nil.")}// A different (and somewhat tricky) approach is to use// ConstLabels. ConstLabels are pairs of label names and label values// that never change. Each worker creates and registers an own Counter// instance where the only difference is in the value of the// ConstLabels. Those Counters can all be registered because the// different ConstLabel values guarantee that each worker will increment// a different Counter metric.counterOpts := prometheus.CounterOpts{Subsystem:   "worker_pool",Name:        "completed_tasks",Help:        "Total number of tasks completed.",ConstLabels: prometheus.Labels{"worker_id": "42"},}taskCounterForWorker42 := prometheus.NewCounter(counterOpts)if err := prometheus.Register(taskCounterForWorker42); err != nil {fmt.Println("taskCounterVForWorker42 not registered:", err)} else {fmt.Println("taskCounterForWorker42 registered.")}// Obviously, in real code, taskCounterForWorker42 would be a member// variable of a worker struct, and the "42" would be retrieved with a// GetId() method or something. The Counter would be created and// registered in the initialization code of the worker.// For the creation of the next Counter, we can recycle// counterOpts. Just change the ConstLabels.counterOpts.ConstLabels = prometheus.Labels{"worker_id": "2001"}taskCounterForWorker2001 := prometheus.NewCounter(counterOpts)if err := prometheus.Register(taskCounterForWorker2001); err != nil {fmt.Println("taskCounterVForWorker2001 not registered:", err)} else {fmt.Println("taskCounterForWorker2001 registered.")}taskCounterForWorker2001.Inc()taskCounterForWorker42.Inc()taskCounterForWorker2001.Inc()// Yet another approach would be to turn the workers themselves into// Collectors and register them. See the Collector example for details.}

Output:taskCounter registered.taskCounterVec not registered: a previously registered descriptor with the same fully-qualified name as Desc{fqName: "worker_pool_completed_tasks_total", help: "Total number of tasks completed.", constLabels: {}, variableLabels: {worker_id}} has different label names or a different help stringtaskCounter unregistered.taskCounterVec not registered: a previously registered descriptor with the same fully-qualified name as Desc{fqName: "worker_pool_completed_tasks_total", help: "Total number of tasks completed.", constLabels: {}, variableLabels: {worker_id}} has different label names or a different help stringtaskCounterVec registered.Worker initialization failed: inconsistent label cardinality: expected 1 label values but got 2 in []string{"42", "spurious arg"}notMyCounter is nil.taskCounterForWorker42 registered.taskCounterForWorker2001 registered.

funcUnregister ¶

func Unregister(cCollector)bool

Unregister removes the registration of the provided Collector from theDefaultRegisterer.

Unregister is a shortcut for DefaultRegisterer.Unregister(c). See there formore details.

funcWriteToTextfile ¶added inv0.9.1

func WriteToTextfile(filenamestring, gGatherer)error

WriteToTextfile calls Gather on the provided Gatherer, encodes the result in thePrometheus text format, and writes it to a temporary file. Upon success, thetemporary file is renamed to the provided filename.

This is intended for use with the textfile collector of the node exporter.Note that the node exporter expects the filename to be suffixed with ".prom".

Types¶

typeAlreadyRegisteredError ¶

type AlreadyRegisteredError struct {ExistingCollector, NewCollectorCollector}

AlreadyRegisteredError is returned by the Register method if the Collector tobe registered has already been registered before, or a different Collectorthat collects the same metrics has been registered before. Registration failsin that case, but you can detect from the kind of error what hashappened. The error contains fields for the existing Collector and the(rejected) new Collector that equals the existing one. This can be used tofind out if an equal Collector has been registered before and switch over tousing the old one, as demonstrated in the example.

Example¶

package mainimport ("errors""github.com/prometheus/client_golang/prometheus")func main() {reqCounter := prometheus.NewCounter(prometheus.CounterOpts{Name: "requests_total",Help: "The total number of requests served.",})if err := prometheus.Register(reqCounter); err != nil {are := &prometheus.AlreadyRegisteredError{}if errors.As(err, are) {// A counter for that metric has been registered before.// Use the old counter from now on.reqCounter = are.ExistingCollector.(prometheus.Counter)} else {// Something else went wrong!panic(err)}}reqCounter.Inc()}

func (AlreadyRegisteredError)Error ¶

func (errAlreadyRegisteredError) Error()string

typeCollector ¶

type Collector interface {// Describe sends the super-set of all possible descriptors of metrics// collected by this Collector to the provided channel and returns once// the last descriptor has been sent. The sent descriptors fulfill the// consistency and uniqueness requirements described in the Desc// documentation.//// It is valid if one and the same Collector sends duplicate// descriptors. Those duplicates are simply ignored. However, two// different Collectors must not send duplicate descriptors.//// Sending no descriptor at all marks the Collector as “unchecked”,// i.e. no checks will be performed at registration time, and the// Collector may yield any Metric it sees fit in its Collect method.//// This method idempotently sends the same descriptors throughout the// lifetime of the Collector. It may be called concurrently and// therefore must be implemented in a concurrency safe way.//// If a Collector encounters an error while executing this method, it// must send an invalid descriptor (created with NewInvalidDesc) to// signal the error to the registry.Describe(chan<- *Desc)// Collect is called by the Prometheus registry when collecting// metrics. The implementation sends each collected metric via the// provided channel and returns once the last metric has been sent. The// descriptor of each sent metric is one of those returned by Describe// (unless the Collector is unchecked, see above). Returned metrics that// share the same descriptor must differ in their variable label// values.//// This method may be called concurrently and must therefore be// implemented in a concurrency safe way. Blocking occurs at the expense// of total performance of rendering all registered metrics. Ideally,// Collector implementations support concurrent readers.Collect(chan<-Metric)}

Collector is the interface implemented by anything that can be used byPrometheus to collect metrics. A Collector has to be registered forcollection. See Registerer.Register.

The stock metrics provided by this package (Gauge, Counter, Summary,Histogram, Untyped) are also Collectors (which only ever collect one metric,namely itself). An implementer of Collector may, however, collect multiplemetrics in a coordinated fashion and/or create metrics on the fly. Examplesfor collectors already implemented in this library are the metric vectors(i.e. collection of multiple instances of the same Metric but with differentlabel values) like GaugeVec or SummaryVec, and the ExpvarCollector.

Example¶

package mainimport ("log""net/http""github.com/prometheus/client_golang/prometheus""github.com/prometheus/client_golang/prometheus/promhttp")// ClusterManager is an example for a system that might have been built without// Prometheus in mind. It models a central manager of jobs running in a// cluster. Thus, we implement a custom Collector called// ClusterManagerCollector, which collects information from a ClusterManager// using its provided methods and turns them into Prometheus Metrics for// collection.//// An additional challenge is that multiple instances of the ClusterManager are// run within the same binary, each in charge of a different zone. We need to// make use of wrapping Registerers to be able to register each// ClusterManagerCollector instance with Prometheus.type ClusterManager struct {Zone string// Contains many more fields not listed in this example.}// ReallyExpensiveAssessmentOfTheSystemState is a mock for the data gathering a// real cluster manager would have to do. Since it may actually be really// expensive, it must only be called once per collection. This implementation,// obviously, only returns some made-up data.func (c *ClusterManager) ReallyExpensiveAssessmentOfTheSystemState() (oomCountByHost map[string]int, ramUsageByHost map[string]float64,) {// Just example fake data.oomCountByHost = map[string]int{"foo.example.org": 42,"bar.example.org": 2001,}ramUsageByHost = map[string]float64{"foo.example.org": 6.023e23,"bar.example.org": 3.14,}return}// ClusterManagerCollector implements the Collector interface.type ClusterManagerCollector struct {ClusterManager *ClusterManager}// Descriptors used by the ClusterManagerCollector below.var (oomCountDesc = prometheus.NewDesc("clustermanager_oom_crashes_total","Number of OOM crashes.",[]string{"host"}, nil,)ramUsageDesc = prometheus.NewDesc("clustermanager_ram_usage_bytes","RAM usage as reported to the cluster manager.",[]string{"host"}, nil,))// Describe is implemented with DescribeByCollect. That's possible because the// Collect method will always return the same two metrics with the same two// descriptors.func (cc ClusterManagerCollector) Describe(ch chan<- *prometheus.Desc) {prometheus.DescribeByCollect(cc, ch)}// Collect first triggers the ReallyExpensiveAssessmentOfTheSystemState. Then it// creates constant metrics for each host on the fly based on the returned data.//// Note that Collect could be called concurrently, so we depend on// ReallyExpensiveAssessmentOfTheSystemState to be concurrency-safe.func (cc ClusterManagerCollector) Collect(ch chan<- prometheus.Metric) {oomCountByHost, ramUsageByHost := cc.ClusterManager.ReallyExpensiveAssessmentOfTheSystemState()for host, oomCount := range oomCountByHost {ch <- prometheus.MustNewConstMetric(oomCountDesc,prometheus.CounterValue,float64(oomCount),host,)}for host, ramUsage := range ramUsageByHost {ch <- prometheus.MustNewConstMetric(ramUsageDesc,prometheus.GaugeValue,ramUsage,host,)}}// NewClusterManager first creates a Prometheus-ignorant ClusterManager// instance. Then, it creates a ClusterManagerCollector for the just created// ClusterManager. Finally, it registers the ClusterManagerCollector with a// wrapping Registerer that adds the zone as a label. In this way, the metrics// collected by different ClusterManagerCollectors do not collide.func NewClusterManager(zone string, reg prometheus.Registerer) *ClusterManager {c := &ClusterManager{Zone: zone,}cc := ClusterManagerCollector{ClusterManager: c}prometheus.WrapRegistererWith(prometheus.Labels{"zone": zone}, reg).MustRegister(cc)return c}func main() {// Since we are dealing with custom Collector implementations, it might// be a good idea to try it out with a pedantic registry.reg := prometheus.NewPedanticRegistry()// Construct cluster managers. In real code, we would assign them to// variables to then do something with them.NewClusterManager("db", reg)NewClusterManager("ca", reg)// Add the standard process and Go metrics to the custom registry.reg.MustRegister(prometheus.NewProcessCollector(prometheus.ProcessCollectorOpts{}),prometheus.NewGoCollector(),)http.Handle("/metrics", promhttp.HandlerFor(reg, promhttp.HandlerOpts{}))log.Fatal(http.ListenAndServe(":8080", nil))}

funcNewBuildInfoCollectordeprecatedadded inv0.9.4

func NewBuildInfoCollector()Collector

NewBuildInfoCollector is the obsolete version of collectors.NewBuildInfoCollector.See there for documentation.

Deprecated: Use collectors.NewBuildInfoCollector instead.

funcNewExpvarCollectordeprecated

func NewExpvarCollector(exports map[string]*Desc)Collector

NewExpvarCollector is the obsolete version of collectors.NewExpvarCollector.See there for documentation.

Deprecated: Use collectors.NewExpvarCollector instead.

Example¶

expvarCollector := prometheus.NewExpvarCollector(map[string]*prometheus.Desc{"memstats": prometheus.NewDesc("expvar_memstats","All numeric memstats as one metric family. Not a good role-model, actually... ;-)",[]string{"type"}, nil,),"lone-int": prometheus.NewDesc("expvar_lone_int","Just an expvar int as an example.",nil, nil,),"http-request-map": prometheus.NewDesc("expvar_http_request_total","How many http requests processed, partitioned by status code and http method.",[]string{"code", "method"}, nil,),})prometheus.MustRegister(expvarCollector)// The Prometheus part is done here. But to show that this example is// doing anything, we have to manually export something via expvar.  In// real-life use-cases, some library would already have exported via// expvar what we want to re-export as Prometheus metrics.expvar.NewInt("lone-int").Set(42)expvarMap := expvar.NewMap("http-request-map")var (expvarMap1, expvarMap2                             expvar.MapexpvarInt11, expvarInt12, expvarInt21, expvarInt22 expvar.Int)expvarMap1.Init()expvarMap2.Init()expvarInt11.Set(3)expvarInt12.Set(13)expvarInt21.Set(11)expvarInt22.Set(212)expvarMap1.Set("POST", &expvarInt11)expvarMap1.Set("GET", &expvarInt12)expvarMap2.Set("POST", &expvarInt21)expvarMap2.Set("GET", &expvarInt22)expvarMap.Set("404", &expvarMap1)expvarMap.Set("200", &expvarMap2)// Results in the following expvar map:// "http-request-count": {"200": {"POST": 11, "GET": 212}, "404": {"POST": 3, "GET": 13}}// Let's see what the scrape would yield, but exclude the memstats metrics.metricStrings := []string{}metric := dto.Metric{}metricChan := make(chan prometheus.Metric)go func() {expvarCollector.Collect(metricChan)close(metricChan)}()for m := range metricChan {if !strings.Contains(m.Desc().String(), "expvar_memstats") {metric.Reset()m.Write(&metric)metricStrings = append(metricStrings, toNormalizedJSON(&metric))}}sort.Strings(metricStrings)for _, s := range metricStrings {fmt.Println(s)}

Output:{"label":[{"name":"code","value":"200"},{"name":"method","value":"GET"}],"untyped":{"value":212}}{"label":[{"name":"code","value":"200"},{"name":"method","value":"POST"}],"untyped":{"value":11}}{"label":[{"name":"code","value":"404"},{"name":"method","value":"GET"}],"untyped":{"value":13}}{"label":[{"name":"code","value":"404"},{"name":"method","value":"POST"}],"untyped":{"value":3}}{"untyped":{"value":42}}

funcNewGoCollectordeprecated

func NewGoCollector(opts ...func(o *internal.GoCollectorOptions))Collector

NewGoCollector is the obsolete version of collectors.NewGoCollector.See there for documentation.

Deprecated: Use collectors.NewGoCollector instead.

funcNewProcessCollectordeprecated

func NewProcessCollector(optsProcessCollectorOpts)Collector

NewProcessCollector is the obsolete version of collectors.NewProcessCollector.See there for documentation.

Deprecated: Use collectors.NewProcessCollector instead.

funcWrapCollectorWith ¶added inv1.23.0

func WrapCollectorWith(labelsLabels, cCollector)Collector

WrapCollectorWith returns a Collector wrapping the provided Collector. Thewrapped Collector will add the provided Labels to all Metrics it collects (asConstLabels). The Metrics collected by the unmodified Collector must notduplicate any of those labels.

WrapCollectorWith can be useful to work with multiple instances of a thirdparty library that does not expose enough flexibility on the lifecycle of itsregistered metrics.For example, let's say you have a foo.New(reg Registerer) constructor thatregisters metrics but never unregisters them, and you want to create multipleinstances of foo.Foo with different labels.The way to achieve that, is to create a new Registry, pass it to foo.New,then use WrapCollectorWith to wrap that Registry with the desired labels andregister that as a collector in your main Registry.Then you can un-register the wrapped collector effectively un-registering themetrics registered by foo.New.

Example¶

Using WrapCollectorWith to un-register metrics registered by a third party lib.newThirdPartyLibFoo illustrates a constructor from a third-party lib that doesnot expose any way to un-register metrics.

reg := prometheus.NewRegistry()// We want to create two instances of thirdPartyLibFoo, each one wrapped with// its "instance" label.firstReg := prometheus.NewRegistry()_ = newThirdPartyLibFoo(firstReg)firstCollector := prometheus.WrapCollectorWith(prometheus.Labels{"instance": "first"}, firstReg)reg.MustRegister(firstCollector)secondReg := prometheus.NewRegistry()_ = newThirdPartyLibFoo(secondReg)secondCollector := prometheus.WrapCollectorWith(prometheus.Labels{"instance": "second"}, secondReg)reg.MustRegister(secondCollector)// So far we have illustrated that we can create two instances of thirdPartyLibFoo,// wrapping each one's metrics with some const label.// This is something we could've achieved by doing:// newThirdPartyLibFoo(prometheus.WrapRegistererWith(prometheus.Labels{"instance": "first"}, reg))metricFamilies, err := reg.Gather()if err != nil {panic("unexpected behavior of registry")}fmt.Println("Both instances:")fmt.Println(toNormalizedJSON(sanitizeMetricFamily(metricFamilies[0])))// Now we want to unregister first Foo's metrics, and then register them again.// This is not possible by passing a wrapped Registerer to newThirdPartyLibFoo,// because we have already lost track of the registered Collectors,// however since we've collected Foo's metrics in it's own Registry, and we have registered that// as a specific Collector, we can now de-register them:unregistered := reg.Unregister(firstCollector)if !unregistered {panic("unexpected behavior of registry")}metricFamilies, err = reg.Gather()if err != nil {panic("unexpected behavior of registry")}fmt.Println("First unregistered:")fmt.Println(toNormalizedJSON(sanitizeMetricFamily(metricFamilies[0])))// Now we can create another instance of Foo with {instance: "first"} label again.firstRegAgain := prometheus.NewRegistry()_ = newThirdPartyLibFoo(firstRegAgain)firstCollectorAgain := prometheus.WrapCollectorWith(prometheus.Labels{"instance": "first"}, firstRegAgain)reg.MustRegister(firstCollectorAgain)metricFamilies, err = reg.Gather()if err != nil {panic("unexpected behavior of registry")}fmt.Println("Both again:")fmt.Println(toNormalizedJSON(sanitizeMetricFamily(metricFamilies[0])))

Output:Both instances:{"name":"foo","help":"Registered forever.","type":"GAUGE","metric":[{"label":[{"name":"instance","value":"first"}],"gauge":{"value":1}},{"label":[{"name":"instance","value":"second"}],"gauge":{"value":1}}]}First unregistered:{"name":"foo","help":"Registered forever.","type":"GAUGE","metric":[{"label":[{"name":"instance","value":"second"}],"gauge":{"value":1}}]}Both again:{"name":"foo","help":"Registered forever.","type":"GAUGE","metric":[{"label":[{"name":"instance","value":"first"}],"gauge":{"value":1}},{"label":[{"name":"instance","value":"second"}],"gauge":{"value":1}}]}

funcWrapCollectorWithPrefix ¶added inv1.23.0

func WrapCollectorWithPrefix(prefixstring, cCollector)Collector

WrapCollectorWithPrefix returns a Collector wrapping the provided Collector. Thewrapped Collector will add the provided prefix to the name of all Metrics it collects.

See the documentation of WrapCollectorWith for more details on the use case.

typeCollectorFunc ¶added inv1.22.0

type CollectorFunc func(chan<-Metric)

CollectorFunc is a convenient way to implement a Prometheus Collectorwithout interface boilerplate.This implementation is based on DescribeByCollect method.familiarize yourself to it before using.

Example¶

Using CollectorFunc that registers the metric info for the HTTP requests.

desc := prometheus.NewDesc("http_requests_info","Information about the received HTTP requests.",[]string{"code", "method"},nil,)// Example 1: 42 GET requests with 200 OK status code.collector := prometheus.CollectorFunc(func(ch chan<- prometheus.Metric) {ch <- prometheus.MustNewConstMetric(desc,prometheus.CounterValue, // Metric type: Counter42,                      // Value"200",                   // Label value: HTTP status code"GET",                   // Label value: HTTP method)// Example 2: 15 POST requests with 404 Not Found status code.ch <- prometheus.MustNewConstMetric(desc,prometheus.CounterValue,15,"404","POST",)})prometheus.MustRegister(collector)// Just for demonstration, let's check the state of the metric by registering// it with a custom registry and then let it collect the metrics.reg := prometheus.NewRegistry()reg.MustRegister(collector)metricFamilies, err := reg.Gather()if err != nil || len(metricFamilies) != 1 {panic("unexpected behavior of custom test registry")}fmt.Println(toNormalizedJSON(sanitizeMetricFamily(metricFamilies[0])))

Output:{"name":"http_requests_info","help":"Information about the received HTTP requests.","type":"COUNTER","metric":[{"label":[{"name":"code","value":"200"},{"name":"method","value":"GET"}],"counter":{"value":42}},{"label":[{"name":"code","value":"404"},{"name":"method","value":"POST"}],"counter":{"value":15}}]}

func (CollectorFunc)Collect ¶added inv1.22.0

func (fCollectorFunc) Collect(ch chan<-Metric)

Collect calls the defined CollectorFunc function with the provided Metrics channel

func (CollectorFunc)Describe ¶added inv1.22.0

func (fCollectorFunc) Describe(ch chan<- *Desc)

Describe sends the descriptor information using DescribeByCollect

typeConstrainableLabels ¶added inv1.15.0

type ConstrainableLabels interface {// contains filtered or unexported methods}

ConstrainableLabels is an interface that allows creating of labels that canbe optionally constrained.

prometheus.V2().NewCounterVec(CounterVecOpts{  CounterOpts: {...}, // Usual CounterOpts fields  VariableLabels: []ConstrainedLabels{    {Name: "A"},    {Name: "B", Constraint: func(v string) string { ... }},  },})

typeConstrainedLabel ¶added inv1.15.0

type ConstrainedLabel struct {NamestringConstraintLabelConstraint}

ConstrainedLabels represents a label name and its constrain functionto normalize label values. This type is commonly used when constructingmetric vector Collectors.

typeConstrainedLabels ¶added inv1.15.0

type ConstrainedLabels []ConstrainedLabel

ConstrainedLabels represents a collection of label name -> constrain functionto normalize label values. This type is commonly used when constructingmetric vector Collectors.

typeCounter ¶

type Counter interface {MetricCollector// Inc increments the counter by 1. Use Add to increment it by arbitrary// non-negative values.Inc()// Add adds the given value to the counter. It panics if the value is <// 0.Add(float64)}

Counter is a Metric that represents a single numerical value that only evergoes up. That implies that it cannot be used to count items whose number canalso go down, e.g. the number of currently running goroutines. Those"counters" are represented by Gauges.

A Counter is typically used to count requests served, tasks completed, errorsoccurred, etc.

To create Counter instances, use NewCounter.

funcNewCounter ¶

func NewCounter(optsCounterOpts)Counter

NewCounter creates a new Counter based on the provided CounterOpts.

The returned implementation also implements ExemplarAdder. It is safe toperform the corresponding type assertion.

The returned implementation tracks the counter value in two separatevariables, a float64 and a uint64. The latter is used to track calls of theInc method and calls of the Add method with a value that can be representedas a uint64. This allows atomic increments of the counter with optimalperformance. (It is common to have an Inc call in very hot execution paths.)Both internal tracking values are added up in the Write method. This has tobe taken into account when it comes to precision and overflow behavior.

typeCounterFunc ¶

type CounterFunc interface {MetricCollector}

CounterFunc is a Counter whose value is determined at collect time by calling aprovided function.

To create CounterFunc instances, use NewCounterFunc.

funcNewCounterFunc ¶

func NewCounterFunc(optsCounterOpts, function func()float64)CounterFunc

NewCounterFunc creates a new CounterFunc based on the providedCounterOpts. The value reported is determined by calling the given functionfrom within the Write method. Take into account that metric collection mayhappen concurrently. If that results in concurrent calls to Write, like inthe case where a CounterFunc is directly registered with Prometheus, theprovided function must be concurrency-safe. The function should also honorthe contract for a Counter (values only go up, not down), but compliance willnot be checked.

Check out the ExampleGaugeFunc examples for the similar GaugeFunc.

typeCounterOpts ¶

type CounterOptsOpts

CounterOpts is an alias for Opts. See there for doc comments.

typeCounterVec ¶

type CounterVec struct {*MetricVec}

CounterVec is a Collector that bundles a set of Counters that all share thesame Desc, but have different values for their variable labels. This is usedif you want to count the same thing partitioned by various dimensions(e.g. number of HTTP requests, partitioned by response code andmethod). Create instances with NewCounterVec.

Example¶

httpReqs := prometheus.NewCounterVec(prometheus.CounterOpts{Name: "http_requests_total",Help: "How many HTTP requests processed, partitioned by status code and HTTP method.",},[]string{"code", "method"},)prometheus.MustRegister(httpReqs)httpReqs.WithLabelValues("404", "POST").Add(42)// If you have to access the same set of labels very frequently, it// might be good to retrieve the metric only once and keep a handle to// it. But beware of deletion of that metric, see below!m := httpReqs.WithLabelValues("200", "GET")for i := 0; i < 1000000; i++ {m.Inc()}// Delete a metric from the vector. If you have previously kept a handle// to that metric (as above), future updates via that handle will go// unseen (even if you re-create a metric with the same label set// later).httpReqs.DeleteLabelValues("200", "GET")// Same thing with the more verbose Labels syntax.httpReqs.Delete(prometheus.Labels{"method": "GET", "code": "200"})// Just for demonstration, let's check the state of the counter vector// by registering it with a custom registry and then let it collect the// metrics.reg := prometheus.NewRegistry()reg.MustRegister(httpReqs)metricFamilies, err := reg.Gather()if err != nil || len(metricFamilies) != 1 {panic("unexpected behavior of custom test registry")}fmt.Println(toNormalizedJSON(sanitizeMetricFamily(metricFamilies[0])))

Output:{"name":"http_requests_total","help":"How many HTTP requests processed, partitioned by status code and HTTP method.","type":"COUNTER","metric":[{"label":[{"name":"code","value":"404"},{"name":"method","value":"POST"}],"counter":{"value":42,"createdTimestamp":"1970-01-01T00:00:10Z"}}]}

funcNewCounterVec ¶

func NewCounterVec(optsCounterOpts, labelNames []string) *CounterVec

NewCounterVec creates a new CounterVec based on the provided CounterOpts andpartitioned by the given label names.

func (*CounterVec)CurryWith ¶added inv0.9.0

func (v *CounterVec) CurryWith(labelsLabels) (*CounterVec,error)

CurryWith returns a vector curried with the provided labels, i.e. thereturned vector has those labels pre-set for all labeled operations performedon it. The cardinality of the curried vector is reduced accordingly. Theorder of the remaining labels stays the same (just with the curried labelstaken out of the sequence – which is relevant for the(GetMetric)WithLabelValues methods). It is possible to curry a curriedvector, but only with labels not yet used for currying before.

The metrics contained in the CounterVec are shared between the curried anduncurried vectors. They are just accessed differently. Curried and uncurriedvectors behave identically in terms of collection. Only one must beregistered with a given registry (usually the uncurried version). The Resetmethod deletes all metrics, even if called on a curried vector.

func (*CounterVec)GetMetricWith ¶

func (v *CounterVec) GetMetricWith(labelsLabels) (Counter,error)

GetMetricWith returns the Counter for the given Labels map (the label namesmust match those of the variable labels in Desc). If that label map isaccessed for the first time, a new Counter is created. Implications ofcreating a Counter without using it and keeping the Counter for later use arethe same as for GetMetricWithLabelValues.

An error is returned if the number and names of the Labels are inconsistentwith those of the variable labels in Desc (minus any curried labels).

This method is used for the same purpose asGetMetricWithLabelValues(...string). See there for pros and cons of the twomethods.

func (*CounterVec)GetMetricWithLabelValues ¶

func (v *CounterVec) GetMetricWithLabelValues(lvs ...string) (Counter,error)

GetMetricWithLabelValues returns the Counter for the given slice of labelvalues (same order as the variable labels in Desc). If that combination oflabel values is accessed for the first time, a new Counter is created.

It is possible to call this method without using the returned Counter to onlycreate the new Counter but leave it at its starting value 0. See also theSummaryVec example.

Keeping the Counter for later use is possible (and should be considered ifperformance is critical), but keep in mind that Reset, DeleteLabelValues andDelete can be used to delete the Counter from the CounterVec. In that case,the Counter will still exist, but it will not be exported anymore, even if aCounter with the same label values is created later.

An error is returned if the number of label values is not the same as thenumber of variable labels in Desc (minus any curried labels).

Note that for more than one label value, this method is prone to mistakescaused by an incorrect order of arguments. Consider GetMetricWith(Labels) asan alternative to avoid that type of mistake. For higher label numbers, thelatter has a much more readable (albeit more verbose) syntax, but it comeswith a performance overhead (for creating and processing the Labels map).See also the GaugeVec example.

func (*CounterVec)MustCurryWith ¶added inv0.9.0

func (v *CounterVec) MustCurryWith(labelsLabels) *CounterVec

MustCurryWith works as CurryWith but panics where CurryWith would havereturned an error.

func (*CounterVec)With ¶

func (v *CounterVec) With(labelsLabels)Counter

With works as GetMetricWith, but panics where GetMetricWithLabels would havereturned an error. Not returning an error allows shortcuts like

myVec.With(prometheus.Labels{"code": "404", "method": "GET"}).Add(42)

func (*CounterVec)WithLabelValues ¶

func (v *CounterVec) WithLabelValues(lvs ...string)Counter

WithLabelValues works as GetMetricWithLabelValues, but panics whereGetMetricWithLabelValues would have returned an error. Not returning anerror allows shortcuts like

myVec.WithLabelValues("404", "GET").Add(42)

typeCounterVecOpts ¶added inv1.15.0

type CounterVecOpts struct {CounterOpts// VariableLabels are used to partition the metric vector by the given set// of labels. Each label value will be constrained with the optional Constraint// function, if provided.VariableLabelsConstrainableLabels}

CounterVecOpts bundles the options to create a CounterVec metric.It is mandatory to set CounterOpts, see there for mandatory fields. VariableLabelsis optional and can safely be left to its default value.

typeDesc ¶

type Desc struct {// contains filtered or unexported fields}

Desc is the descriptor used by every Prometheus Metric. It is essentiallythe immutable meta-data of a Metric. The normal Metric implementationsincluded in this package manage their Desc under the hood. Users only have todeal with Desc if they use advanced features like the ExpvarCollector orcustom Collectors and Metrics.

Descriptors registered with the same registry have to fulfill certainconsistency and uniqueness criteria if they share the same fully-qualifiedname: They must have the same help string and the same label names (aka labeldimensions) in each, constLabels and variableLabels, but they must differ inthe values of the constLabels.

Descriptors that share the same fully-qualified names and the same labelvalues of their constLabels are considered equal.

Use NewDesc to create new Desc instances.

funcNewDesc ¶

func NewDesc(fqName, helpstring, variableLabels []string, constLabelsLabels) *Desc

NewDesc allocates and initializes a new Desc. Errors are recorded in the Descand will be reported on registration time. variableLabels and constLabels canbe nil if no such labels should be set. fqName must not be empty.

variableLabels only contain the label names. Their label values are variableand therefore not part of the Desc. (They are managed within the Metric.)

For constLabels, the label values are constant. Therefore, they are fullyspecified in the Desc. See the Collector example for a usage pattern.

funcNewInvalidDesc ¶

func NewInvalidDesc(errerror) *Desc

NewInvalidDesc returns an invalid descriptor, i.e. a descriptor with theprovided error set. If a collector returning such a descriptor is registered,registration will fail with the provided error. NewInvalidDesc can be used bya Collector to signal inability to describe itself.

func (*Desc)String ¶

func (d *Desc) String()string

typeExemplar ¶added inv1.13.0

type Exemplar struct {Valuefloat64LabelsLabels// Optional.// Default value (time.Time{}) indicates its empty, which should be// understood as time.Now() time at the moment of creation of metric.Timestamptime.Time}

Exemplar is easier to use, user-facing representation of *dto.Exemplar.

typeExemplarAdder ¶added inv0.12.1

type ExemplarAdder interface {AddWithExemplar(valuefloat64, exemplarLabels)}

ExemplarAdder is implemented by Counters that offer the option of adding avalue to the Counter together with an exemplar. Its AddWithExemplar methodworks like the Add method of the Counter interface but also replaces thecurrently saved exemplar (if any) with a new one, created from the providedvalue, the current time as timestamp, and the provided labels. Empty Labelswill lead to a valid (label-less) exemplar. But if Labels is nil, the currentexemplar is left in place. AddWithExemplar panics if the value is < 0, if anyof the provided labels are invalid, or if the provided labels contain morethan 128 runes in total.

typeExemplarObserver ¶added inv0.12.1

type ExemplarObserver interface {ObserveWithExemplar(valuefloat64, exemplarLabels)}

ExemplarObserver is implemented by Observers that offer the option ofobserving a value together with an exemplar. Its ObserveWithExemplar methodworks like the Observe method of an Observer but also replaces the currentlysaved exemplar (if any) with a new one, created from the provided value, thecurrent time as timestamp, and the provided Labels. Empty Labels will lead toa valid (label-less) exemplar. But if Labels is nil, the current exemplar isleft in place. ObserveWithExemplar panics if any of the provided labels areinvalid or if the provided labels contain more than 128 runes in total.

typeGatherer ¶

type Gatherer interface {// Gather calls the Collect method of the registered Collectors and then// gathers the collected metrics into a lexicographically sorted slice// of uniquely named MetricFamily protobufs. Gather ensures that the// returned slice is valid and self-consistent so that it can be used// for valid exposition. As an exception to the strict consistency// requirements described for metric.Desc, Gather will tolerate// different sets of label names for metrics of the same metric family.//// Even if an error occurs, Gather attempts to gather as many metrics as// possible. Hence, if a non-nil error is returned, the returned// MetricFamily slice could be nil (in case of a fatal error that// prevented any meaningful metric collection) or contain a number of// MetricFamily protobufs, some of which might be incomplete, and some// might be missing altogether. The returned error (which might be a// MultiError) explains the details. Note that this is mostly useful for// debugging purposes. If the gathered protobufs are to be used for// exposition in actual monitoring, it is almost always better to not// expose an incomplete result and instead disregard the returned// MetricFamily protobufs in case the returned error is non-nil.Gather() ([]*dto.MetricFamily,error)}

Gatherer is the interface for the part of a registry in charge of gatheringthe collected metrics into a number of MetricFamilies. The Gatherer interfacecomes with the same general implication as described for the Registererinterface.

typeGathererFunc ¶

type GathererFunc func() ([]*dto.MetricFamily,error)

GathererFunc turns a function into a Gatherer.

func (GathererFunc)Gather ¶

func (gfGathererFunc) Gather() ([]*dto.MetricFamily,error)

Gather implements Gatherer.

typeGatherers ¶

type Gatherers []Gatherer

Gatherers is a slice of Gatherer instances that implements the Gathererinterface itself. Its Gather method calls Gather on all Gatherers in theslice in order and returns the merged results. Errors returned from theGather calls are all returned in a flattened MultiError. Duplicate andinconsistent Metrics are skipped (first occurrence in slice order wins) andreported in the returned error.

Gatherers can be used to merge the Gather results from multipleRegistries. It also provides a way to directly inject existing MetricFamilyprotobufs into the gathering by creating a custom Gatherer with a Gathermethod that simply returns the existing MetricFamily protobufs. Note that noregistration is involved (in contrast to Collector registration), soobviously registration-time checks cannot happen. Any inconsistencies betweenthe gathered MetricFamilies are reported as errors by the Gather method, andinconsistent Metrics are dropped. Invalid parts of the MetricFamilies(e.g. syntactically invalid metric or label names) will go undetected.

Example¶

package mainimport ("bytes""fmt""strings"dto "github.com/prometheus/client_model/go""github.com/prometheus/common/expfmt""github.com/prometheus/common/model""github.com/prometheus/client_golang/prometheus")func main() {reg := prometheus.NewRegistry()temp := prometheus.NewGaugeVec(prometheus.GaugeOpts{Name: "temperature_kelvin",Help: "Temperature in Kelvin.",},[]string{"location"},)reg.MustRegister(temp)temp.WithLabelValues("outside").Set(273.14)temp.WithLabelValues("inside").Set(298.44)parser := expfmt.NewTextParser(model.UTF8Validation)text := `# TYPE humidity_percent gauge# HELP humidity_percent Humidity in %.humidity_percent{location="outside"} 45.4humidity_percent{location="inside"} 33.2# TYPE temperature_kelvin gauge# HELP temperature_kelvin Temperature in Kelvin.temperature_kelvin{location="somewhere else"} 4.5`parseText := func() ([]*dto.MetricFamily, error) {parsed, err := parser.TextToMetricFamilies(strings.NewReader(text))if err != nil {return nil, err}var result []*dto.MetricFamilyfor _, mf := range parsed {result = append(result, mf)}return result, nil}gatherers := prometheus.Gatherers{reg,prometheus.GathererFunc(parseText),}gathering, err := gatherers.Gather()if err != nil {fmt.Println(err)}out := &bytes.Buffer{}for _, mf := range gathering {if _, err := expfmt.MetricFamilyToText(out, mf); err != nil {panic(err)}}fmt.Print(out.String())fmt.Println("----------")// Note how the temperature_kelvin metric family has been merged from// different sources. Now trytext = `# TYPE humidity_percent gauge# HELP humidity_percent Humidity in %.humidity_percent{location="outside"} 45.4humidity_percent{location="inside"} 33.2# TYPE temperature_kelvin gauge# HELP temperature_kelvin Temperature in Kelvin.# Duplicate metric:temperature_kelvin{location="outside"} 265.3 # Missing location label (note that this is undesirable but valid):temperature_kelvin 4.5`gathering, err = gatherers.Gather()if err != nil {// We expect error collected metric "temperature_kelvin" { label:<name:"location" value:"outside" > gauge:<value:265.3 > } was collected before with the same name and label values// We cannot assert it because of https://github.com/golang/protobuf/issues/1121if strings.HasPrefix(err.Error(), `collected metric "temperature_kelvin" `) {fmt.Println("Found duplicated metric `temperature_kelvin`")} else {fmt.Print(err)}}// Note that still as many metrics as possible are returned:out.Reset()for _, mf := range gathering {if _, err := expfmt.MetricFamilyToText(out, mf); err != nil {panic(err)}}fmt.Print(out.String())}

Output:# HELP humidity_percent Humidity in %.# TYPE humidity_percent gaugehumidity_percent{location="inside"} 33.2humidity_percent{location="outside"} 45.4# HELP temperature_kelvin Temperature in Kelvin.# TYPE temperature_kelvin gaugetemperature_kelvin{location="inside"} 298.44temperature_kelvin{location="outside"} 273.14temperature_kelvin{location="somewhere else"} 4.5----------Found duplicated metric `temperature_kelvin`# HELP humidity_percent Humidity in %.# TYPE humidity_percent gaugehumidity_percent{location="inside"} 33.2humidity_percent{location="outside"} 45.4# HELP temperature_kelvin Temperature in Kelvin.# TYPE temperature_kelvin gaugetemperature_kelvin 4.5temperature_kelvin{location="inside"} 298.44temperature_kelvin{location="outside"} 273.14

func (Gatherers)Gather ¶

func (gsGatherers) Gather() ([]*dto.MetricFamily,error)

Gather implements Gatherer.

typeGauge ¶

type Gauge interface {MetricCollector// Set sets the Gauge to an arbitrary value.Set(float64)// Inc increments the Gauge by 1. Use Add to increment it by arbitrary// values.Inc()// Dec decrements the Gauge by 1. Use Sub to decrement it by arbitrary// values.Dec()// Add adds the given value to the Gauge. (The value can be negative,// resulting in a decrease of the Gauge.)Add(float64)// Sub subtracts the given value from the Gauge. (The value can be// negative, resulting in an increase of the Gauge.)Sub(float64)// SetToCurrentTime sets the Gauge to the current Unix time in seconds.SetToCurrentTime()}

Gauge is a Metric that represents a single numerical value that canarbitrarily go up and down.

A Gauge is typically used for measured values like temperatures or currentmemory usage, but also "counts" that can go up and down, like the number ofrunning goroutines.

To create Gauge instances, use NewGauge.

Example¶

package mainimport ("github.com/prometheus/client_golang/prometheus")func main() {opsQueued := prometheus.NewGauge(prometheus.GaugeOpts{Namespace: "our_company",Subsystem: "blob_storage",Name:      "ops_queued",Help:      "Number of blob storage operations waiting to be processed.",})prometheus.MustRegister(opsQueued)// 10 operations queued by the goroutine managing incoming requests.opsQueued.Add(10)// A worker goroutine has picked up a waiting operation.opsQueued.Dec()// And once more...opsQueued.Dec()}

funcNewGauge ¶

func NewGauge(optsGaugeOpts)Gauge

NewGauge creates a new Gauge based on the provided GaugeOpts.

The returned implementation is optimized for a fast Set method. If you have achoice for managing the value of a Gauge via Set vs. Inc/Dec/Add/Sub, pickthe former. For example, the Inc method of the returned Gauge is slower thanthe Inc method of a Counter returned by NewCounter. This matches the typicalscenarios for Gauges and Counters, where the former tends to be Set-heavy andthe latter Inc-heavy.

typeGaugeFunc ¶

type GaugeFunc interface {MetricCollector}

GaugeFunc is a Gauge whose value is determined at collect time by calling aprovided function.

To create GaugeFunc instances, use NewGaugeFunc.

Example (ConstLabels)¶

package mainimport ("fmt""github.com/prometheus/client_golang/prometheus")func main() {// primaryDB and secondaryDB represent two example *sql.DB connections we want to instrument.var primaryDB, secondaryDB interface {Stats() struct{ OpenConnections int }}if err := prometheus.Register(prometheus.NewGaugeFunc(prometheus.GaugeOpts{Namespace:   "mysql",Name:        "connections_open",Help:        "Number of mysql connections open.",ConstLabels: prometheus.Labels{"destination": "primary"},},func() float64 { return float64(primaryDB.Stats().OpenConnections) },)); err == nil {fmt.Println(`GaugeFunc 'connections_open' for primary DB connection registered with labels {destination="primary"}`)}if err := prometheus.Register(prometheus.NewGaugeFunc(prometheus.GaugeOpts{Namespace:   "mysql",Name:        "connections_open",Help:        "Number of mysql connections open.",ConstLabels: prometheus.Labels{"destination": "secondary"},},func() float64 { return float64(secondaryDB.Stats().OpenConnections) },)); err == nil {fmt.Println(`GaugeFunc 'connections_open' for secondary DB connection registered with labels {destination="secondary"}`)}// Note that we can register more than once GaugeFunc with same metric name// as long as their const labels are consistent.}

Output:GaugeFunc 'connections_open' for primary DB connection registered with labels {destination="primary"}GaugeFunc 'connections_open' for secondary DB connection registered with labels {destination="secondary"}

Example (Simple)¶

package mainimport ("fmt""runtime""github.com/prometheus/client_golang/prometheus")func main() {if err := prometheus.Register(prometheus.NewGaugeFunc(prometheus.GaugeOpts{Subsystem: "runtime",Name:      "goroutines_count",Help:      "Number of goroutines that currently exist.",},func() float64 { return float64(runtime.NumGoroutine()) },)); err == nil {fmt.Println("GaugeFunc 'goroutines_count' registered.")}// Note that the count of goroutines is a gauge (and not a counter) as// it can go up and down.}

Output:GaugeFunc 'goroutines_count' registered.

funcNewGaugeFunc ¶

func NewGaugeFunc(optsGaugeOpts, function func()float64)GaugeFunc

NewGaugeFunc creates a new GaugeFunc based on the provided GaugeOpts. Thevalue reported is determined by calling the given function from within theWrite method. Take into account that metric collection may happenconcurrently. Therefore, it must be safe to call the provided functionconcurrently.

NewGaugeFunc is a good way to create an “info” style metric with a constantvalue of 1. Example:https://github.com/prometheus/common/blob/8558a5b7db3c84fa38b4766966059a7bd5bfa2ee/version/info.go#L36-L56

typeGaugeOpts ¶

type GaugeOptsOpts

GaugeOpts is an alias for Opts. See there for doc comments.

typeGaugeVec ¶

type GaugeVec struct {*MetricVec}

GaugeVec is a Collector that bundles a set of Gauges that all share the sameDesc, but have different values for their variable labels. This is used ifyou want to count the same thing partitioned by various dimensions(e.g. number of operations queued, partitioned by user and operationtype). Create instances with NewGaugeVec.

Example¶

package mainimport ("github.com/prometheus/client_golang/prometheus")func main() {opsQueued := prometheus.NewGaugeVec(prometheus.GaugeOpts{Namespace: "our_company",Subsystem: "blob_storage",Name:      "ops_queued",Help:      "Number of blob storage operations waiting to be processed, partitioned by user and type.",},[]string{// Which user has requested the operation?"user",// Of what type is the operation?"type",},)prometheus.MustRegister(opsQueued)// Increase a value using compact (but order-sensitive!) WithLabelValues().opsQueued.WithLabelValues("bob", "put").Add(4)// Increase a value with a map using WithLabels. More verbose, but order// doesn't matter anymore.opsQueued.With(prometheus.Labels{"type": "delete", "user": "alice"}).Inc()}

funcNewGaugeVec ¶

func NewGaugeVec(optsGaugeOpts, labelNames []string) *GaugeVec

NewGaugeVec creates a new GaugeVec based on the provided GaugeOpts andpartitioned by the given label names.

func (*GaugeVec)CurryWith ¶added inv0.9.0

func (v *GaugeVec) CurryWith(labelsLabels) (*GaugeVec,error)

The metrics contained in the GaugeVec are shared between the curried anduncurried vectors. They are just accessed differently. Curried and uncurriedvectors behave identically in terms of collection. Only one must beregistered with a given registry (usually the uncurried version). The Resetmethod deletes all metrics, even if called on a curried vector.

func (*GaugeVec)GetMetricWith ¶

func (v *GaugeVec) GetMetricWith(labelsLabels) (Gauge,error)

GetMetricWith returns the Gauge for the given Labels map (the label namesmust match those of the variable labels in Desc). If that label map isaccessed for the first time, a new Gauge is created. Implications ofcreating a Gauge without using it and keeping the Gauge for later use arethe same as for GetMetricWithLabelValues.

An error is returned if the number and names of the Labels are inconsistentwith those of the variable labels in Desc (minus any curried labels).

This method is used for the same purpose asGetMetricWithLabelValues(...string). See there for pros and cons of the twomethods.

func (*GaugeVec)GetMetricWithLabelValues ¶

func (v *GaugeVec) GetMetricWithLabelValues(lvs ...string) (Gauge,error)

GetMetricWithLabelValues returns the Gauge for the given slice of labelvalues (same order as the variable labels in Desc). If that combination oflabel values is accessed for the first time, a new Gauge is created.

It is possible to call this method without using the returned Gauge to onlycreate the new Gauge but leave it at its starting value 0. See also theSummaryVec example.

Keeping the Gauge for later use is possible (and should be considered ifperformance is critical), but keep in mind that Reset, DeleteLabelValues andDelete can be used to delete the Gauge from the GaugeVec. In that case, theGauge will still exist, but it will not be exported anymore, even if aGauge with the same label values is created later. See also the CounterVecexample.

An error is returned if the number of label values is not the same as thenumber of variable labels in Desc (minus any curried labels).

func (*GaugeVec)MustCurryWith ¶added inv0.9.0

func (v *GaugeVec) MustCurryWith(labelsLabels) *GaugeVec

MustCurryWith works as CurryWith but panics where CurryWith would havereturned an error.

func (*GaugeVec)With ¶

func (v *GaugeVec) With(labelsLabels)Gauge

With works as GetMetricWith, but panics where GetMetricWithLabels would havereturned an error. Not returning an error allows shortcuts like

myVec.With(prometheus.Labels{"code": "404", "method": "GET"}).Add(42)

func (*GaugeVec)WithLabelValues ¶

func (v *GaugeVec) WithLabelValues(lvs ...string)Gauge

WithLabelValues works as GetMetricWithLabelValues, but panics whereGetMetricWithLabelValues would have returned an error. Not returning anerror allows shortcuts like

myVec.WithLabelValues("404", "GET").Add(42)

typeGaugeVecOpts ¶added inv1.15.0

type GaugeVecOpts struct {GaugeOpts// VariableLabels are used to partition the metric vector by the given set// of labels. Each label value will be constrained with the optional Constraint// function, if provided.VariableLabelsConstrainableLabels}

GaugeVecOpts bundles the options to create a GaugeVec metric.It is mandatory to set GaugeOpts, see there for mandatory fields. VariableLabelsis optional and can safely be left to its default value.

typeHistogram ¶

type Histogram interface {MetricCollector// Observe adds a single observation to the histogram. Observations are// usually positive or zero. Negative observations are accepted but// prevent current versions of Prometheus from properly detecting// counter resets in the sum of observations. (The experimental Native// Histograms handle negative observations properly.) See//https://prometheus.io/docs/practices/histograms/#count-and-sum-of-observations// for details.Observe(float64)}

A Histogram counts individual observations from an event or sample stream inconfigurable static buckets (or in dynamic sparse buckets as part of theexperimental Native Histograms, see below for more details). Similar to aSummary, it also provides a sum of observations and an observation count.

On the Prometheus server, quantiles can be calculated from a Histogram usingthe histogram_quantile PromQL function.

Note that Histograms, in contrast to Summaries, can be aggregated in PromQL(see the documentation for detailed procedures). However, Histograms requirethe user to pre-define suitable buckets, and they are in general lessaccurate. (Both problems are addressed by the experimental NativeHistograms. To use them, configure a NativeHistogramBucketFactor in theHistogramOpts. They also require a Prometheus server v2.40+ with thecorresponding feature flag enabled.)

The Observe method of a Histogram has a very low performance overhead incomparison with the Observe method of a Summary.

To create Histogram instances, use NewHistogram.

Example¶

temps := prometheus.NewHistogram(prometheus.HistogramOpts{Name:    "pond_temperature_celsius",Help:    "The temperature of the frog pond.", // Sorry, we can't measure how badly it smells.Buckets: prometheus.LinearBuckets(20, 5, 5),  // 5 buckets, each 5 centigrade wide.})// Simulate some observations.for i := 0; i < 1000; i++ {temps.Observe(30 + math.Floor(120*math.Sin(float64(i)*0.1))/10)}// Just for demonstration, let's check the state of the histogram by// (ab)using its Write method (which is usually only used by Prometheus// internally).metric := &dto.Metric{}temps.Write(metric)fmt.Println(toNormalizedJSON(sanitizeMetric(metric)))

Output:{"histogram":{"sampleCount":"1000","sampleSum":29969.50000000001,"bucket":[{"cumulativeCount":"192","upperBound":20},{"cumulativeCount":"366","upperBound":25},{"cumulativeCount":"501","upperBound":30},{"cumulativeCount":"638","upperBound":35},{"cumulativeCount":"816","upperBound":40}],"createdTimestamp":"1970-01-01T00:00:10Z"}}

funcNewHistogram ¶

func NewHistogram(optsHistogramOpts)Histogram

NewHistogram creates a new Histogram based on the provided HistogramOpts. Itpanics if the buckets in HistogramOpts are not in strictly increasing order.

The returned implementation also implements ExemplarObserver. It is safe toperform the corresponding type assertion. Exemplars are tracked separatelyfor each bucket.

typeHistogramOpts ¶

type HistogramOpts struct {// Namespace, Subsystem, and Name are components of the fully-qualified// name of the Histogram (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 Histogram must be a// valid Prometheus metric name.NamespacestringSubsystemstringNamestring// Help provides information about this Histogram.//// Metrics with the same fully-qualified name must have the same Help// string.Helpstring// 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-labelsConstLabelsLabels// Buckets defines the buckets into which observations are counted. Each// element in the slice is the upper inclusive bound of a bucket. The// values must be sorted in strictly increasing order. There is no need// to add a highest bucket with +Inf bound, it will be added// implicitly. If Buckets is left as nil or set to a slice of length// zero, it is replaced by default buckets. The default buckets are// DefBuckets if no buckets for a native histogram (see below) are used,// otherwise the default is no buckets. (In other words, if you want to// use both regular buckets and buckets for a native histogram, you have// to define the regular buckets here explicitly.)Buckets []float64// If NativeHistogramBucketFactor is greater than one, so-called sparse// buckets are used (in addition to the regular buckets, if defined// above). A Histogram with sparse buckets will be ingested as a Native// Histogram by a Prometheus server with that feature enabled (requires// Prometheus v2.40+). Sparse buckets are exponential buckets covering// the whole float64 range (with the exception of the “zero” bucket, see// NativeHistogramZeroThreshold below). From any one bucket to the next,// the width of the bucket grows by a constant// factor. NativeHistogramBucketFactor provides an upper bound for this// factor (exception see below). The smaller// NativeHistogramBucketFactor, the more buckets will be used and thus// the more costly the histogram will become. A generally good trade-off// between cost and accuracy is a value of 1.1 (each bucket is at most// 10% wider than the previous one), which will result in each power of// two divided into 8 buckets (e.g. there will be 8 buckets between 1// and 2, same as between 2 and 4, and 4 and 8, etc.).//// Details about the actually used factor: The factor is calculated as// 2^(2^-n), where n is an integer number between (and including) -4 and// 8. n is chosen so that the resulting factor is the largest that is// still smaller or equal to NativeHistogramBucketFactor. Note that the// smallest possible factor is therefore approx. 1.00271 (i.e. 2^(2^-8)// ). If NativeHistogramBucketFactor is greater than 1 but smaller than// 2^(2^-8), then the actually used factor is still 2^(2^-8) even though// it is larger than the provided NativeHistogramBucketFactor.//// NOTE: Native Histograms are still an experimental feature. Their// behavior might still change without a major version// bump. Subsequently, all NativeHistogram... options here might still// change their behavior or name (or might completely disappear) without// a major version bump.NativeHistogramBucketFactorfloat64// All observations with an absolute value of less or equal// NativeHistogramZeroThreshold are accumulated into a “zero” bucket.// For best results, this should be close to a bucket boundary. This is// usually the case if picking a power of two. If// NativeHistogramZeroThreshold is left at zero,// DefNativeHistogramZeroThreshold is used as the threshold. To// configure a zero bucket with an actual threshold of zero (i.e. only// observations of precisely zero will go into the zero bucket), set// NativeHistogramZeroThreshold to the NativeHistogramZeroThresholdZero// constant (or any negative float value).NativeHistogramZeroThresholdfloat64// The next three fields define a strategy to limit the number of// populated sparse buckets. If NativeHistogramMaxBucketNumber is left// at zero, the number of buckets is not limited. (Note that this might// lead to unbounded memory consumption if the values observed by the// Histogram are sufficiently wide-spread. In particular, this could be// used as a DoS attack vector. Where the observed values depend on// external inputs, it is highly recommended to set a// NativeHistogramMaxBucketNumber.) Once the set// NativeHistogramMaxBucketNumber is exceeded, the following strategy is// enacted:// - First, if the last reset (or the creation) of the histogram is at// least NativeHistogramMinResetDuration ago, then the whole// histogram is reset to its initial state (including regular// buckets).// - If less time has passed, or if NativeHistogramMinResetDuration is// zero, no reset is performed. Instead, the zero threshold is// increased sufficiently to reduce the number of buckets to or below// NativeHistogramMaxBucketNumber, but not to more than// NativeHistogramMaxZeroThreshold. Thus, if// NativeHistogramMaxZeroThreshold is already at or below the current// zero threshold, nothing happens at this step.// - After that, if the number of buckets still exceeds// NativeHistogramMaxBucketNumber, the resolution of the histogram is// reduced by doubling the width of the sparse buckets (up to a// growth factor between one bucket to the next of 2^(2^4) = 65536,// see above).// - Any increased zero threshold or reduced resolution is reset back// to their original values once NativeHistogramMinResetDuration has// passed (since the last reset or the creation of the histogram).NativeHistogramMaxBucketNumberuint32NativeHistogramMinResetDurationtime.DurationNativeHistogramMaxZeroThresholdfloat64// NativeHistogramMaxExemplars limits the number of exemplars// that are kept in memory for each native histogram. If you leave it at// zero, a default value of 10 is used. If no exemplars should be kept specifically// for native histograms, set it to a negative value. (Scrapers can// still use the exemplars exposed for classic buckets, which are managed// independently.)NativeHistogramMaxExemplarsint// NativeHistogramExemplarTTL is only checked once// NativeHistogramMaxExemplars is exceeded. In that case, the// oldest exemplar is removed if it is older than NativeHistogramExemplarTTL.// Otherwise, the older exemplar in the pair of exemplars that are closest// together (on an exponential scale) is removed.// If NativeHistogramExemplarTTL is left at its zero value, a default value of// 5m is used. To always delete the oldest exemplar, set it to a negative value.NativeHistogramExemplarTTLtime.Duration// contains filtered or unexported fields}

HistogramOpts bundles the options for creating a Histogram metric. It ismandatory to set Name to a non-empty string. All other fields are optionaland can safely be left at their zero value, although it is stronglyencouraged to set a Help string.

typeHistogramVec ¶

type HistogramVec struct {*MetricVec}

HistogramVec is a Collector that bundles a set of Histograms that all share thesame Desc, but have different values for their variable labels. This is usedif you want to count the same thing partitioned by various dimensions(e.g. HTTP request latencies, partitioned by status code and method). Createinstances with NewHistogramVec.

funcNewHistogramVec ¶

func NewHistogramVec(optsHistogramOpts, labelNames []string) *HistogramVec

NewHistogramVec creates a new HistogramVec based on the provided HistogramOpts andpartitioned by the given label names.

func (*HistogramVec)CurryWith ¶added inv0.9.0

func (v *HistogramVec) CurryWith(labelsLabels) (ObserverVec,error)

The metrics contained in the HistogramVec are shared between the curried anduncurried vectors. They are just accessed differently. Curried and uncurriedvectors behave identically in terms of collection. Only one must beregistered with a given registry (usually the uncurried version). The Resetmethod deletes all metrics, even if called on a curried vector.

func (*HistogramVec)GetMetricWith ¶

func (v *HistogramVec) GetMetricWith(labelsLabels) (Observer,error)

GetMetricWith returns the Histogram for the given Labels map (the label namesmust match those of the variable labels in Desc). If that label map isaccessed for the first time, a new Histogram is created. Implications ofcreating a Histogram without using it and keeping the Histogram for later useare the same as for GetMetricWithLabelValues.

An error is returned if the number and names of the Labels are inconsistentwith those of the variable labels in Desc (minus any curried labels).

This method is used for the same purpose asGetMetricWithLabelValues(...string). See there for pros and cons of the twomethods.

func (*HistogramVec)GetMetricWithLabelValues ¶

func (v *HistogramVec) GetMetricWithLabelValues(lvs ...string) (Observer,error)

GetMetricWithLabelValues returns the Histogram for the given slice of labelvalues (same order as the variable labels in Desc). If that combination oflabel values is accessed for the first time, a new Histogram is created.

It is possible to call this method without using the returned Histogram to onlycreate the new Histogram but leave it at its starting value, a Histogram withoutany observations.

Keeping the Histogram for later use is possible (and should be considered ifperformance is critical), but keep in mind that Reset, DeleteLabelValues andDelete can be used to delete the Histogram from the HistogramVec. In that case, theHistogram will still exist, but it will not be exported anymore, even if aHistogram with the same label values is created later. See also the CounterVecexample.

An error is returned if the number of label values is not the same as thenumber of variable labels in Desc (minus any curried labels).

func (*HistogramVec)MustCurryWith ¶added inv0.9.0

func (v *HistogramVec) MustCurryWith(labelsLabels)ObserverVec

MustCurryWith works as CurryWith but panics where CurryWith would havereturned an error.

func (*HistogramVec)With ¶

func (v *HistogramVec) With(labelsLabels)Observer

With works as GetMetricWith but panics where GetMetricWithLabels would havereturned an error. Not returning an error allows shortcuts like

myVec.With(prometheus.Labels{"code": "404", "method": "GET"}).Observe(42.21)

func (*HistogramVec)WithLabelValues ¶

func (v *HistogramVec) WithLabelValues(lvs ...string)Observer

WithLabelValues works as GetMetricWithLabelValues, but panics whereGetMetricWithLabelValues would have returned an error. Not returning anerror allows shortcuts like

myVec.WithLabelValues("404", "GET").Observe(42.21)

typeHistogramVecOpts ¶added inv1.15.0

type HistogramVecOpts struct {HistogramOpts// VariableLabels are used to partition the metric vector by the given set// of labels. Each label value will be constrained with the optional Constraint// function, if provided.VariableLabelsConstrainableLabels}

HistogramVecOpts bundles the options to create a HistogramVec metric.It is mandatory to set HistogramOpts, see there for mandatory fields. VariableLabelsis optional and can safely be left to its default value.

typeLabelConstraint ¶added inv1.17.0

type LabelConstraint func(string)string

LabelConstraint normalizes label values.

typeLabels ¶

type Labels map[string]string

Labels represents a collection of label name -> value mappings. This type iscommonly used with the With(Labels) and GetMetricWith(Labels) methods ofmetric vector Collectors, e.g.:

myVec.With(Labels{"code": "404", "method": "GET"}).Add(42)

The other use-case is the specification of constant label pairs in Opts or tocreate a Desc.

typeMetric ¶

type Metric interface {// Desc returns the descriptor for the Metric. This method idempotently// returns the same descriptor throughout the lifetime of the// 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. Callers of Write should// still make sure of sorting if they depend on it.Write(*dto.Metric)error}

A Metric models a single sample value with its meta data being exported toPrometheus. Implementations of Metric in this package are Gauge, Counter,Histogram, Summary, and Untyped.

funcMustNewConstHistogram ¶

func MustNewConstHistogram(desc *Desc,countuint64,sumfloat64,buckets map[float64]uint64,labelValues ...string,)Metric

MustNewConstHistogram is a version of NewConstHistogram that panics whereNewConstHistogram would have returned an error.

funcMustNewConstHistogramWithCreatedTimestamp ¶added inv1.20.0

func MustNewConstHistogramWithCreatedTimestamp(desc *Desc,countuint64,sumfloat64,buckets map[float64]uint64,cttime.Time,labelValues ...string,)Metric

MustNewConstHistogramWithCreatedTimestamp is a version of NewConstHistogramWithCreatedTimestamp that panics whereNewConstHistogramWithCreatedTimestamp would have returned an error.

funcMustNewConstMetric ¶

func MustNewConstMetric(desc *Desc, valueTypeValueType, valuefloat64, labelValues ...string)Metric

MustNewConstMetric is a version of NewConstMetric that panics whereNewConstMetric would have returned an error.

funcMustNewConstMetricWithCreatedTimestamp ¶added inv1.17.0

func MustNewConstMetricWithCreatedTimestamp(desc *Desc, valueTypeValueType, valuefloat64, cttime.Time, labelValues ...string)Metric

MustNewConstMetricWithCreatedTimestamp is a version of NewConstMetricWithCreatedTimestamp that panics whereNewConstMetricWithCreatedTimestamp would have returned an error.

funcMustNewConstNativeHistogram ¶added inv1.21.0

func MustNewConstNativeHistogram(desc *Desc,countuint64,sumfloat64,positiveBuckets, negativeBuckets map[int]int64,zeroBucketuint64,nativeHistogramSchemaint32,nativeHistogramZeroThresholdfloat64,createdTimestamptime.Time,labelValues ...string,)Metric

MustNewConstNativeHistogram is a version of NewConstNativeHistogram that panics whereNewConstNativeHistogram would have returned an error.

funcMustNewConstSummary ¶

func MustNewConstSummary(desc *Desc,countuint64,sumfloat64,quantiles map[float64]float64,labelValues ...string,)Metric

MustNewConstSummary is a version of NewConstSummary that panics whereNewConstMetric would have returned an error.

funcMustNewConstSummaryWithCreatedTimestamp ¶added inv1.20.0

func MustNewConstSummaryWithCreatedTimestamp(desc *Desc,countuint64,sumfloat64,quantiles map[float64]float64,cttime.Time,labelValues ...string,)Metric

MustNewConstSummaryWithCreatedTimestamp is a version of NewConstSummaryWithCreatedTimestamp that panics whereNewConstSummaryWithCreatedTimestamp would have returned an error.

funcMustNewMetricWithExemplars ¶added inv1.13.0

func MustNewMetricWithExemplars(mMetric, exemplars ...Exemplar)Metric

MustNewMetricWithExemplars is a version of NewMetricWithExemplars that panics whereNewMetricWithExemplars would have returned an error.

funcNewConstHistogram ¶

func NewConstHistogram(desc *Desc,countuint64,sumfloat64,buckets map[float64]uint64,labelValues ...string,) (Metric,error)

NewConstHistogram returns a metric representing a Prometheus histogram withfixed values for the count, sum, and bucket counts. As those parameterscannot be changed, the returned value does not implement the Histograminterface (but only the Metric interface). Users of this package will nothave much use for it in regular operations. However, when implementing customCollectors, it is useful as a throw-away metric that is generated on the flyto send it to Prometheus in the Collect method.

buckets is a map of upper bounds to cumulative counts, excluding the +Infbucket. The +Inf bucket is implicit, and its value is equal to the provided count.

NewConstHistogram returns an error if the length of labelValues is notconsistent with the variable labels in Desc or if Desc is invalid.

Example¶

desc := prometheus.NewDesc("http_request_duration_seconds","A histogram of the HTTP request durations.",[]string{"code", "method"},prometheus.Labels{"owner": "example"},)// Create a constant histogram from values we got from a 3rd party telemetry system.h := prometheus.MustNewConstHistogram(desc,4711, 403.34,map[float64]uint64{25: 121, 50: 2403, 100: 3221, 200: 4233},"200", "get",)// Just for demonstration, let's check the state of the histogram by// (ab)using its Write method (which is usually only used by Prometheus// internally).metric := &dto.Metric{}h.Write(metric)fmt.Println(toNormalizedJSON(metric))

Output:{"label":[{"name":"code","value":"200"},{"name":"method","value":"get"},{"name":"owner","value":"example"}],"histogram":{"sampleCount":"4711","sampleSum":403.34,"bucket":[{"cumulativeCount":"121","upperBound":25},{"cumulativeCount":"2403","upperBound":50},{"cumulativeCount":"3221","upperBound":100},{"cumulativeCount":"4233","upperBound":200}]}}

Example (WithExemplar)¶

desc := prometheus.NewDesc("http_request_duration_seconds","A histogram of the HTTP request durations.",[]string{"code", "method"},prometheus.Labels{"owner": "example"},)// Create a constant histogram from values we got from a 3rd party telemetry system.h := prometheus.MustNewConstHistogram(desc,4711, 403.34,map[float64]uint64{25: 121, 50: 2403, 100: 3221, 200: 4233},"200", "get",)// Wrap const histogram with exemplars for each bucket.exemplarTs, _ := time.Parse(time.RFC850, "Monday, 02-Jan-06 15:04:05 GMT")exemplarLabels := prometheus.Labels{"testName": "testVal"}h = prometheus.MustNewMetricWithExemplars(h,prometheus.Exemplar{Labels: exemplarLabels, Timestamp: exemplarTs, Value: 24.0},prometheus.Exemplar{Labels: exemplarLabels, Timestamp: exemplarTs, Value: 42.0},prometheus.Exemplar{Labels: exemplarLabels, Timestamp: exemplarTs, Value: 89.0},prometheus.Exemplar{Labels: exemplarLabels, Timestamp: exemplarTs, Value: 157.0},)// Just for demonstration, let's check the state of the histogram by// (ab)using its Write method (which is usually only used by Prometheus// internally).metric := &dto.Metric{}h.Write(metric)fmt.Println(toNormalizedJSON(metric))

Output:{"label":[{"name":"code","value":"200"},{"name":"method","value":"get"},{"name":"owner","value":"example"}],"histogram":{"sampleCount":"4711","sampleSum":403.34,"bucket":[{"cumulativeCount":"121","upperBound":25,"exemplar":{"label":[{"name":"testName","value":"testVal"}],"value":24,"timestamp":"2006-01-02T15:04:05Z"}},{"cumulativeCount":"2403","upperBound":50,"exemplar":{"label":[{"name":"testName","value":"testVal"}],"value":42,"timestamp":"2006-01-02T15:04:05Z"}},{"cumulativeCount":"3221","upperBound":100,"exemplar":{"label":[{"name":"testName","value":"testVal"}],"value":89,"timestamp":"2006-01-02T15:04:05Z"}},{"cumulativeCount":"4233","upperBound":200,"exemplar":{"label":[{"name":"testName","value":"testVal"}],"value":157,"timestamp":"2006-01-02T15:04:05Z"}}]}}

funcNewConstHistogramWithCreatedTimestamp ¶added inv1.20.0

func NewConstHistogramWithCreatedTimestamp(desc *Desc,countuint64,sumfloat64,buckets map[float64]uint64,cttime.Time,labelValues ...string,) (Metric,error)

NewConstHistogramWithCreatedTimestamp does the same thing as NewConstHistogram but sets the created timestamp.

Example¶

desc := prometheus.NewDesc("http_request_duration_seconds","A histogram of the HTTP request durations.",[]string{"code", "method"},prometheus.Labels{"owner": "example"},)createdTs := time.Unix(1719670764, 123)h := prometheus.MustNewConstHistogramWithCreatedTimestamp(desc,4711, 403.34,map[float64]uint64{25: 121, 50: 2403, 100: 3221, 200: 4233},createdTs,"200", "get",)// Just for demonstration, let's check the state of the histogram by// (ab)using its Write method (which is usually only used by Prometheus// internally).metric := &dto.Metric{}h.Write(metric)fmt.Println(toNormalizedJSON(metric))

Output:{"label":[{"name":"code","value":"200"},{"name":"method","value":"get"},{"name":"owner","value":"example"}],"histogram":{"sampleCount":"4711","sampleSum":403.34,"bucket":[{"cumulativeCount":"121","upperBound":25},{"cumulativeCount":"2403","upperBound":50},{"cumulativeCount":"3221","upperBound":100},{"cumulativeCount":"4233","upperBound":200}],"createdTimestamp":"2024-06-29T14:19:24.000000123Z"}}

funcNewConstMetric ¶

func NewConstMetric(desc *Desc, valueTypeValueType, valuefloat64, labelValues ...string) (Metric,error)

NewConstMetric returns a metric with one fixed value that cannot bechanged. Users of this package will not have much use for it in regularoperations. However, when implementing custom Collectors, it is useful as athrow-away metric that is generated on the fly to send it to Prometheus inthe Collect method. NewConstMetric returns an error if the length oflabelValues is not consistent with the variable labels in Desc or if Desc isinvalid.

funcNewConstMetricWithCreatedTimestamp ¶added inv1.17.0

func NewConstMetricWithCreatedTimestamp(desc *Desc, valueTypeValueType, valuefloat64, cttime.Time, labelValues ...string) (Metric,error)

NewConstMetricWithCreatedTimestamp does the same thing as NewConstMetric, but generates Counterswith created timestamp set and returns an error for other metric types.

Example¶

// Here we have a metric that is reported by an external system.// Besides providing the value, the external system also provides the// timestamp when the metric was created.desc := prometheus.NewDesc("time_since_epoch_seconds","Current epoch time in seconds.",nil, nil,)timeSinceEpochReportedByExternalSystem := time.Date(2009, time.November, 10, 23, 0, 0, 12345678, time.UTC)epoch := time.Unix(0, 0).UTC()s := prometheus.MustNewConstMetricWithCreatedTimestamp(desc, prometheus.CounterValue, float64(timeSinceEpochReportedByExternalSystem.Unix()), epoch,)metric := &dto.Metric{}s.Write(metric)fmt.Println(toNormalizedJSON(metric))

Output:{"counter":{"value":1257894000,"createdTimestamp":"1970-01-01T00:00:00Z"}}

funcNewConstNativeHistogram ¶added inv1.21.0

func NewConstNativeHistogram(desc *Desc,countuint64,sumfloat64,positiveBuckets, negativeBuckets map[int]int64,zeroBucketuint64,schemaint32,zeroThresholdfloat64,createdTimestamptime.Time,labelValues ...string,) (Metric,error)

NewConstNativeHistogram returns a metric representing a Prometheus native histogram withfixed values for the count, sum, and positive/negative/zero bucket counts. As those parameterscannot be changed, the returned value does not implement the Histograminterface (but only the Metric interface). Users of this package will nothave much use for it in regular operations. However, when implementing customOpenTelemetry Collectors, it is useful as a throw-away metric that is generated on the flyto send it to Prometheus in the Collect method.

zeroBucket counts all (positive and negative)observations in the zero bucket (with an absolute value less or equalthe current threshold).positiveBuckets and negativeBuckets are separate maps for negative and positiveobservations. The map's value is an int64, counting observations inthat bucket. The map's key is theindex of the bucket according to the usedSchema. Index 0 is for an upper bound of 1 in positive buckets and for a lower bound of -1 in negative buckets.NewConstNativeHistogram returns an error if

the length of labelValues is not consistent with the variable labels in Desc or if Desc is invalid.
the schema passed is not between 8 and -4
the sum of counts in all buckets including the zero bucket does not equal the count if sum is not NaN (or exceeds the count if sum is NaN)

Seehttps://opentelemetry.io/docs/specs/otel/compatibility/prometheus_and_openmetrics/#exponential-histograms for more details about the conversion from OTel to Prometheus.

funcNewConstSummary ¶

func NewConstSummary(desc *Desc,countuint64,sumfloat64,quantiles map[float64]float64,labelValues ...string,) (Metric,error)

NewConstSummary returns a metric representing a Prometheus summary with fixedvalues for the count, sum, and quantiles. As those parameters cannot bechanged, the returned value does not implement the Summary interface (butonly the Metric interface). Users of this package will not have much use forit in regular operations. However, when implementing custom Collectors, it isuseful as a throw-away metric that is generated on the fly to send it toPrometheus in the Collect method.

quantiles maps ranks to quantile values. For example, a median latency of0.23s and a 99th percentile latency of 0.56s would be expressed as:

map[float64]float64{0.5: 0.23, 0.99: 0.56}

NewConstSummary returns an error if the length of labelValues is notconsistent with the variable labels in Desc or if Desc is invalid.

Example¶

desc := prometheus.NewDesc("http_request_duration_seconds","A summary of the HTTP request durations.",[]string{"code", "method"},prometheus.Labels{"owner": "example"},)// Create a constant summary from values we got from a 3rd party telemetry system.s := prometheus.MustNewConstSummary(desc,4711, 403.34,map[float64]float64{0.5: 42.3, 0.9: 323.3},"200", "get",)// Just for demonstration, let's check the state of the summary by// (ab)using its Write method (which is usually only used by Prometheus// internally).metric := &dto.Metric{}s.Write(metric)fmt.Println(toNormalizedJSON(metric))

Output:{"label":[{"name":"code","value":"200"},{"name":"method","value":"get"},{"name":"owner","value":"example"}],"summary":{"sampleCount":"4711","sampleSum":403.34,"quantile":[{"quantile":0.5,"value":42.3},{"quantile":0.9,"value":323.3}]}}

funcNewConstSummaryWithCreatedTimestamp ¶added inv1.20.0

func NewConstSummaryWithCreatedTimestamp(desc *Desc,countuint64,sumfloat64,quantiles map[float64]float64,cttime.Time,labelValues ...string,) (Metric,error)

NewConstSummaryWithCreatedTimestamp does the same thing as NewConstSummary but sets the created timestamp.

Example¶

desc := prometheus.NewDesc("http_request_duration_seconds","A summary of the HTTP request durations.",[]string{"code", "method"},prometheus.Labels{"owner": "example"},)// Create a constant summary with created timestamp setcreatedTs := time.Unix(1719670764, 123)s := prometheus.MustNewConstSummaryWithCreatedTimestamp(desc,4711, 403.34,map[float64]float64{0.5: 42.3, 0.9: 323.3},createdTs,"200", "get",)// Just for demonstration, let's check the state of the summary by// (ab)using its Write method (which is usually only used by Prometheus// internally).metric := &dto.Metric{}s.Write(metric)fmt.Println(toNormalizedJSON(metric))

Output:{"label":[{"name":"code","value":"200"},{"name":"method","value":"get"},{"name":"owner","value":"example"}],"summary":{"sampleCount":"4711","sampleSum":403.34,"quantile":[{"quantile":0.5,"value":42.3},{"quantile":0.9,"value":323.3}],"createdTimestamp":"2024-06-29T14:19:24.000000123Z"}}

funcNewInvalidMetric ¶

func NewInvalidMetric(desc *Desc, errerror)Metric

NewInvalidMetric returns a metric whose Write method always returns theprovided error. It is useful if a Collector finds itself unable to collecta metric and wishes to report an error to the registry.

funcNewMetricWithExemplars ¶added inv1.13.0

func NewMetricWithExemplars(mMetric, exemplars ...Exemplar) (Metric,error)

NewMetricWithExemplars returns a new Metric wrapping the provided Metric with givenexemplars. Exemplars are validated.

Only last applicable exemplar is injected from the list.For example for Counter it means last exemplar is injected.For Histogram, it means last applicable exemplar for each bucket is injected.For a Native Histogram, all valid exemplars are injected.

NewMetricWithExemplars works best with MustNewConstMetric andMustNewConstHistogram, see example.

funcNewMetricWithTimestamp ¶added inv0.9.0

func NewMetricWithTimestamp(ttime.Time, mMetric)Metric

NewMetricWithTimestamp returns a new Metric wrapping the provided Metric in away that it has an explicit timestamp set to the provided Time. This is onlyuseful in rare cases as the timestamp of a Prometheus metric should usuallybe set by the Prometheus server during scraping. Exceptions include mirroringmetrics with given timestamps from other metricsources.

NewMetricWithTimestamp works best with MustNewConstMetric,MustNewConstHistogram, and MustNewConstSummary, see example.

Currently, the exposition formats used by Prometheus are limited tomillisecond resolution. Thus, the provided time will be rounded down to thenext full millisecond value.

Example¶

desc := prometheus.NewDesc("temperature_kelvin","Current temperature in Kelvin.",nil, nil,)// Create a constant gauge from values we got from an external// temperature reporting system. Those values are reported with a slight// delay, so we want to add the timestamp of the actual measurement.temperatureReportedByExternalSystem := 298.15timeReportedByExternalSystem := time.Date(2009, time.November, 10, 23, 0, 0, 12345678, time.UTC)s := prometheus.NewMetricWithTimestamp(timeReportedByExternalSystem,prometheus.MustNewConstMetric(desc, prometheus.GaugeValue, temperatureReportedByExternalSystem,),)// Just for demonstration, let's check the state of the gauge by// (ab)using its Write method (which is usually only used by Prometheus// internally).metric := &dto.Metric{}s.Write(metric)fmt.Println(toNormalizedJSON(metric))

Output:{"gauge":{"value":298.15},"timestampMs":"1257894000012"}

typeMetricVec ¶

type MetricVec struct {// contains filtered or unexported fields}

MetricVec is a Collector to bundle metrics of the same name that differ intheir label values. MetricVec is not used directly but as a building blockfor implementations of vectors of a given metric type, like GaugeVec,CounterVec, SummaryVec, and HistogramVec. It is exported so that it can beused for custom Metric implementations.

To create a FooVec for custom Metric Foo, embed a pointer to MetricVec inFooVec and initialize it with NewMetricVec. Implement wrappers forGetMetricWithLabelValues and GetMetricWith that return (Foo, error) ratherthan (Metric, error). Similarly, create a wrapper for CurryWith that returns(*FooVec, error) rather than (*MetricVec, error). It is recommended to alsoadd the convenience methods WithLabelValues, With, and MustCurryWith, whichpanic instead of returning errors. See also the MetricVec example.

Example¶

package mainimport ("fmt""google.golang.org/protobuf/proto"dto "github.com/prometheus/client_model/go""github.com/prometheus/client_golang/prometheus")// Info implements an info pseudo-metric, which is modeled as a Gauge that// always has a value of 1. In practice, you would just use a Gauge directly,// but for this example, we pretend it would be useful to have a “native”// implementation.type Info struct {desc       *prometheus.DesclabelPairs []*dto.LabelPair}func (i Info) Desc() *prometheus.Desc {return i.desc}func (i Info) Write(out *dto.Metric) error {out.Label = i.labelPairsout.Gauge = &dto.Gauge{Value: proto.Float64(1)}return nil}// InfoVec is the vector version for Info. As an info metric never changes, we// wouldn't really need to wrap GetMetricWithLabelValues and GetMetricWith// because Info has no additional methods compared to the vanilla Metric that// the unwrapped MetricVec methods return. However, to demonstrate all there is// to do to fully implement a vector for a custom Metric implementation, we do// it in this example anyway.type InfoVec struct {*prometheus.MetricVec}func NewInfoVec(name, help string, labelNames []string) *InfoVec {desc := prometheus.NewDesc(name, help, labelNames, nil)return &InfoVec{MetricVec: prometheus.NewMetricVec(desc, func(lvs ...string) prometheus.Metric {if len(lvs) != len(labelNames) {panic("inconsistent label cardinality")}return Info{desc: desc, labelPairs: prometheus.MakeLabelPairs(desc, lvs)}}),}}func (v *InfoVec) GetMetricWithLabelValues(lvs ...string) (Info, error) {metric, err := v.MetricVec.GetMetricWithLabelValues(lvs...)return metric.(Info), err}func (v *InfoVec) GetMetricWith(labels prometheus.Labels) (Info, error) {metric, err := v.MetricVec.GetMetricWith(labels)return metric.(Info), err}func (v *InfoVec) WithLabelValues(lvs ...string) Info {i, err := v.GetMetricWithLabelValues(lvs...)if err != nil {panic(err)}return i}func (v *InfoVec) With(labels prometheus.Labels) Info {i, err := v.GetMetricWith(labels)if err != nil {panic(err)}return i}func (v *InfoVec) CurryWith(labels prometheus.Labels) (*InfoVec, error) {vec, err := v.MetricVec.CurryWith(labels)if vec != nil {return &InfoVec{vec}, err}return nil, err}func (v *InfoVec) MustCurryWith(labels prometheus.Labels) *InfoVec {vec, err := v.CurryWith(labels)if err != nil {panic(err)}return vec}func main() {infoVec := NewInfoVec("library_version_info","Versions of the libraries used in this binary.",[]string{"library", "version"},)infoVec.WithLabelValues("prometheus/client_golang", "1.7.1")infoVec.WithLabelValues("k8s.io/client-go", "0.18.8")// Just for demonstration, let's check the state of the InfoVec by// registering it with a custom registry and then let it collect the// metrics.reg := prometheus.NewRegistry()reg.MustRegister(infoVec)metricFamilies, err := reg.Gather()if err != nil || len(metricFamilies) != 1 {panic("unexpected behavior of custom test registry")}fmt.Println(toNormalizedJSON(metricFamilies[0]))}

Output:{"name":"library_version_info","help":"Versions of the libraries used in this binary.","type":"GAUGE","metric":[{"label":[{"name":"library","value":"k8s.io/client-go"},{"name":"version","value":"0.18.8"}],"gauge":{"value":1}},{"label":[{"name":"library","value":"prometheus/client_golang"},{"name":"version","value":"1.7.1"}],"gauge":{"value":1}}]}

funcNewMetricVec ¶added inv0.12.1

func NewMetricVec(desc *Desc, newMetric func(lvs ...string)Metric) *MetricVec

NewMetricVec returns an initialized metricVec.

func (*MetricVec)Collect ¶

func (m *MetricVec) Collect(ch chan<-Metric)

Collect implements Collector.

func (*MetricVec)CurryWith ¶added inv0.12.1

func (m *MetricVec) CurryWith(labelsLabels) (*MetricVec,error)

The metrics contained in the MetricVec are shared between the curried anduncurried vectors. They are just accessed differently. Curried and uncurriedvectors behave identically in terms of collection. Only one must beregistered with a given registry (usually the uncurried version). The Resetmethod deletes all metrics, even if called on a curried vector.

Note that CurryWith is usually not called directly but through a wrapperaround MetricVec, implementing a vector for a specific Metricimplementation, for example GaugeVec.

func (*MetricVec)Delete ¶

func (m *MetricVec) Delete(labelsLabels)bool

Delete deletes the metric where the variable labels are the same as thosepassed in as labels. It returns true if a metric was deleted.

It is not an error if the number and names of the Labels are inconsistentwith those of the VariableLabels in Desc. However, such inconsistent Labelscan never match an actual metric, so the method will always return false inthat case.

This method is used for the same purpose as DeleteLabelValues(...string). Seethere for pros and cons of the two methods.

func (*MetricVec)DeleteLabelValues ¶

func (m *MetricVec) DeleteLabelValues(lvs ...string)bool

DeleteLabelValues removes the metric where the variable labels are the sameas those passed in as labels (same order as the VariableLabels in Desc). Itreturns true if a metric was deleted.

It is not an error if the number of label values is not the same as thenumber of VariableLabels in Desc. However, such inconsistent label count cannever match an actual metric, so the method will always return false in thatcase.

Note that for more than one label value, this method is prone to mistakescaused by an incorrect order of arguments. Consider Delete(Labels) as analternative to avoid that type of mistake. For higher label numbers, thelatter has a much more readable (albeit more verbose) syntax, but it comeswith a performance overhead (for creating and processing the Labels map).See also the CounterVec example.

func (*MetricVec)DeletePartialMatch ¶added inv1.13.0

func (m *MetricVec) DeletePartialMatch(labelsLabels)int

DeletePartialMatch deletes all metrics where the variable labels contain all of thosepassed in as labels. The order of the labels does not matter.It returns the number of metrics deleted.

Note that curried labels will never be matched if deleting from the curried vector.To match curried labels with DeletePartialMatch, it must be called on the base vector.

func (*MetricVec)Describe ¶

func (m *MetricVec) Describe(ch chan<- *Desc)

Describe implements Collector.

func (*MetricVec)GetMetricWith ¶

func (m *MetricVec) GetMetricWith(labelsLabels) (Metric,error)

GetMetricWith returns the Metric for the given Labels map (the label namesmust match those of the variable labels in Desc). If that label map isaccessed for the first time, a new Metric is created. Implications ofcreating a Metric without using it and keeping the Metric for later useare the same as for GetMetricWithLabelValues.

An error is returned if the number and names of the Labels are inconsistentwith those of the variable labels in Desc (minus any curried labels).

This method is used for the same purpose asGetMetricWithLabelValues(...string). See there for pros and cons of the twomethods.

Note that GetMetricWith is usually not called directly but through a wrapperaround MetricVec, implementing a vector for a specific Metric implementation,for example GaugeVec.

func (*MetricVec)GetMetricWithLabelValues ¶

func (m *MetricVec) GetMetricWithLabelValues(lvs ...string) (Metric,error)

GetMetricWithLabelValues returns the Metric for the given slice of labelvalues (same order as the variable labels in Desc). If that combination oflabel values is accessed for the first time, a new Metric is created (bycalling the newMetric function provided during construction of theMetricVec).

It is possible to call this method without using the returned Metric to onlycreate the new Metric but leave it in its initial state.

Keeping the Metric for later use is possible (and should be considered ifperformance is critical), but keep in mind that Reset, DeleteLabelValues andDelete can be used to delete the Metric from the MetricVec. In that case, theMetric will still exist, but it will not be exported anymore, even if aMetric with the same label values is created later.

An error is returned if the number of label values is not the same as thenumber of variable labels in Desc (minus any curried labels).

Note that GetMetricWithLabelValues is usually not called directly but througha wrapper around MetricVec, implementing a vector for a specific Metricimplementation, for example GaugeVec.

func (*MetricVec)Reset ¶

func (m *MetricVec) Reset()

Reset deletes all metrics in this vector.

typeMultiError ¶

type MultiError []error

MultiError is a slice of errors implementing the error interface. It is usedby a Gatherer to report multiple errors during MetricFamily gathering.

func (*MultiError)Append ¶added inv0.9.0

func (errs *MultiError) Append(errerror)

Append appends the provided error if it is not nil.

func (MultiError)Error ¶

func (errsMultiError) Error()string

Error formats the contained errors as a bullet point list, preceded by thetotal number of errors. Note that this results in a multi-line string.

func (MultiError)MaybeUnwrap ¶

func (errsMultiError) MaybeUnwrap()error

MaybeUnwrap returns nil if len(errs) is 0. It returns the first and onlycontained error as error if len(errs is 1). In all other cases, it returnsthe MultiError directly. This is helpful for returning a MultiError in a waythat only uses the MultiError if needed.

typeMultiTRegistry ¶added inv1.13.0

type MultiTRegistry struct {// contains filtered or unexported fields}

MultiTRegistry is a TransactionalGatherer that joins gathered metrics from multipletransactional gatherers.

It is caller responsibility to ensure two registries have mutually exclusive metric families,no deduplication will happen.

funcNewMultiTRegistry ¶added inv1.13.0

func NewMultiTRegistry(tGatherers ...TransactionalGatherer) *MultiTRegistry

NewMultiTRegistry creates MultiTRegistry.

func (*MultiTRegistry)Gather ¶added inv1.13.0

func (r *MultiTRegistry) Gather() (mfs []*dto.MetricFamily, done func(), errerror)

Gather implements TransactionalGatherer interface.

typeObserver ¶added inv0.9.0

type Observer interface {Observe(float64)}

Observer is the interface that wraps the Observe method, which is used byHistogram and Summary to add observations.

typeObserverFunc ¶added inv0.9.0

type ObserverFunc func(float64)

The ObserverFunc type is an adapter to allow the use of ordinaryfunctions as Observers. If f is a function with the appropriatesignature, ObserverFunc(f) is an Observer that calls f.

This adapter is usually used in connection with the Timer type, and there aretwo general use cases:

The most common one is to use a Gauge as the Observer for a Timer.See the "Gauge" Timer example.

The more advanced use case is to create a function that dynamically decideswhich Observer to use for observing the duration. See the "Complex" Timerexample.

func (ObserverFunc)Observe ¶added inv0.9.0

func (fObserverFunc) Observe(valuefloat64)

Observe calls f(value). It implements Observer.

typeObserverVec ¶added inv0.9.0

type ObserverVec interface {GetMetricWith(Labels) (Observer,error)GetMetricWithLabelValues(lvs ...string) (Observer,error)With(Labels)ObserverWithLabelValues(...string)ObserverCurryWith(Labels) (ObserverVec,error)MustCurryWith(Labels)ObserverVecCollector}

ObserverVec is an interface implemented by `HistogramVec` and `SummaryVec`.

typeOpts ¶

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.NamespacestringSubsystemstringNamestring// Help provides information about this metric.//// Metrics with the same fully-qualified name must have the same Help// string.Helpstring// 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-labelsConstLabelsLabels// contains filtered or unexported fields}

Opts bundles the options for creating most Metric types. Each metricimplementation XXX has its own XXXOpts type, but in most cases, it is justan alias of this type (which might change when the requirement arises.)

It is mandatory to set Name to a non-empty string. All other fields areoptional and can safely be left at their zero value, although it is stronglyencouraged to set a Help string.

typeProcessCollectorOpts ¶added inv0.9.0

type ProcessCollectorOpts struct {// PidFn returns the PID of the process the collector collects metrics// for. It is called upon each collection. By default, the PID of the// current process is used, as determined on construction time by// calling os.Getpid().PidFn func() (int,error)// If non-empty, each of the collected metrics is prefixed by the// provided string and an underscore ("_").Namespacestring// If true, any error encountered during collection is reported as an// invalid metric (see NewInvalidMetric). Otherwise, errors are ignored// and the collected metrics will be incomplete. (Possibly, no metrics// will be collected at all.) While that's usually not desired, it is// appropriate for the common "mix-in" of process metrics, where process// metrics are nice to have, but failing to collect them should not// disrupt the collection of the remaining metrics.ReportErrorsbool}

ProcessCollectorOpts defines the behavior of a process metrics collectorcreated with NewProcessCollector.

typeRegisterer ¶

type Registerer interface {// Register registers a new Collector to be included in metrics// collection. It returns an error if the descriptors provided by the// Collector are invalid or if they — in combination with descriptors of// already registered Collectors — do not fulfill the consistency and// uniqueness criteria described in the documentation of metric.Desc.//// If the provided Collector is equal to a Collector already registered// (which includes the case of re-registering the same Collector), the// returned error is an instance of AlreadyRegisteredError, which// contains the previously registered Collector.//// A Collector whose Describe method does not yield any Desc is treated// as unchecked. Registration will always succeed. No check for// re-registering (see previous paragraph) is performed. Thus, the// caller is responsible for not double-registering the same unchecked// Collector, and for providing a Collector that will not cause// inconsistent metrics on collection. (This would lead to scrape// errors.)Register(Collector)error// MustRegister works like Register but registers any number of// Collectors and panics upon the first registration that causes an// error.MustRegister(...Collector)// Unregister unregisters the Collector that equals the Collector passed// in as an argument.  (Two Collectors are considered equal if their// Describe method yields the same set of descriptors.) The function// returns whether a Collector was unregistered. Note that an unchecked// Collector cannot be unregistered (as its Describe method does not// yield any descriptor).//// Note that even after unregistering, it will not be possible to// register a new Collector that is inconsistent with the unregistered// Collector, e.g. a Collector collecting metrics with the same name but// a different help string. The rationale here is that the same registry// instance must only collect consistent metrics throughout its// lifetime.Unregister(Collector)bool}

Registerer is the interface for the part of a registry in charge ofregistering and unregistering. Users of custom registries should useRegisterer as type for registration purposes (rather than the Registry typedirectly). In that way, they are free to use custom Registerer implementation(e.g. for testing purposes).

funcWrapRegistererWith ¶added inv0.9.0

func WrapRegistererWith(labelsLabels, regRegisterer)Registerer

WrapRegistererWith returns a Registerer wrapping the providedRegisterer. Collectors registered with the returned Registerer will beregistered with the wrapped Registerer in a modified way. The modifiedCollector adds the provided Labels to all Metrics it collects (asConstLabels). The Metrics collected by the unmodified Collector must notduplicate any of those labels. Wrapping a nil value is valid, resultingin a no-op Registerer.

WrapRegistererWith provides a way to add fixed labels to a subset ofCollectors. It should not be used to add fixed labels to all metricsexposed. See alsohttps://prometheus.io/docs/instrumenting/writing_exporters/#target-labels-not-static-scraped-labels

Conflicts between Collectors registered through the original Registerer withCollectors registered through the wrapping Registerer will still bedetected. Any AlreadyRegisteredError returned by the Register method ofeither Registerer will contain the ExistingCollector in the form it wasprovided to the respective registry.

The Collector example demonstrates a use of WrapRegistererWith.

funcWrapRegistererWithPrefix ¶added inv0.9.0

func WrapRegistererWithPrefix(prefixstring, regRegisterer)Registerer

WrapRegistererWithPrefix returns a Registerer wrapping the providedRegisterer. Collectors registered with the returned Registerer will beregistered with the wrapped Registerer in a modified way. The modifiedCollector adds the provided prefix to the name of all Metrics it collects.Wrapping a nil value is valid, resulting in a no-op Registerer.

WrapRegistererWithPrefix is useful to have one place to prefix all metrics ofa sub-system. To make this work, register metrics of the sub-system with thewrapping Registerer returned by WrapRegistererWithPrefix. It is rarely usefulto use the same prefix for all metrics exposed. In particular, do not prefixmetric names that are standardized across applications, as that would breakhorizontal monitoring, for example the metrics provided by the Go collector(see NewGoCollector) and the process collector (see NewProcessCollector). (Infact, those metrics are already prefixed with "go_" or "process_",respectively.)

typeRegistry ¶

type Registry struct {// contains filtered or unexported fields}

Registry registers Prometheus collectors, collects their metrics, and gathersthem into MetricFamilies for exposition. It implements Registerer, Gatherer,and Collector. The zero value is not usable. Create instances withNewRegistry or NewPedanticRegistry.

Registry implements Collector to allow it to be used for creating groups ofmetrics. See the Grouping example for how this can be done.

Example (Grouping)¶

This example shows how to use multiple registries for registering andunregistering groups of metrics.

package mainimport ("math/rand""strconv""time""github.com/prometheus/client_golang/prometheus")func main() {// Create a global registry.globalReg := prometheus.NewRegistry()// Spawn 10 workers, each of which will have their own group of metrics.for i := 0; i < 10; i++ {// Create a new registry for each worker, which acts as a group of// worker-specific metrics.workerReg := prometheus.NewRegistry()globalReg.Register(workerReg)go func(workerID int) {// Once the worker is done, it can unregister itself.defer globalReg.Unregister(workerReg)workTime := prometheus.NewCounter(prometheus.CounterOpts{Name: "worker_total_work_time_milliseconds",ConstLabels: prometheus.Labels{// Generate a label unique to this worker so its metric doesn't// collide with the metrics from other workers."worker_id": strconv.Itoa(workerID),},})workerReg.MustRegister(workTime)start := time.Now()time.Sleep(time.Millisecond * time.Duration(rand.Intn(100)))workTime.Add(float64(time.Since(start).Milliseconds()))}(i)}}

funcNewPedanticRegistry ¶

func NewPedanticRegistry() *Registry

NewPedanticRegistry returns a registry that checks during collection if eachcollected Metric is consistent with its reported Desc, and if the Desc hasactually been registered with the registry. Unchecked Collectors (those whoseDescribe method does not yield any descriptors) are excluded from the check.

Usually, a Registry will be happy as long as the union of all collectedMetrics is consistent and valid even if some metrics are not consistent withtheir own Desc or a Desc provided by their registered Collector. Well-behavedCollectors and Metrics will only provide consistent Descs. This Registry isuseful to test the implementation of Collectors and Metrics.

funcNewRegistry ¶

func NewRegistry() *Registry

NewRegistry creates a new vanilla Registry without any Collectorspre-registered.

func (*Registry)Collect ¶added inv1.14.0

func (r *Registry) Collect(ch chan<-Metric)

Collect implements Collector.

func (*Registry)Describe ¶added inv1.14.0

func (r *Registry) Describe(ch chan<- *Desc)

Describe implements Collector.

func (*Registry)Gather ¶

func (r *Registry) Gather() ([]*dto.MetricFamily,error)

Gather implements Gatherer.

func (*Registry)MustRegister ¶

func (r *Registry) MustRegister(cs ...Collector)

MustRegister implements Registerer.

func (*Registry)Register ¶

func (r *Registry) Register(cCollector)error

func (*Registry)Unregister ¶

func (r *Registry) Unregister(cCollector)bool

Unregister implements Registerer.

typeSummary ¶

type Summary interface {MetricCollector// Observe adds a single observation to the summary. Observations are// usually positive or zero. Negative observations are accepted but// prevent current versions of Prometheus from properly detecting// counter resets in the sum of observations. See//https://prometheus.io/docs/practices/histograms/#count-and-sum-of-observations// for details.Observe(float64)}

A Summary captures individual observations from an event or sample stream andsummarizes them in a manner similar to traditional summary statistics: 1. sumof observations, 2. observation count, 3. rank estimations.

A typical use-case is the observation of request latencies. By default, aSummary provides the median, the 90th and the 99th percentile of the latencyas rank estimations. However, the default behavior will change in theupcoming v1.0.0 of the library. There will be no rank estimations at all bydefault. For a sane transition, it is recommended to set the desired rankestimations explicitly.

Note that the rank estimations cannot be aggregated in a meaningful way withthe Prometheus query language (i.e. you cannot average or add them). If youneed aggregatable quantiles (e.g. you want the 99th percentile latency of allqueries served across all instances of a service), consider the Histogrammetric type. See the Prometheus documentation for more details.

To create Summary instances, use NewSummary.

Example¶

temps := prometheus.NewSummary(prometheus.SummaryOpts{Name:       "pond_temperature_celsius",Help:       "The temperature of the frog pond.",Objectives: map[float64]float64{0.5: 0.05, 0.9: 0.01, 0.99: 0.001},})// Simulate some observations.for i := 0; i < 1000; i++ {temps.Observe(30 + math.Floor(120*math.Sin(float64(i)*0.1))/10)}// Just for demonstration, let's check the state of the summary by// (ab)using its Write method (which is usually only used by Prometheus// internally).metric := &dto.Metric{}temps.Write(metric)fmt.Println(toNormalizedJSON(sanitizeMetric(metric)))

Output:{"summary":{"sampleCount":"1000","sampleSum":29969.50000000001,"quantile":[{"quantile":0.5,"value":31.1},{"quantile":0.9,"value":41.3},{"quantile":0.99,"value":41.9}],"createdTimestamp":"1970-01-01T00:00:10Z"}}

funcNewSummary ¶

func NewSummary(optsSummaryOpts)Summary

NewSummary creates a new Summary based on the provided SummaryOpts.

typeSummaryOpts ¶

type SummaryOpts struct {// Namespace, Subsystem, and Name are components of the fully-qualified// name of the Summary (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 Summary must be a// valid Prometheus metric name.NamespacestringSubsystemstringNamestring// Help provides information about this Summary.//// Metrics with the same fully-qualified name must have the same Help// string.Helpstring// 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.//// Due to the way a Summary is represented in the Prometheus text format// and how it is handled by the Prometheus server internally, “quantile”// is an illegal label name. Construction of a Summary or SummaryVec// will panic if this label name is used in 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-labelsConstLabelsLabels// Objectives defines the quantile rank estimates with their respective// absolute error. If Objectives[q] = e, then the value reported for q// will be the φ-quantile value for some φ between q-e and q+e. The// default value is an empty map, resulting in a summary without// quantiles.Objectives map[float64]float64// MaxAge defines the duration for which an observation stays relevant// for the summary. Only applies to pre-calculated quantiles, does not// apply to _sum and _count. Must be positive. The default value is// DefMaxAge.MaxAgetime.Duration// AgeBuckets is the number of buckets used to exclude observations that// are older than MaxAge from the summary. A higher number has a// resource penalty, so only increase it if the higher resolution is// really required. For very high observation rates, you might want to// reduce the number of age buckets. With only one age bucket, you will// effectively see a complete reset of the summary each time MaxAge has// passed. The default value is DefAgeBuckets.AgeBucketsuint32// BufCap defines the default sample stream buffer size. The default// value of DefBufCap should suffice for most uses. If there is a need// to increase the value, a multiple of 500 is recommended (because that// is the internal buffer size of the underlying package// "github.com/bmizerany/perks/quantile").BufCapuint32// contains filtered or unexported fields}

SummaryOpts bundles the options for creating a Summary metric. It ismandatory to set Name to a non-empty string. While all other fields areoptional and can safely be left at their zero value, it is recommended to seta help string and to explicitly set the Objectives field to the desired valueas the default value will change in the upcoming v1.0.0 of the library.

typeSummaryVec ¶

type SummaryVec struct {*MetricVec}

SummaryVec is a Collector that bundles a set of Summaries that all share thesame Desc, but have different values for their variable labels. This is usedif you want to count the same thing partitioned by various dimensions(e.g. HTTP request latencies, partitioned by status code and method). Createinstances with NewSummaryVec.

Example¶

temps := prometheus.NewSummaryVec(prometheus.SummaryOpts{Name:       "pond_temperature_celsius",Help:       "The temperature of the frog pond.",Objectives: map[float64]float64{0.5: 0.05, 0.9: 0.01, 0.99: 0.001},},[]string{"species"},)// Simulate some observations.for i := 0; i < 1000; i++ {temps.WithLabelValues("litoria-caerulea").Observe(30 + math.Floor(120*math.Sin(float64(i)*0.1))/10)temps.WithLabelValues("lithobates-catesbeianus").Observe(32 + math.Floor(100*math.Cos(float64(i)*0.11))/10)}// Create a Summary without any observations.temps.WithLabelValues("leiopelma-hochstetteri")// Just for demonstration, let's check the state of the summary vector// by registering it with a custom registry and then let it collect the// metrics.reg := prometheus.NewRegistry()reg.MustRegister(temps)metricFamilies, err := reg.Gather()if err != nil || len(metricFamilies) != 1 {panic("unexpected behavior of custom test registry")}fmt.Println(toNormalizedJSON(sanitizeMetricFamily(metricFamilies[0])))

Output:{"name":"pond_temperature_celsius","help":"The temperature of the frog pond.","type":"SUMMARY","metric":[{"label":[{"name":"species","value":"leiopelma-hochstetteri"}],"summary":{"sampleCount":"0","sampleSum":0,"quantile":[{"quantile":0.5,"value":"NaN"},{"quantile":0.9,"value":"NaN"},{"quantile":0.99,"value":"NaN"}],"createdTimestamp":"1970-01-01T00:00:10Z"}},{"label":[{"name":"species","value":"lithobates-catesbeianus"}],"summary":{"sampleCount":"1000","sampleSum":31956.100000000017,"quantile":[{"quantile":0.5,"value":32.4},{"quantile":0.9,"value":41.4},{"quantile":0.99,"value":41.9}],"createdTimestamp":"1970-01-01T00:00:10Z"}},{"label":[{"name":"species","value":"litoria-caerulea"}],"summary":{"sampleCount":"1000","sampleSum":29969.50000000001,"quantile":[{"quantile":0.5,"value":31.1},{"quantile":0.9,"value":41.3},{"quantile":0.99,"value":41.9}],"createdTimestamp":"1970-01-01T00:00:10Z"}}]}

funcNewSummaryVec ¶

func NewSummaryVec(optsSummaryOpts, labelNames []string) *SummaryVec

NewSummaryVec creates a new SummaryVec based on the provided SummaryOpts andpartitioned by the given label names.

Due to the way a Summary is represented in the Prometheus text format and howit is handled by the Prometheus server internally, “quantile” is an illegallabel name. NewSummaryVec will panic if this label name is used.

func (*SummaryVec)CurryWith ¶added inv0.9.0

func (v *SummaryVec) CurryWith(labelsLabels) (ObserverVec,error)

The metrics contained in the SummaryVec are shared between the curried anduncurried vectors. They are just accessed differently. Curried and uncurriedvectors behave identically in terms of collection. Only one must beregistered with a given registry (usually the uncurried version). The Resetmethod deletes all metrics, even if called on a curried vector.

func (*SummaryVec)GetMetricWith ¶

func (v *SummaryVec) GetMetricWith(labelsLabels) (Observer,error)

GetMetricWith returns the Summary for the given Labels map (the label namesmust match those of the variable labels in Desc). If that label map isaccessed for the first time, a new Summary is created. Implications ofcreating a Summary without using it and keeping the Summary for later use arethe same as for GetMetricWithLabelValues.

An error is returned if the number and names of the Labels are inconsistentwith those of the variable labels in Desc (minus any curried labels).

This method is used for the same purpose asGetMetricWithLabelValues(...string). See there for pros and cons of the twomethods.

func (*SummaryVec)GetMetricWithLabelValues ¶

func (v *SummaryVec) GetMetricWithLabelValues(lvs ...string) (Observer,error)

GetMetricWithLabelValues returns the Summary for the given slice of labelvalues (same order as the variable labels in Desc). If that combination oflabel values is accessed for the first time, a new Summary is created.

It is possible to call this method without using the returned Summary to onlycreate the new Summary but leave it at its starting value, a Summary withoutany observations.

Keeping the Summary for later use is possible (and should be considered ifperformance is critical), but keep in mind that Reset, DeleteLabelValues andDelete can be used to delete the Summary from the SummaryVec. In that case,the Summary will still exist, but it will not be exported anymore, even if aSummary with the same label values is created later. See also the CounterVecexample.

An error is returned if the number of label values is not the same as thenumber of variable labels in Desc (minus any curried labels).

func (*SummaryVec)MustCurryWith ¶added inv0.9.0

func (v *SummaryVec) MustCurryWith(labelsLabels)ObserverVec

MustCurryWith works as CurryWith but panics where CurryWith would havereturned an error.

func (*SummaryVec)With ¶

func (v *SummaryVec) With(labelsLabels)Observer

With works as GetMetricWith, but panics where GetMetricWithLabels would havereturned an error. Not returning an error allows shortcuts like

myVec.With(prometheus.Labels{"code": "404", "method": "GET"}).Observe(42.21)

func (*SummaryVec)WithLabelValues ¶

func (v *SummaryVec) WithLabelValues(lvs ...string)Observer

WithLabelValues works as GetMetricWithLabelValues, but panics whereGetMetricWithLabelValues would have returned an error. Not returning anerror allows shortcuts like

myVec.WithLabelValues("404", "GET").Observe(42.21)

typeSummaryVecOpts ¶added inv1.15.0

type SummaryVecOpts struct {SummaryOpts// VariableLabels are used to partition the metric vector by the given set// of labels. Each label value will be constrained with the optional Constraint// function, if provided.VariableLabelsConstrainableLabels}

SummaryVecOpts bundles the options to create a SummaryVec metric.It is mandatory to set SummaryOpts, see there for mandatory fields. VariableLabelsis optional and can safely be left to its default value.

typeTimer ¶added inv0.9.0

type Timer struct {// contains filtered or unexported fields}

Timer is a helper type to time functions. Use NewTimer to create newinstances.

Example¶

package mainimport ("math/rand""time""github.com/prometheus/client_golang/prometheus")var requestDuration = prometheus.NewHistogram(prometheus.HistogramOpts{Name:    "example_request_duration_seconds",Help:    "Histogram for the runtime of a simple example function.",Buckets: prometheus.LinearBuckets(0.01, 0.01, 10),})func main() {// timer times this example function. It uses a Histogram, but a Summary// would also work, as both implement Observer. Check out// https://prometheus.io/docs/practices/histograms/ for differences.timer := prometheus.NewTimer(requestDuration)defer timer.ObserveDuration()// Do something here that takes time.time.Sleep(time.Duration(rand.NormFloat64()*10000+50000) * time.Microsecond)}

Example (Complex)¶

package mainimport ("net/http""github.com/prometheus/client_golang/prometheus")// apiRequestDuration tracks the duration separate for each HTTP status// class (1xx, 2xx, ...). This creates a fair amount of time series on// the Prometheus server. Usually, you would track the duration of// serving HTTP request without partitioning by outcome. Do something// like this only if needed. Also note how only status classes are// tracked, not every single status code. The latter would create an// even larger amount of time series. Request counters partitioned by// status code are usually OK as each counter only creates one time// series. Histograms are way more expensive, so partition with care and// only where you really need separate latency tracking. Partitioning by// status class is only an example. In concrete cases, other partitions// might make more sense.var apiRequestDuration = prometheus.NewHistogramVec(prometheus.HistogramOpts{Name:    "api_request_duration_seconds",Help:    "Histogram for the request duration of the public API, partitioned by status class.",Buckets: prometheus.ExponentialBuckets(0.1, 1.5, 5),},[]string{"status_class"},)func handler(w http.ResponseWriter, r *http.Request) {status := http.StatusOK// The ObserverFunc gets called by the deferred ObserveDuration and// decides which Histogram's Observe method is called.timer := prometheus.NewTimer(prometheus.ObserverFunc(func(v float64) {switch {case status >= 500: // Server error.apiRequestDuration.WithLabelValues("5xx").Observe(v)case status >= 400: // Client error.apiRequestDuration.WithLabelValues("4xx").Observe(v)case status >= 300: // Redirection.apiRequestDuration.WithLabelValues("3xx").Observe(v)case status >= 200: // Success.apiRequestDuration.WithLabelValues("2xx").Observe(v)default: // Informational.apiRequestDuration.WithLabelValues("1xx").Observe(v)}}))defer timer.ObserveDuration()// Handle the request. Set status accordingly.// ...}func main() {http.HandleFunc("/api", handler)}

Example (Gauge)¶

package mainimport ("os""github.com/prometheus/client_golang/prometheus")// If a function is called rarely (i.e. not more often than scrapes// happen) or ideally only once (like in a batch job), it can make sense// to use a Gauge for timing the function call. For timing a batch job// and pushing the result to a Pushgateway, see also the comprehensive// example in the push package.var funcDuration = prometheus.NewGauge(prometheus.GaugeOpts{Name: "example_function_duration_seconds",Help: "Duration of the last call of an example function.",})func run() error {// The Set method of the Gauge is used to observe the duration.timer := prometheus.NewTimer(prometheus.ObserverFunc(funcDuration.Set))defer timer.ObserveDuration()// Do something. Return errors as encountered. The use of 'defer' above// makes sure the function is still timed properly.return nil}func main() {if err := run(); err != nil {os.Exit(1)}}

funcNewTimer ¶added inv0.9.0

func NewTimer(oObserver) *Timer

NewTimer creates a new Timer. The provided Observer is used to observe aduration in seconds. If the Observer implements ExemplarObserver, passing exemplarlater on will be also supported.Timer is usually used to time a function call in thefollowing way:

func TimeMe() {    timer := NewTimer(myHistogram)    defer timer.ObserveDuration()    // Do actual work.}

func TimeMeWithExemplar() {    timer := NewTimer(myHistogram)    defer timer.ObserveDurationWithExemplar(exemplar)    // Do actual work.}

func (*Timer)ObserveDuration ¶added inv0.9.0

func (t *Timer) ObserveDuration()time.Duration

ObserveDuration records the duration passed since the Timer was created withNewTimer. It calls the Observe method of the Observer provided duringconstruction with the duration in seconds as an argument. The observedduration is also returned. ObserveDuration is usually called with a deferstatement.

Note that this method is only guaranteed to never observe negative durationsif used with Go1.9+.

func (*Timer)ObserveDurationWithExemplar ¶added inv1.15.0

func (t *Timer) ObserveDurationWithExemplar(exemplarLabels)time.Duration

ObserveDurationWithExemplar is like ObserveDuration, but it will alsoobserve exemplar with the duration unless exemplar is nil or provided Observer can'tbe casted to ExemplarObserver.

typeTransactionalGatherer ¶added inv1.13.0

type TransactionalGatherer interface {// Gather returns metrics in a lexicographically sorted slice// of uniquely named MetricFamily protobufs. Gather ensures that the// returned slice is valid and self-consistent so that it can be used// for valid exposition. As an exception to the strict consistency// requirements described for metric.Desc, Gather will tolerate// different sets of label names for metrics of the same metric family.//// Even if an error occurs, Gather attempts to gather as many metrics as// possible. Hence, if a non-nil error is returned, the returned// MetricFamily slice could be nil (in case of a fatal error that// prevented any meaningful metric collection) or contain a number of// MetricFamily protobufs, some of which might be incomplete, and some// might be missing altogether. The returned error (which might be a// MultiError) explains the details. Note that this is mostly useful for// debugging purposes. If the gathered protobufs are to be used for// exposition in actual monitoring, it is almost always better to not// expose an incomplete result and instead disregard the returned// MetricFamily protobufs in case the returned error is non-nil.//// Important: done is expected to be triggered (even if the error occurs!)// once caller does not need returned slice of dto.MetricFamily.Gather() (_ []*dto.MetricFamily, done func(), errerror)}

TransactionalGatherer represents transactional gatherer that can be triggered to notify gatherer that memoryused by metric family is no longer used by a caller. This allows implementations with cache.

funcToTransactionalGatherer ¶added inv1.13.0

func ToTransactionalGatherer(gGatherer)TransactionalGatherer

ToTransactionalGatherer transforms Gatherer to transactional one with noop as done function.

typeUnconstrainedLabels ¶added inv1.15.0

type UnconstrainedLabels []string

UnconstrainedLabels represents collection of label without any constraint ontheir value. Thus, it is simply a collection of label names.

UnconstrainedLabels([]string{ "A", "B" })

is equivalent to

ConstrainedLabels {  { Name: "A" },  { Name: "B" },}

typeUntypedFunc ¶

type UntypedFunc interface {MetricCollector}

UntypedFunc works like GaugeFunc but the collected metric is of type"Untyped". UntypedFunc is useful to mirror an external metric of unknowntype.

To create UntypedFunc instances, use NewUntypedFunc.

funcNewUntypedFunc ¶

func NewUntypedFunc(optsUntypedOpts, function func()float64)UntypedFunc

NewUntypedFunc creates a new UntypedFunc based on the providedUntypedOpts. The value reported is determined by calling the given functionfrom within the Write method. Take into account that metric collection mayhappen concurrently. If that results in concurrent calls to Write, like inthe case where an UntypedFunc is directly registered with Prometheus, theprovided function must be concurrency-safe.

typeUntypedOpts ¶

type UntypedOptsOpts

UntypedOpts is an alias for Opts. See there for doc comments.

typeValueType ¶

type ValueTypeint

ValueType is an enumeration of metric types that represent a simple value.

const (CounterValue ValueTypeGaugeValueUntypedValue)

Possible values for the ValueType enum. Use UntypedValue to mark a metricwith an unknown type.

func (ValueType)ToDTO ¶added inv1.13.0

func (vValueType) ToDTO() *dto.MetricType

Source Files¶

View all Source files

Directories¶

Path	Synopsis
collectors Package collectors provides implementations of prometheus.Collector to conveniently collect process and Go-related metrics.	Package collectors provides implementations of prometheus.Collector to conveniently collect process and Go-related metrics.
version
graphite Package graphite provides a bridge to push Prometheus metrics to a Graphite server.	Package graphite provides a bridge to push Prometheus metrics to a Graphite server.
internal
promauto Package promauto provides alternative constructors for the fundamental Prometheus metric types and their …Vec and …Func variants.	Package promauto provides alternative constructors for the fundamental Prometheus metric types and their …Vec and …Func variants.
promhttp Package promhttp provides tooling around HTTP servers and clients.	Package promhttp provides tooling around HTTP servers and clients.
internal
zstd Package zstd activates support for zstd compression.	Package zstd activates support for zstd compression.
push Package push provides functions to push metrics to a Pushgateway.	Package push provides functions to push metrics to a Pushgateway.
testutil Package testutil provides helpers to test code using the prometheus package of client_golang.	Package testutil provides helpers to test code using the prometheus package of client_golang.
promlint Package promlint provides a linter for Prometheus metrics.	Package promlint provides a linter for Prometheus metrics.
promlint/validations

?	: This menu
/	: Search site
f orF	: Jump to
y orY	: Canonical URL

Movatterモバイル変換

Details

Repository

Links

README¶

Documentation¶

Overview¶

A Basic Example¶

Metrics¶

Custom Collectors and constant Metrics¶

Advanced Uses of the Registry¶

HTTP Exposition¶

Pushing to the Pushgateway¶

Graphite Bridge¶

Other Means of Exposition¶

Index¶

Examples¶

Constants¶

Variables¶

Functions¶

funcBuildFQName¶

funcDescribeByCollect¶added inv0.9.0

funcExponentialBuckets¶

funcExponentialBucketsRange¶added inv0.12.1

funcLinearBuckets¶

funcMakeLabelPairs¶added inv0.12.1

funcMustRegister¶

funcNewPidFileFn¶added inv0.12.1

funcRegister¶

funcUnregister¶

funcWriteToTextfile¶added inv0.9.1

Types¶

typeAlreadyRegisteredError¶

func (AlreadyRegisteredError)Error¶

typeCollector¶

funcNewBuildInfoCollectordeprecatedadded inv0.9.4

funcNewExpvarCollectordeprecated

funcNewGoCollectordeprecated

funcNewProcessCollectordeprecated

funcWrapCollectorWith¶added inv1.23.0

funcWrapCollectorWithPrefix¶added inv1.23.0

typeCollectorFunc¶added inv1.22.0

func (CollectorFunc)Collect¶added inv1.22.0

func (CollectorFunc)Describe¶added inv1.22.0

typeConstrainableLabels¶added inv1.15.0

typeConstrainedLabel¶added inv1.15.0

typeConstrainedLabels¶added inv1.15.0

typeCounter¶

funcNewCounter¶

typeCounterFunc¶

funcNewCounterFunc¶

typeCounterOpts¶

typeCounterVec¶

funcNewCounterVec¶

func (*CounterVec)CurryWith¶added inv0.9.0

func (*CounterVec)GetMetricWith¶

func (*CounterVec)GetMetricWithLabelValues¶

func (*CounterVec)MustCurryWith¶added inv0.9.0

func (*CounterVec)With¶

func (*CounterVec)WithLabelValues¶

typeCounterVecOpts¶added inv1.15.0

typeDesc¶

funcNewDesc¶

funcNewInvalidDesc¶

func (*Desc)String¶

typeExemplar¶added inv1.13.0

typeExemplarAdder¶added inv0.12.1

typeExemplarObserver¶added inv0.12.1

typeGatherer¶

typeGathererFunc¶

func (GathererFunc)Gather¶

typeGatherers¶

func (Gatherers)Gather¶

typeGauge¶

funcNewGauge¶

typeGaugeFunc¶

funcNewGaugeFunc¶

typeGaugeOpts¶

typeGaugeVec¶

funcNewGaugeVec¶

README ¶

funcBuildFQName ¶

funcDescribeByCollect ¶added inv0.9.0

funcExponentialBuckets ¶

funcExponentialBucketsRange ¶added inv0.12.1

funcLinearBuckets ¶

funcMakeLabelPairs ¶added inv0.12.1

funcMustRegister ¶

funcNewPidFileFn ¶added inv0.12.1

funcRegister ¶

funcUnregister ¶

funcWriteToTextfile ¶added inv0.9.1

typeAlreadyRegisteredError ¶

func (AlreadyRegisteredError)Error ¶

typeCollector ¶

funcWrapCollectorWith ¶added inv1.23.0

funcWrapCollectorWithPrefix ¶added inv1.23.0

typeCollectorFunc ¶added inv1.22.0

func (CollectorFunc)Collect ¶added inv1.22.0

func (CollectorFunc)Describe ¶added inv1.22.0

typeConstrainableLabels ¶added inv1.15.0

typeConstrainedLabel ¶added inv1.15.0

typeConstrainedLabels ¶added inv1.15.0

typeCounter ¶

funcNewCounter ¶

typeCounterFunc ¶

funcNewCounterFunc ¶

typeCounterOpts ¶

typeCounterVec ¶

funcNewCounterVec ¶

func (*CounterVec)CurryWith ¶added inv0.9.0

func (*CounterVec)GetMetricWith ¶

func (*CounterVec)GetMetricWithLabelValues ¶

func (*CounterVec)MustCurryWith ¶added inv0.9.0

func (*CounterVec)With ¶

func (*CounterVec)WithLabelValues ¶

typeCounterVecOpts ¶added inv1.15.0

typeDesc ¶

funcNewDesc ¶

funcNewInvalidDesc ¶

func (*Desc)String ¶

typeExemplar ¶added inv1.13.0

typeExemplarAdder ¶added inv0.12.1

typeExemplarObserver ¶added inv0.12.1

typeGatherer ¶

typeGathererFunc ¶

func (GathererFunc)Gather ¶

typeGatherers ¶

func (Gatherers)Gather ¶

typeGauge ¶

funcNewGauge ¶

typeGaugeFunc ¶

funcNewGaugeFunc ¶

typeGaugeOpts ¶

typeGaugeVec ¶

funcNewGaugeVec ¶

func (*GaugeVec)CurryWith ¶added inv0.9.0

func (*GaugeVec)GetMetricWith ¶

func (*GaugeVec)GetMetricWithLabelValues ¶

func (*GaugeVec)MustCurryWith ¶added inv0.9.0

func (*GaugeVec)With ¶

func (*GaugeVec)WithLabelValues ¶

typeGaugeVecOpts ¶added inv1.15.0

typeHistogram ¶

funcNewHistogram ¶

typeHistogramOpts ¶

typeHistogramVec ¶

funcNewHistogramVec ¶

func (*HistogramVec)CurryWith ¶added inv0.9.0

func (*HistogramVec)GetMetricWith ¶

func (*HistogramVec)GetMetricWithLabelValues ¶

func (*HistogramVec)MustCurryWith ¶added inv0.9.0

func (*HistogramVec)With ¶

func (*HistogramVec)WithLabelValues ¶

typeHistogramVecOpts ¶added inv1.15.0

typeLabelConstraint ¶added inv1.17.0

typeLabels ¶

typeMetric ¶

funcMustNewConstHistogram ¶

funcMustNewConstHistogramWithCreatedTimestamp ¶added inv1.20.0