metrics

Documentation

Overview

Package metrics provides a Prometheus-compatible metrics registry with counters, gauges, histograms and runtime snapshots for gofly services.

Package metrics provides a Prometheus-compatible metrics registry with counters, gauges, histograms and runtime snapshots for gofly services.

Package metrics provides a Prometheus-compatible metrics registry with request counters, error counters, latency histograms, and custom metrics.

Index

• Variables
• func RegisterPrometheusCollectors(reg prometheus.Registerer, namespace string, metrics *Registry) error
• type Counter
  • func RegisterCounter(name, help string, labels ...string) *Counter
  • func (c *Counter) Add(delta float64, labelValues ...string)
  • func (c *Counter) Inc(labelValues ...string)
• type CustomMetricSnapshot
• type CustomSeriesSnapshot
• type Gauge
  • func RegisterGauge(name, help string, labels ...string) *Gauge
  • func (g *Gauge) Add(delta float64, labelValues ...string)
  • func (g *Gauge) Dec(labelValues ...string)
  • func (g *Gauge) Delete(labelValues ...string)
  • func (g *Gauge) Inc(labelValues ...string)
  • func (g *Gauge) Set(value float64, labelValues ...string)
• type Histogram
  • func RegisterHistogram(name, help string, buckets []float64, labels ...string) *Histogram
  • func (h *Histogram) Observe(value float64, labelValues ...string)
• type MetricType
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) Counter(name, help string, labels ...string) *Counter
  • func (r *Registry) DecInFlight()
  • func (r *Registry) Gauge(name, help string, labels ...string) *Gauge
  • func (r *Registry) Histogram(name, help string, buckets []float64, labels ...string) *Histogram
  • func (r *Registry) IncInFlight()
  • func (r *Registry) Observe(route string, status int, duration time.Duration)
  • func (r *Registry) Snapshot() Snapshot
  • func (r *Registry) WritePrometheus(w io.Writer) error
• type RouteSnapshot
• type RuntimeSnapshot
• type Snapshot

Variables

var Default = NewRegistry()

var DefaultDurationBuckets = []time.Duration{
	5 * time.Millisecond,
	10 * time.Millisecond,
	25 * time.Millisecond,
	50 * time.Millisecond,
	100 * time.Millisecond,
	250 * time.Millisecond,
	500 * time.Millisecond,
	time.Second,
	2 * time.Second,
	5 * time.Second,
}

var DefaultHistogramBuckets = []float64{0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10}

DefaultHistogramBuckets are the upper bounds used when a histogram is created without explicit buckets.

Functions

func RegisterPrometheusCollectors

func RegisterPrometheusCollectors(reg prometheus.Registerer, namespace string, metrics *Registry) error

RegisterPrometheusCollectors registers gofly metrics as Prometheus collectors.

Types

type Counter

type Counter struct {
	// contains filtered or unexported fields
}

Counter is a monotonically increasing custom metric partitioned by labels.

func RegisterCounter

func RegisterCounter(name, help string, labels ...string) *Counter

Counter, Gauge and Histogram on the package-level Default registry.

func (*Counter) Add

func (c *Counter) Add(delta float64, labelValues ...string)

Add increases the counter for the given label values by delta. Negative deltas are ignored to preserve monotonicity.

func (*Counter) Inc

func (c *Counter) Inc(labelValues ...string)

Inc increments the counter for the given label values by one.

type CustomMetricSnapshot

type CustomMetricSnapshot struct {
	Name    string                 `json:"name"`
	Help    string                 `json:"help,omitempty"`
	Type    MetricType             `json:"type"`
	Labels  []string               `json:"labels,omitempty"`
	Buckets []float64              `json:"buckets,omitempty"`
	Series  []CustomSeriesSnapshot `json:"series,omitempty"`
}

CustomMetricSnapshot is the JSON-safe representation of a custom metric.

type CustomSeriesSnapshot

type CustomSeriesSnapshot struct {
	Labels map[string]string `json:"labels,omitempty"`
	Value  float64           `json:"value,omitempty"`
	Count  uint64            `json:"count,omitempty"`
	Sum    float64           `json:"sum,omitempty"`
	Counts map[string]uint64 `json:"counts,omitempty"`
}

CustomSeriesSnapshot captures one labeled time series for a custom metric.

type Gauge

type Gauge struct {
	// contains filtered or unexported fields
}

Gauge is a custom metric that can move up and down, partitioned by labels.

func RegisterGauge

func RegisterGauge(name, help string, labels ...string) *Gauge

func (*Gauge) Add

func (g *Gauge) Add(delta float64, labelValues ...string)

Add adjusts the gauge value for the given label values by delta.

func (*Gauge) Dec

func (g *Gauge) Dec(labelValues ...string)

Dec decrements the gauge by one.

func (*Gauge) Delete

func (g *Gauge) Delete(labelValues ...string)

Delete removes the gauge series for the given label values so it stops being exported. Deleting a label combination leaves sibling series untouched, and deleting a series that does not exist is a no-op, so callers can safely clear stale labels (for example after a degraded state recovers) without tracking which series were previously set.

func (*Gauge) Inc

func (g *Gauge) Inc(labelValues ...string)

Inc increments the gauge by one.

func (*Gauge) Set

func (g *Gauge) Set(value float64, labelValues ...string)

Set replaces the gauge value for the given label values.

type Histogram

type Histogram struct {
	// contains filtered or unexported fields
}

Histogram records distributions of observed values, partitioned by labels.

func RegisterHistogram

func RegisterHistogram(name, help string, buckets []float64, labels ...string) *Histogram

func (*Histogram) Observe

func (h *Histogram) Observe(value float64, labelValues ...string)

Observe records a single value into the histogram for the given label values.

type MetricType

type MetricType string

MetricType enumerates the supported custom business metric kinds.

const (
	// MetricCounter is a monotonically increasing metric.
	MetricCounter MetricType = "counter"
	// MetricGauge is a metric that can increase and decrease.
	MetricGauge MetricType = "gauge"
	// MetricHistogram samples observations into buckets.
	MetricHistogram MetricType = "histogram"
)

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry collects request metrics with latency histograms.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates a new metrics Registry with default duration buckets.

func (*Registry) Counter

func (r *Registry) Counter(name, help string, labels ...string) *Counter

Counter registers (or returns an existing) custom counter. Calling it again with the same name returns the previously registered metric, so it is safe to call from package initializers.

func (*Registry) DecInFlight

func (r *Registry) DecInFlight()

DecInFlight decrements the in-flight request counter.

func (*Registry) Gauge

func (r *Registry) Gauge(name, help string, labels ...string) *Gauge

Gauge registers (or returns an existing) custom gauge.

func (*Registry) Histogram

func (r *Registry) Histogram(name, help string, buckets []float64, labels ...string) *Histogram

Histogram registers (or returns an existing) custom histogram. When buckets is nil DefaultHistogramBuckets is used. Buckets are sorted ascending.

func (*Registry) IncInFlight

func (r *Registry) IncInFlight()

IncInFlight increments the in-flight request counter.

func (*Registry) Observe

func (r *Registry) Observe(route string, status int, duration time.Duration)

Observe records a request outcome for the given route.

func (*Registry) Snapshot

func (r *Registry) Snapshot() Snapshot

Snapshot returns a point-in-time copy of all registry metrics.

func (*Registry) WritePrometheus

func (r *Registry) WritePrometheus(w io.Writer) error

type RouteSnapshot

type RouteSnapshot struct {
	Requests      int64            `json:"requests"`
	Errors        int64            `json:"errors"`
	TotalDuration time.Duration    `json:"totalDuration"`
	MaxDuration   time.Duration    `json:"maxDuration"`
	AvgDuration   time.Duration    `json:"avgDuration"`
	Buckets       map[string]int64 `json:"buckets"`
}

RouteSnapshot holds request metrics for a single route.

type RuntimeSnapshot

type RuntimeSnapshot struct {
	Goroutines  int    `json:"goroutines"`
	HeapAlloc   uint64 `json:"heapAlloc"`
	HeapSys     uint64 `json:"heapSys"`
	NumGC       uint32 `json:"numGC"`
	LastPauseNS uint64 `json:"lastPauseNs"`
}

RuntimeSnapshot captures Go runtime statistics.

type Snapshot

type Snapshot struct {
	StartedAt time.Time                       `json:"startedAt"`
	Uptime    time.Duration                   `json:"uptime"`
	Requests  int64                           `json:"requests"`
	Errors    int64                           `json:"errors"`
	InFlight  int64                           `json:"inFlight"`
	Statuses  map[int]int64                   `json:"statuses"`
	Routes    map[string]RouteSnapshot        `json:"routes"`
	Customs   map[string]CustomMetricSnapshot `json:"customs,omitempty"`
	Runtime   RuntimeSnapshot                 `json:"runtime"`
}

Snapshot is a point-in-time view of registry metrics.