Debian Codegraph @

/

0 files · 0 symbols
README (full)

Build Status GoDoc Go Report codecov

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

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

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 Prometheus-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.

However, for compatibility purposes package provides classic Prometheus Histograms with le labels.

dir .github/
dir debian/
dir testdata/
file LICENSE
file README.md
file counter.go
file counter_example_test.go
file counter_test.go
file floatcounter.go
file floatcounter_example_test.go
file floatcounter_test.go
file gauge.go
file gauge_example_test.go
file gauge_test.go
file go.mod
file go.sum
file go_metrics.go
file go_metrics_test.go
file histogram.go
file histogram_example_test.go
file histogram_test.go
file histogram_timing_test.go
file metrics.go
file metrics_example_test.go
file metrics_test.go
file process_metrics_darwin.go
file process_metrics_darwin_cgo.c
file process_metrics_darwin_cgo.go
file process_metrics_darwin_nocgo.go
file process_metrics_linux.go
file process_metrics_linux_test.go
file process_metrics_other.go
file process_metrics_solaris.go
file process_metrics_solaris_test.go
file process_metrics_windows.go
file prometheus_histogram.go
file prometheus_histogram_example_test.go
file prometheus_histogram_test.go
file push.go
file push_test.go
file push_timing_test.go
file set.go
file set_example_test.go
file set_test.go
file summary.go
file summary_example_test.go
file summary_test.go
file validator.go
file validator_test.go