1 // Copyright 2014 The Prometheus Authors
2 // Licensed under the Apache License, Version 2.0 (the "License");
3 // you may not use this file except in compliance with the License.
4 // You may obtain a copy of the License at
6 // http://www.apache.org/licenses/LICENSE-2.0
8 // Unless required by applicable law or agreed to in writing, software
9 // distributed under the License is distributed on an "AS IS" BASIS,
10 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11 // See the License for the specific language governing permissions and
12 // limitations under the License.
14 // Package prometheus is the core instrumentation package. It provides metrics
15 // primitives to instrument code for monitoring. It also offers a registry for
16 // metrics. Sub-packages allow to expose the registered metrics via HTTP
17 // (package promhttp) or push them to a Pushgateway (package push). There is
18 // also a sub-package promauto, which provides metrics constructors with
19 // automatic registration.
21 // All exported functions and methods are safe to be used concurrently unless
22 // specified otherwise.
26 // As a starting point, a very basic usage example:
34 // "github.com/prometheus/client_golang/prometheus"
35 // "github.com/prometheus/client_golang/prometheus/promhttp"
39 // cpuTemp = prometheus.NewGauge(prometheus.GaugeOpts{
40 // Name: "cpu_temperature_celsius",
41 // Help: "Current temperature of the CPU.",
43 // hdFailures = prometheus.NewCounterVec(
44 // prometheus.CounterOpts{
45 // Name: "hd_errors_total",
46 // Help: "Number of hard-disk errors.",
48 // []string{"device"},
53 // // Metrics have to be registered to be exposed:
54 // prometheus.MustRegister(cpuTemp)
55 // prometheus.MustRegister(hdFailures)
60 // hdFailures.With(prometheus.Labels{"device":"/dev/sda"}).Inc()
62 // // The Handler function provides a default handler to expose metrics
63 // // via an HTTP server. "/metrics" is the usual endpoint for that.
64 // http.Handle("/metrics", promhttp.Handler())
65 // log.Fatal(http.ListenAndServe(":8080", nil))
69 // This is a complete program that exports two metrics, a Gauge and a Counter,
70 // the latter with a label attached to turn it into a (one-dimensional) vector.
74 // The number of exported identifiers in this package might appear a bit
75 // overwhelming. However, in addition to the basic plumbing shown in the example
76 // above, you only need to understand the different metric types and their
77 // vector versions for basic usage. Furthermore, if you are not concerned with
78 // fine-grained control of when and how to register metrics with the registry,
79 // have a look at the promauto package, which will effectively allow you to
80 // ignore registration altogether in simple cases.
82 // Above, you have already touched the Counter and the Gauge. There are two more
83 // advanced metric types: the Summary and Histogram. A more thorough description
84 // of those four metric types can be found in the Prometheus docs:
85 // https://prometheus.io/docs/concepts/metric_types/
87 // A fifth "type" of metric is Untyped. It behaves like a Gauge, but signals the
88 // Prometheus server not to assume anything about its type.
90 // In addition to the fundamental metric types Gauge, Counter, Summary,
91 // Histogram, and Untyped, a very important part of the Prometheus data model is
92 // the partitioning of samples along dimensions called labels, which results in
93 // metric vectors. The fundamental types are GaugeVec, CounterVec, SummaryVec,
94 // HistogramVec, and UntypedVec.
96 // While only the fundamental metric types implement the Metric interface, both
97 // the metrics and their vector versions implement the Collector interface. A
98 // Collector manages the collection of a number of Metrics, but for convenience,
99 // a Metric can also “collect itself”. Note that Gauge, Counter, Summary,
100 // Histogram, and Untyped are interfaces themselves while GaugeVec, CounterVec,
101 // SummaryVec, HistogramVec, and UntypedVec are not.
103 // To create instances of Metrics and their vector versions, you need a suitable
104 // …Opts struct, i.e. GaugeOpts, CounterOpts, SummaryOpts, HistogramOpts, or
107 // Custom Collectors and constant Metrics
109 // While you could create your own implementations of Metric, most likely you
110 // will only ever implement the Collector interface on your own. At a first
111 // glance, a custom Collector seems handy to bundle Metrics for common
112 // registration (with the prime example of the different metric vectors above,
113 // which bundle all the metrics of the same name but with different labels).
115 // There is a more involved use case, too: If you already have metrics
116 // available, created outside of the Prometheus context, you don't need the
117 // interface of the various Metric types. You essentially want to mirror the
118 // existing numbers into Prometheus Metrics during collection. An own
119 // implementation of the Collector interface is perfect for that. You can create
120 // Metric instances “on the fly” using NewConstMetric, NewConstHistogram, and
121 // NewConstSummary (and their respective Must… versions). That will happen in
122 // the Collect method. The Describe method has to return separate Desc
123 // instances, representative of the “throw-away” metrics to be created later.
124 // NewDesc comes in handy to create those Desc instances. Alternatively, you
125 // could return no Desc at all, which will mark the Collector “unchecked”. No
126 // checks are performed at registration time, but metric consistency will still
127 // be ensured at scrape time, i.e. any inconsistencies will lead to scrape
128 // errors. Thus, with unchecked Collectors, the responsibility to not collect
129 // metrics that lead to inconsistencies in the total scrape result lies with the
130 // implementer of the Collector. While this is not a desirable state, it is
131 // sometimes necessary. The typical use case is a situation where the exact
132 // metrics to be returned by a Collector cannot be predicted at registration
133 // time, but the implementer has sufficient knowledge of the whole system to
134 // guarantee metric consistency.
136 // The Collector example illustrates the use case. You can also look at the
137 // source code of the processCollector (mirroring process metrics), the
138 // goCollector (mirroring Go metrics), or the expvarCollector (mirroring expvar
139 // metrics) as examples that are used in this package itself.
141 // If you just need to call a function to get a single float value to collect as
142 // a metric, GaugeFunc, CounterFunc, or UntypedFunc might be interesting
145 // Advanced Uses of the Registry
147 // While MustRegister is the by far most common way of registering a Collector,
148 // sometimes you might want to handle the errors the registration might cause.
149 // As suggested by the name, MustRegister panics if an error occurs. With the
150 // Register function, the error is returned and can be handled.
152 // An error is returned if the registered Collector is incompatible or
153 // inconsistent with already registered metrics. The registry aims for
154 // consistency of the collected metrics according to the Prometheus data model.
155 // Inconsistencies are ideally detected at registration time, not at collect
156 // time. The former will usually be detected at start-up time of a program,
157 // while the latter will only happen at scrape time, possibly not even on the
158 // first scrape if the inconsistency only becomes relevant later. That is the
159 // main reason why a Collector and a Metric have to describe themselves to the
162 // So far, everything we did operated on the so-called default registry, as it
163 // can be found in the global DefaultRegisterer variable. With NewRegistry, you
164 // can create a custom registry, or you can even implement the Registerer or
165 // Gatherer interfaces yourself. The methods Register and Unregister work in the
166 // same way on a custom registry as the global functions Register and Unregister
167 // on the default registry.
169 // There are a number of uses for custom registries: You can use registries with
170 // special properties, see NewPedanticRegistry. You can avoid global state, as
171 // it is imposed by the DefaultRegisterer. You can use multiple registries at
172 // the same time to expose different metrics in different ways. You can use
173 // separate registries for testing purposes.
175 // Also note that the DefaultRegisterer comes registered with a Collector for Go
176 // runtime metrics (via NewGoCollector) and a Collector for process metrics (via
177 // NewProcessCollector). With a custom registry, you are in control and decide
178 // yourself about the Collectors to register.
182 // The Registry implements the Gatherer interface. The caller of the Gather
183 // method can then expose the gathered metrics in some way. Usually, the metrics
184 // are served via HTTP on the /metrics endpoint. That's happening in the example
185 // above. The tools to expose metrics via HTTP are in the promhttp sub-package.
186 // (The top-level functions in the prometheus package are deprecated.)
188 // Pushing to the Pushgateway
190 // Function for pushing to the Pushgateway can be found in the push sub-package.
194 // Functions and examples to push metrics from a Gatherer to Graphite can be
195 // found in the graphite sub-package.
197 // Other Means of Exposition
199 // More ways of exposing metrics can easily be added by following the approaches
200 // of the existing implementations.
Code Review / icn.git / blob