metrics

README

Metrics Package

Overview

The Metrics package provides a flexible and efficient way to instrument Go applications for metrics collection. It supports various metric types and is designed around a singleton pattern to ensure global access and performance. The package defaults to a no-operation implementation for environments where metrics is not required or enabled.

Features

• Singleton Access: Ensures that the entire application uses a single instance of the metrics system.
• Extensible Interface: Supports multiple backend implementations.
• HTTP Metrics Handler: Easy integration with HTTP servers to expose metrics.
• Lazy Loading: Metrics are instantiated only when they are first used, which optimizes resource usage.

Metric Types

• CountMeter: Monotonically increasing counter that resets on application restart.
• CountVecMeter: CountMeter with support for labeling for dimensional data.
• GaugeMeter: Represents a metric that can go up or down.
• GaugeVecMeter: GaugeMeter with label support.
• HistogramMeter: Measures distributions of values into predefined buckets.
• HistogramVecMeter: HistogramMeter with label support.

Usage

Counters

To create a counter:

counter := metrics.Counter("request_count")
counter.Add(1)

For counters with labels:

counterVec := metrics.CounterVec("request_count_by_status", []string{"status"})
counterVec.AddWithLabel(1, map[string]string{"status": "200"})

Gauges

To create a gauge:

gauge := metrics.Gauge("current_users")
gauge.Gauge(5)

For gauges with labels:

gaugeVec := metrics.GaugeVec("current_users_by_tier", []string{"tier"})
gaugeVec.GaugeWithLabel(5, map[string]string{"tier": "premium"})

Histograms

To create a histogram:

histogram := metrics.Histogram("response_times_ms", metrics.Bucket10s)
histogram.Observe(350)

For histograms with labels:

histogramVec := metrics.HistogramVec("response_times_by_route_ms", []string{"route"}, metrics.BucketHTTPReqs)
histogramVec.ObserveWithLabels(350, map[string]string{"route": "/api/data"})

Lazy Loading

To defer the instantiation of any metric:

lazyHistogram := metrics.LazyLoadHistogram("response_times_ms", metrics.Bucket10s)
h := lazyHistogram() // Actual instantiation occurs here
h.Observe(500)

HTTP Handler

To expose metrics via HTTP:

http.Handle("/metrics", metrics.Handler())

Documentation

Index

• Variables
• func HTTPHandler() http.Handler
• func InitializePrometheusMetrics()
• func LazyLoad[T any](f func() T) func() T
• func LazyLoadCounter(name string) func() CountMeter
• func LazyLoadCounterVec(name string, labels []string) func() CountVecMeter
• func LazyLoadGauge(name string) func() GaugeMeter
• func LazyLoadGaugeVec(name string, labels []string) func() GaugeVecMeter
• func LazyLoadHistogram(name string, buckets []int64) func() HistogramMeter
• func LazyLoadHistogramVec(name string, labels []string, buckets []int64) func() HistogramVecMeter
• type CountMeter
  • func Counter(name string) CountMeter
• type CountVecMeter
  • func CounterVec(name string, labels []string) CountVecMeter
• type GaugeMeter
  • func Gauge(name string) GaugeMeter
• type GaugeVecMeter
  • func GaugeVec(name string, labels []string) GaugeVecMeter
• type HistogramMeter
  • func Histogram(name string, buckets []int64) HistogramMeter
• type HistogramVecMeter
  • func HistogramVec(name string, labels []string, buckets []int64) HistogramVecMeter
• type Metrics

Variables

var (
	Bucket10s      = []int64{0, 500, 1000, 2000, 3000, 4000, 5000, 7500, 10_000}
	BucketHTTPReqs = []int64{0, 150, 300, 450, 600, 900, 1200, 1500, 3000}
)

Define standard buckets for histograms

Functions

func HTTPHandler

func HTTPHandler() http.Handler

HTTPHandler returns the http handler for retrieving metrics

func InitializePrometheusMetrics

func InitializePrometheusMetrics()

InitializePrometheusMetrics creates a new instance of the Prometheus service and sets the implementation as the default metrics services

func LazyLoad

func LazyLoad[T any](f func() T) func() T

LazyLoad allows to defer the instantiation of the metric while allowing its definition. More clearly: - it allow metrics to be defined and used package wide (using var) - it avoid metrics definition to determine the singleton to use (noop vs prometheus)

func LazyLoadCounter

func LazyLoadCounter(name string) func() CountMeter

func LazyLoadCounterVec

func LazyLoadCounterVec(name string, labels []string) func() CountVecMeter

func LazyLoadGauge

func LazyLoadGauge(name string) func() GaugeMeter

func LazyLoadGaugeVec

func LazyLoadGaugeVec(name string, labels []string) func() GaugeVecMeter

func LazyLoadHistogram

func LazyLoadHistogram(name string, buckets []int64) func() HistogramMeter

func LazyLoadHistogramVec

func LazyLoadHistogramVec(name string, labels []string, buckets []int64) func() HistogramVecMeter

Types

type CountMeter

type CountMeter interface {
	Add(int64)
}

CountMeter is a cumulative metric that represents a single monotonically increasing counter whose value can only increase or be reset to zero on restart.

func Counter

func Counter(name string) CountMeter

type CountVecMeter

type CountVecMeter interface {
	AddWithLabel(int64, map[string]string)
}

CountVecMeter is a cumulative metric that represents a single monotonically increasing counter whose value can only increase or be reset to zero on restart with a vector of values.

func CounterVec

func CounterVec(name string, labels []string) CountVecMeter

type GaugeMeter

type GaugeMeter interface {
	Add(int64)
	Set(int64)
}

GaugeMeter is a metric that represents a single numeric value, which can arbitrarily go up and down.

func Gauge

func Gauge(name string) GaugeMeter

type GaugeVecMeter

type GaugeVecMeter interface {
	AddWithLabel(int64, map[string]string)
	SetWithLabel(int64, map[string]string)
}

GaugeVecMeter is a metric that represents a single numeric value, which can arbitrarily go up and down with multiple labels.

func GaugeVec

func GaugeVec(name string, labels []string) GaugeVecMeter

type HistogramMeter

type HistogramMeter interface {
	Observe(int64)
}

HistogramMeter represents the type of metric that is calculated by aggregating as a Histogram of all reported measurements over a time interval.

func Histogram

func Histogram(name string, buckets []int64) HistogramMeter

type HistogramVecMeter

type HistogramVecMeter interface {
	ObserveWithLabels(int64, map[string]string)
}

HistogramVecMeter same as the Histogram but with labels

func HistogramVec

func HistogramVec(name string, labels []string, buckets []int64) HistogramVecMeter

type Metrics

type Metrics interface {
	GetOrCreateCountMeter(name string) CountMeter
	GetOrCreateCountVecMeter(name string, labels []string) CountVecMeter
	GetOrCreateGaugeMeter(name string) GaugeMeter
	GetOrCreateGaugeVecMeter(name string, labels []string) GaugeVecMeter
	GetOrCreateHistogramMeter(name string, buckets []int64) HistogramMeter
	GetOrCreateHistogramVecMeter(name string, labels []string, buckets []int64) HistogramVecMeter
	GetOrCreateHandler() http.Handler
}

Metrics defines the interface for metrics service implementations