README
¶
Metrics
Go library for working with Prometheus metrics.
Features
- Name Builder: Create valid Prometheus metric names from arbitrary strings
- Pusher: Push metrics to Prometheus Pushgateway
Installation
go get github.com/bborbe/metrics
Usage
Building Metric Names
import "github.com/bborbe/metrics"
// Create a valid Prometheus metric name
name := metrics.BuildName("my-service", "request_count")
// Result: "my_service_request_count"
// Add to existing name
name = name.Add("total")
// Result: "my_service_request_count_total"
The BuildName function:
- Converts to lowercase
- Replaces illegal characters with underscores
- Handles leading numbers
- Collapses multiple underscores
Pushing Metrics
import (
"context"
"github.com/bborbe/metrics"
"github.com/prometheus/client_golang/prometheus"
)
func pushMetrics(ctx context.Context) error {
// Create a registry and register your metrics
prometheusRegistry := prometheus.NewRegistry()
// Create and configure a pusher using the fluent API
pusher := metrics.NewPusher(
"http://monitoring-pushgateway:9091",
metrics.BuildName("kafka", "backup", "my_topic"),
).Gatherer(prometheusRegistry)
// Push metrics to the gateway (using context from caller)
if err := pusher.Push(ctx); err != nil {
return err
}
return nil
}
The pusher supports a fluent API for configuration:
pusher := metrics.NewPusher(url, jobName).
Gatherer(registry). // Use a custom registry
Collector(myCollector). // Add a specific collector
Client(customHTTPClient) // Use a custom HTTP client
Documentation
¶
Overview ¶
Package metrics provides utilities for working with Prometheus metrics.
It includes a name builder for creating valid Prometheus metric names from arbitrary strings, and a pusher for sending metrics to a Prometheus Pushgateway.
Name Builder ¶
The BuildName function creates valid Prometheus metric names by joining strings with underscores, converting to lowercase, and replacing illegal characters:
name := metrics.BuildName("my-service", "request_count")
// Result: "my_service_request_count"
name = name.Add("total")
// Result: "my_service_request_count_total"
Metrics Pusher ¶
The Pusher interface provides a fluent API for pushing metrics to a Prometheus Pushgateway:
func pushMetrics(ctx context.Context) error {
registry := prometheus.NewRegistry()
// ... register your metrics ...
pusher := metrics.NewPusher(url, jobName).
Gatherer(registry).
Push(ctx)
return pusher.Push(ctx)
}
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BuildInfoMetrics ¶ added in v0.5.0
type BuildInfoMetrics interface {
// SetBuildInfo records build provenance for the current process.
// Call exactly once at startup, after argument parsing.
// Does nothing when buildDate is nil (local `go run` without build args).
SetBuildInfo(version, commit string, buildDate *libtime.DateTime)
}
BuildInfoMetrics records build-time provenance as a Prometheus metric.
Emits a GaugeVec "build_info{version, commit}" whose value is the build timestamp in Unix seconds. Service identification comes from the Prometheus "job" label set by the scrape config — not a metric label — so one "build_info" metric is shared across every binary that imports this package.
Typical queries:
time() - build_info // process age in seconds count by (version) (build_info) // distinct versions currently running
func NewBuildInfoMetrics ¶ added in v0.5.0
func NewBuildInfoMetrics() BuildInfoMetrics
NewBuildInfoMetrics returns a BuildInfoMetrics writing to the package-level "build_info" gauge. The gauge is registered against prometheus.DefaultRegisterer at package init.
type Name ¶
type Name string
Name represents a valid Prometheus metric name.
func BuildName ¶
BuildName creates a valid Prometheus metric name from the given strings. It joins the strings with underscores, converts to lowercase, replaces leading numbers and illegal characters with underscores, and collapses multiple consecutive underscores into one.
type Pusher ¶
type Pusher interface {
// Push pushes all registered metrics to the Pushgateway.
Push(ctx context.Context) error
// Gatherer sets the Gatherer to use for collecting metrics and returns the Pusher
// for method chaining.
Gatherer(gatherer prometheus.Gatherer) Pusher
// Collector adds a Collector to the Pusher and returns the Pusher for method chaining.
Collector(collector prometheus.Collector) Pusher
// Client sets a custom HTTP client for the Pusher and returns the Pusher for
// method chaining.
Client(httpClient push.HTTPDoer) Pusher
}
Pusher pushes metrics to a Prometheus Pushgateway using a fluent API pattern. Configure the pusher by chaining Gatherer(), Collector(), or Client() calls before invoking Push() to send the metrics.
Example:
pusher := metrics.NewPusher(url, jobName).
Gatherer(registry).
Collector(myCollector).
Client(customHTTPClient)
if err := pusher.Push(ctx); err != nil {
return err
}
Source Files
Directories