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 provides embeddable metric primitives for servers and
15// standardized exposition of telemetry through a web services interface.
16//
17// All exported functions and methods are safe to be used concurrently unless
18// specified otherwise.
19//
20// To expose metrics registered with the Prometheus registry, an HTTP server
21// needs to know about the Prometheus handler. The usual endpoint is "/metrics".
22//
23//     http.Handle("/metrics", prometheus.Handler())
24//
25// As a starting point a very basic usage example:
26//
27//    package main
28//
29//    import (
30//    	"net/http"
31//
32//    	"github.com/prometheus/client_golang/prometheus"
33//    )
34//
35//    var (
36//    	cpuTemp = prometheus.NewGauge(prometheus.GaugeOpts{
37//    		Name: "cpu_temperature_celsius",
38//    		Help: "Current temperature of the CPU.",
39//    	})
40//    	hdFailures = prometheus.NewCounter(prometheus.CounterOpts{
41//    		Name: "hd_errors_total",
42//    		Help: "Number of hard-disk errors.",
43//    	})
44//    )
45//
46//    func init() {
47//    	prometheus.MustRegister(cpuTemp)
48//    	prometheus.MustRegister(hdFailures)
49//    }
50//
51//    func main() {
52//    	cpuTemp.Set(65.3)
53//    	hdFailures.Inc()
54//
55//    	http.Handle("/metrics", prometheus.Handler())
56//    	http.ListenAndServe(":8080", nil)
57//    }
58//
59//
60// This is a complete program that exports two metrics, a Gauge and a Counter.
61// It also exports some stats about the HTTP usage of the /metrics
62// endpoint. (See the Handler function for more detail.)
63//
64// Two more advanced metric types are the Summary and Histogram.
65//
66// In addition to the fundamental metric types Gauge, Counter, Summary, and
67// Histogram, a very important part of the Prometheus data model is the
68// partitioning of samples along dimensions called labels, which results in
69// metric vectors. The fundamental types are GaugeVec, CounterVec, SummaryVec,
70// and HistogramVec.
71//
72// Those are all the parts needed for basic usage. Detailed documentation and
73// examples are provided below.
74//
75// Everything else this package offers is essentially for "power users" only. A
76// few pointers to "power user features":
77//
78// All the various ...Opts structs have a ConstLabels field for labels that
79// never change their value (which is only useful under special circumstances,
80// see documentation of the Opts type).
81//
82// The Untyped metric behaves like a Gauge, but signals the Prometheus server
83// not to assume anything about its type.
84//
85// Functions to fine-tune how the metric registry works: EnableCollectChecks,
86// PanicOnCollectError, Register, Unregister, SetMetricFamilyInjectionHook.
87//
88// For custom metric collection, there are two entry points: Custom Metric
89// implementations and custom Collector implementations. A Metric is the
90// fundamental unit in the Prometheus data model: a sample at a point in time
91// together with its meta-data (like its fully-qualified name and any number of
92// pairs of label name and label value) that knows how to marshal itself into a
93// data transfer object (aka DTO, implemented as a protocol buffer). A Collector
94// gets registered with the Prometheus registry and manages the collection of
95// one or more Metrics. Many parts of this package are building blocks for
96// Metrics and Collectors. Desc is the metric descriptor, actually used by all
97// metrics under the hood, and by Collectors to describe the Metrics to be
98// collected, but only to be dealt with by users if they implement their own
99// Metrics or Collectors. To create a Desc, the BuildFQName function will come
100// in handy. Other useful components for Metric and Collector implementation
101// include: LabelPairSorter to sort the DTO version of label pairs,
102// NewConstMetric and MustNewConstMetric to create "throw away" Metrics at
103// collection time, MetricVec to bundle custom Metrics into a metric vector
104// Collector, SelfCollector to make a custom Metric collect itself.
105//
106// A good example for a custom Collector is the ExpVarCollector included in this
107// package, which exports variables exported via the "expvar" package as
108// Prometheus metrics.
109package prometheus
110