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