khenaidoo | 59ce9dd | 2019-11-11 13:05:32 -0500 | [diff] [blame] | 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 |
| 5 | // |
| 6 | // http://www.apache.org/licenses/LICENSE-2.0 |
| 7 | // |
| 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. |
| 13 | |
| 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. |
| 20 | // |
| 21 | // All exported functions and methods are safe to be used concurrently unless |
| 22 | // specified otherwise. |
| 23 | // |
| 24 | // A Basic Example |
| 25 | // |
| 26 | // As a starting point, a very basic usage example: |
| 27 | // |
| 28 | // package main |
| 29 | // |
| 30 | // import ( |
| 31 | // "log" |
| 32 | // "net/http" |
| 33 | // |
| 34 | // "github.com/prometheus/client_golang/prometheus" |
| 35 | // "github.com/prometheus/client_golang/prometheus/promhttp" |
| 36 | // ) |
| 37 | // |
| 38 | // var ( |
| 39 | // cpuTemp = prometheus.NewGauge(prometheus.GaugeOpts{ |
| 40 | // Name: "cpu_temperature_celsius", |
| 41 | // Help: "Current temperature of the CPU.", |
| 42 | // }) |
| 43 | // hdFailures = prometheus.NewCounterVec( |
| 44 | // prometheus.CounterOpts{ |
| 45 | // Name: "hd_errors_total", |
| 46 | // Help: "Number of hard-disk errors.", |
| 47 | // }, |
| 48 | // []string{"device"}, |
| 49 | // ) |
| 50 | // ) |
| 51 | // |
| 52 | // func init() { |
| 53 | // // Metrics have to be registered to be exposed: |
| 54 | // prometheus.MustRegister(cpuTemp) |
| 55 | // prometheus.MustRegister(hdFailures) |
| 56 | // } |
| 57 | // |
| 58 | // func main() { |
| 59 | // cpuTemp.Set(65.3) |
| 60 | // hdFailures.With(prometheus.Labels{"device":"/dev/sda"}).Inc() |
| 61 | // |
| 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)) |
| 66 | // } |
| 67 | // |
| 68 | // |
| 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. |
| 71 | // |
| 72 | // Metrics |
| 73 | // |
| 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. |
| 81 | // |
| 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/ |
| 86 | // |
khenaidoo | 2672188 | 2021-08-11 17:42:52 -0400 | [diff] [blame^] | 87 | // In addition to the fundamental metric types Gauge, Counter, Summary, and |
| 88 | // Histogram, a very important part of the Prometheus data model is the |
| 89 | // partitioning of samples along dimensions called labels, which results in |
khenaidoo | 59ce9dd | 2019-11-11 13:05:32 -0500 | [diff] [blame] | 90 | // metric vectors. The fundamental types are GaugeVec, CounterVec, SummaryVec, |
khenaidoo | 2672188 | 2021-08-11 17:42:52 -0400 | [diff] [blame^] | 91 | // and HistogramVec. |
khenaidoo | 59ce9dd | 2019-11-11 13:05:32 -0500 | [diff] [blame] | 92 | // |
| 93 | // While only the fundamental metric types implement the Metric interface, both |
| 94 | // the metrics and their vector versions implement the Collector interface. A |
| 95 | // Collector manages the collection of a number of Metrics, but for convenience, |
khenaidoo | 2672188 | 2021-08-11 17:42:52 -0400 | [diff] [blame^] | 96 | // a Metric can also “collect itself”. Note that Gauge, Counter, Summary, and |
| 97 | // Histogram are interfaces themselves while GaugeVec, CounterVec, SummaryVec, |
| 98 | // and HistogramVec are not. |
khenaidoo | 59ce9dd | 2019-11-11 13:05:32 -0500 | [diff] [blame] | 99 | // |
| 100 | // To create instances of Metrics and their vector versions, you need a suitable |
khenaidoo | 2672188 | 2021-08-11 17:42:52 -0400 | [diff] [blame^] | 101 | // …Opts struct, i.e. GaugeOpts, CounterOpts, SummaryOpts, or HistogramOpts. |
khenaidoo | 59ce9dd | 2019-11-11 13:05:32 -0500 | [diff] [blame] | 102 | // |
| 103 | // Custom Collectors and constant Metrics |
| 104 | // |
| 105 | // While you could create your own implementations of Metric, most likely you |
| 106 | // will only ever implement the Collector interface on your own. At a first |
| 107 | // glance, a custom Collector seems handy to bundle Metrics for common |
| 108 | // registration (with the prime example of the different metric vectors above, |
| 109 | // which bundle all the metrics of the same name but with different labels). |
| 110 | // |
| 111 | // There is a more involved use case, too: If you already have metrics |
| 112 | // available, created outside of the Prometheus context, you don't need the |
| 113 | // interface of the various Metric types. You essentially want to mirror the |
| 114 | // existing numbers into Prometheus Metrics during collection. An own |
| 115 | // implementation of the Collector interface is perfect for that. You can create |
| 116 | // Metric instances “on the fly” using NewConstMetric, NewConstHistogram, and |
khenaidoo | 2672188 | 2021-08-11 17:42:52 -0400 | [diff] [blame^] | 117 | // NewConstSummary (and their respective Must… versions). NewConstMetric is used |
| 118 | // for all metric types with just a float64 as their value: Counter, Gauge, and |
| 119 | // a special “type” called Untyped. Use the latter if you are not sure if the |
| 120 | // mirrored metric is a Counter or a Gauge. Creation of the Metric instance |
| 121 | // happens in the Collect method. The Describe method has to return separate |
| 122 | // Desc instances, representative of the “throw-away” metrics to be created |
| 123 | // later. NewDesc comes in handy to create those Desc instances. Alternatively, |
| 124 | // you could return no Desc at all, which will mark the Collector “unchecked”. |
| 125 | // No checks are performed at registration time, but metric consistency will |
| 126 | // still be ensured at scrape time, i.e. any inconsistencies will lead to scrape |
khenaidoo | 59ce9dd | 2019-11-11 13:05:32 -0500 | [diff] [blame] | 127 | // errors. Thus, with unchecked Collectors, the responsibility to not collect |
| 128 | // metrics that lead to inconsistencies in the total scrape result lies with the |
| 129 | // implementer of the Collector. While this is not a desirable state, it is |
| 130 | // sometimes necessary. The typical use case is a situation where the exact |
| 131 | // metrics to be returned by a Collector cannot be predicted at registration |
| 132 | // time, but the implementer has sufficient knowledge of the whole system to |
| 133 | // guarantee metric consistency. |
| 134 | // |
| 135 | // The Collector example illustrates the use case. You can also look at the |
| 136 | // source code of the processCollector (mirroring process metrics), the |
| 137 | // goCollector (mirroring Go metrics), or the expvarCollector (mirroring expvar |
| 138 | // metrics) as examples that are used in this package itself. |
| 139 | // |
| 140 | // If you just need to call a function to get a single float value to collect as |
| 141 | // a metric, GaugeFunc, CounterFunc, or UntypedFunc might be interesting |
| 142 | // shortcuts. |
| 143 | // |
| 144 | // Advanced Uses of the Registry |
| 145 | // |
| 146 | // While MustRegister is the by far most common way of registering a Collector, |
| 147 | // sometimes you might want to handle the errors the registration might cause. |
| 148 | // As suggested by the name, MustRegister panics if an error occurs. With the |
| 149 | // Register function, the error is returned and can be handled. |
| 150 | // |
| 151 | // An error is returned if the registered Collector is incompatible or |
| 152 | // inconsistent with already registered metrics. The registry aims for |
| 153 | // consistency of the collected metrics according to the Prometheus data model. |
| 154 | // Inconsistencies are ideally detected at registration time, not at collect |
| 155 | // time. The former will usually be detected at start-up time of a program, |
| 156 | // while the latter will only happen at scrape time, possibly not even on the |
| 157 | // first scrape if the inconsistency only becomes relevant later. That is the |
| 158 | // main reason why a Collector and a Metric have to describe themselves to the |
| 159 | // registry. |
| 160 | // |
| 161 | // So far, everything we did operated on the so-called default registry, as it |
| 162 | // can be found in the global DefaultRegisterer variable. With NewRegistry, you |
| 163 | // can create a custom registry, or you can even implement the Registerer or |
| 164 | // Gatherer interfaces yourself. The methods Register and Unregister work in the |
| 165 | // same way on a custom registry as the global functions Register and Unregister |
| 166 | // on the default registry. |
| 167 | // |
| 168 | // There are a number of uses for custom registries: You can use registries with |
| 169 | // special properties, see NewPedanticRegistry. You can avoid global state, as |
| 170 | // it is imposed by the DefaultRegisterer. You can use multiple registries at |
| 171 | // the same time to expose different metrics in different ways. You can use |
| 172 | // separate registries for testing purposes. |
| 173 | // |
| 174 | // Also note that the DefaultRegisterer comes registered with a Collector for Go |
| 175 | // runtime metrics (via NewGoCollector) and a Collector for process metrics (via |
| 176 | // NewProcessCollector). With a custom registry, you are in control and decide |
| 177 | // yourself about the Collectors to register. |
| 178 | // |
| 179 | // HTTP Exposition |
| 180 | // |
| 181 | // The Registry implements the Gatherer interface. The caller of the Gather |
| 182 | // method can then expose the gathered metrics in some way. Usually, the metrics |
| 183 | // are served via HTTP on the /metrics endpoint. That's happening in the example |
| 184 | // above. The tools to expose metrics via HTTP are in the promhttp sub-package. |
| 185 | // |
| 186 | // Pushing to the Pushgateway |
| 187 | // |
| 188 | // Function for pushing to the Pushgateway can be found in the push sub-package. |
| 189 | // |
| 190 | // Graphite Bridge |
| 191 | // |
| 192 | // Functions and examples to push metrics from a Gatherer to Graphite can be |
| 193 | // found in the graphite sub-package. |
| 194 | // |
| 195 | // Other Means of Exposition |
| 196 | // |
| 197 | // More ways of exposing metrics can easily be added by following the approaches |
| 198 | // of the existing implementations. |
| 199 | package prometheus |