Awesome
metrics - lightweight package for exporting metrics in Prometheus format
Features
- Lightweight. Has minimal number of third-party dependencies and all these deps are small. See this article for details.
- Easy to use. See the API docs.
- Fast.
- Allows exporting distinct metric sets via distinct endpoints. See Set.
- Supports easy-to-use histograms, which just work without any tuning. Read more about VictoriaMetrics histograms at this article.
- Can push metrics to VictoriaMetrics or to any other remote storage, which accepts metrics in Prometheus text exposition format. See these docs.
Limitations
- It doesn't implement advanced functionality from github.com/prometheus/client_golang.
Usage
import "github.com/VictoriaMetrics/metrics"
// Register various metrics.
// Metric name may contain labels in Prometheus format - see below.
var (
// Register counter without labels.
requestsTotal = metrics.NewCounter("requests_total")
// Register summary with a single label.
requestDuration = metrics.NewSummary(`requests_duration_seconds{path="/foobar/baz"}`)
// Register gauge with two labels.
queueSize = metrics.NewGauge(`queue_size{queue="foobar",topic="baz"}`, func() float64 {
return float64(foobarQueue.Len())
})
// Register histogram with a single label.
responseSize = metrics.NewHistogram(`response_size{path="/foo/bar"}`)
)
// ...
func requestHandler() {
// Increment requestTotal counter.
requestsTotal.Inc()
startTime := time.Now()
processRequest()
// Update requestDuration summary.
requestDuration.UpdateDuration(startTime)
// Update responseSize histogram.
responseSize.Update(responseSize)
}
// Expose the registered metrics at `/metrics` path.
http.HandleFunc("/metrics", func(w http.ResponseWriter, req *http.Request) {
metrics.WritePrometheus(w, true)
})
// ... or push registered metrics every 10 seconds to http://victoria-metrics:8428/api/v1/import/prometheus
// with the added `instance="foobar"` label to all the pushed metrics.
metrics.InitPush("http://victoria-metrics:8428/api/v1/import/prometheus", 10*time.Second, `instance="foobar"`, true)
By default, exposed metrics do not have
TYPE
or HELP
meta information. Call ExposeMetadata(true)
in order to generate TYPE
and HELP
meta information per each metric.
See docs for more info.
Users
Metrics
has been extracted from VictoriaMetrics sources. See this article for more info aboutVictoriaMetrics
.
FAQ
Why the metrics
API isn't compatible with github.com/prometheus/client_golang
?
Because the github.com/prometheus/client_golang
is too complex and is hard to use.
Why the metrics.WritePrometheus
doesn't expose documentation for each metric?
Because this documentation is ignored by Prometheus. The documentation is for users. Just give meaningful names to the exported metrics or add comments in the source code or in other suitable place explaining each metric exposed from your application.
How to implement CounterVec in metrics
?
Just use GetOrCreateCounter
instead of CounterVec.With
. See this example for details.
Why Histogram buckets contain vmrange
labels instead of le
labels like in Prometheus histograms?
Buckets with vmrange
labels occupy less disk space compared to Promethes-style buckets with le
labels,
because vmrange
buckets don't include counters for the previous ranges. VictoriaMetrics provides prometheus_buckets
function, which converts vmrange
buckets to Prometheus-style buckets with le
labels. This is useful for building heatmaps in Grafana.
Additionally, its' histogram_quantile
function transparently handles histogram buckets with vmrange
labels.