metrics

Documentation

Overview

Package metrics provides a small OpenMetrics registry for go-iroh metrics.

The Go API is not stable before v1 and may change in any v0 release.

Index

• func Handler(r *Registry) http.Handler
• type Family
  • func NewFamily(name string, typ MetricType, labelNames ...string) *Family
  • func (f *Family) StructuredSnapshot() StructuredSnapshot
  • func (f *Family) With(labelValues ...string) (*FamilyMetric, error)
• type FamilyMetric
  • func (m *FamilyMetric) Add(delta uint64)
  • func (m *FamilyMetric) Set(value float64)
• type HistogramBucket
• type Label
• type MetricType
• type MetricValue
  • func Counter(v uint64) MetricValue
  • func Gauge(v float64) MetricValue
  • func Histogram(sum float64, count uint64, buckets []HistogramBucket) MetricValue
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) Register(prefix string, source any) error
  • func (r *Registry) WriteOpenMetrics(w io.Writer) error
• type Server
  • func NewServer(addr string, r *Registry) *Server
  • func (s *Server) ListenAndServe() error
  • func (s *Server) Serve(l net.Listener) error
  • func (s *Server) Shutdown(ctx context.Context) error
• type Snapshot
  • func (s Snapshot) String() string
• type Source
• type StructuredSnapshot
• type StructuredSource

Examples

• NewFamily

Functions

func Handler

func Handler(r *Registry) http.Handler

Handler returns an HTTP handler serving r at /metrics.

Types

type Family

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

Family is a metric vector keyed by a fixed label set.

func NewFamily

func NewFamily(name string, typ MetricType, labelNames ...string) *Family

NewFamily returns a metric family with labelNames in output order.

Example

f := NewFamily("connections", CounterMetric, "family")
quic, _ := f.With("quic")
quic.Add(2)

r := NewRegistry()
_ = r.Register("endpoint", f)
_ = r.WriteOpenMetrics(io.Discard)

func (*Family) StructuredSnapshot

func (f *Family) StructuredSnapshot() StructuredSnapshot

StructuredSnapshot returns all children in f.

func (*Family) With

func (f *Family) With(labelValues ...string) (*FamilyMetric, error)

With returns the child metric for labelValues.

type FamilyMetric

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

FamilyMetric is one labeled metric in a Family.

func (*FamilyMetric) Add

func (m *FamilyMetric) Add(delta uint64)

Add adds delta to m. Use it for counter families.

func (*FamilyMetric) Set

func (m *FamilyMetric) Set(value float64)

Set sets m to value. Use it for gauge families.

type HistogramBucket

type HistogramBucket struct {
	// Le is the inclusive upper bound. Use math.Inf(1) for +Inf.
	Le float64
	// Count is the cumulative count for this bucket.
	Count uint64
}

HistogramBucket is one cumulative histogram bucket.

type Label

type Label struct {
	Name  string
	Value string
}

Label is one OpenMetrics label on a sample.

type MetricType

type MetricType string

MetricType is the OpenMetrics type of a metric value.

const (
	// CounterMetric is a monotonically increasing counter.
	CounterMetric MetricType = "counter"
	// GaugeMetric is a point-in-time value that may increase or decrease.
	GaugeMetric MetricType = "gauge"
	// HistogramMetric is a cumulative histogram.
	HistogramMetric MetricType = "histogram"
)

type MetricValue

type MetricValue struct {
	Name    string
	Type    MetricType
	Labels  []Label
	Counter uint64
	Gauge   float64
	Sum     float64
	Count   uint64
	Buckets []HistogramBucket
}

MetricValue is one metric sample in a StructuredSnapshot.

func Counter

func Counter(v uint64) MetricValue

Counter returns a counter metric value.

func Gauge

func Gauge(v float64) MetricValue

Gauge returns a gauge metric value.

func Histogram

func Histogram(sum float64, count uint64, buckets []HistogramBucket) MetricValue

Histogram returns a histogram metric value. Buckets are copied and sorted by upper bound before OpenMetrics output.

type Registry

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

Registry collects named metric sources.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns an empty registry.

func (*Registry) Register

func (r *Registry) Register(prefix string, source any) error

Register adds source under prefix. Prefix must be non-empty and unique.

func (*Registry) WriteOpenMetrics

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

WriteOpenMetrics writes all registered counter snapshots in OpenMetrics text format.

type Server

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

Server is a small HTTP server for OpenMetrics scraping.

func NewServer

func NewServer(addr string, r *Registry) *Server

NewServer returns a metrics HTTP server bound to addr.

func (*Server) ListenAndServe

func (s *Server) ListenAndServe() error

ListenAndServe serves metrics until the server is shut down.

func (*Server) Serve

func (s *Server) Serve(l net.Listener) error

Serve serves metrics on l until the server is shut down.

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the metrics server.

type Snapshot

type Snapshot map[string]uint64

Snapshot is a point-in-time set of unsigned counter values.

func (Snapshot) String

func (s Snapshot) String() string

String implements expvar.Var, returning the snapshot as JSON.

type Source

type Source interface {
	Snapshot() Snapshot
}

Source returns a point-in-time metrics snapshot.

type StructuredSnapshot

type StructuredSnapshot map[string]MetricValue

StructuredSnapshot is a point-in-time set of typed metric values.

type StructuredSource

type StructuredSource interface {
	StructuredSnapshot() StructuredSnapshot
}

StructuredSource returns a point-in-time typed metrics snapshot.