metrics

Documentation

Overview

Package metrics implements Service Weaver metrics.

Example

package main

import (
	"github.com/XCWeaver/xcweaver/runtime/metrics"
	"github.com/XCWeaver/xcweaver/runtime/protos"
)

var (
	// Unlabeled counter.
	catCounter = metrics.Register(
		protos.MetricType_COUNTER,
		"example_cats",
		"Number of cats.",
		nil,
	)

	// Labeled counters.
	dogCounters = metrics.RegisterMap[dogLabels](
		protos.MetricType_COUNTER,
		"example_dogs",
		"Number of dogs, by breed.",
		nil,
	)
	corgiCounter     = dogCounters.Get(dogLabels{"corgi"})
	poodleCounter    = dogCounters.Get(dogLabels{"poodle"})
	dachshundCounter = dogCounters.Get(dogLabels{"dachshund"})
	dalmatianCounter = dogCounters.Get(dogLabels{"dalmatians"})
)

type dogLabels struct {
	Breed string
}

func main() {
	catCounter.Add(9.0)
	corgiCounter.Add(2.0)
	poodleCounter.Add(1.0)
	dachshundCounter.Add(10.0)
	dalmatianCounter.Add(101.0)
}

Index

• type Exporter
  • func (e *Exporter) Export() *protos.MetricUpdate
• type Importer
  • func (i *Importer) Import(update *protos.MetricUpdate) ([]*MetricSnapshot, error)
• type Metric
  • func Register(typ protos.MetricType, name string, help string, bounds []float64) *Metric
  • func (m *Metric) Add(delta float64)
  • func (m *Metric) Inc()
  • func (m *Metric) MetricDef() *protos.MetricDef
  • func (m *Metric) MetricValue() *protos.MetricValue
  • func (m *Metric) Name() string
  • func (m *Metric) Put(val float64)
  • func (m *Metric) Set(val float64)
  • func (m *Metric) Snapshot() *MetricSnapshot
  • func (m *Metric) Sub(delta float64)
• type MetricMap
  • func RegisterMap[L comparable](typ protos.MetricType, name string, help string, bounds []float64) *MetricMap[L]
  • func (mm *MetricMap[L]) Get(labels L) *Metric
  • func (mm *MetricMap[L]) Name() string
• type MetricSnapshot
  • func Snapshot() []*MetricSnapshot
  • func UnProto(m *protos.MetricSnapshot) *MetricSnapshot
  • func (m *MetricSnapshot) Clone() *MetricSnapshot
  • func (m *MetricSnapshot) MetricDef() *protos.MetricDef
  • func (m *MetricSnapshot) MetricValue() *protos.MetricValue
  • func (m *MetricSnapshot) ToProto() *protos.MetricSnapshot

Examples

• Package

Types

type Exporter

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

An Exporter produces MetricUpdates summarizing the change in metrics over time.

func (*Exporter) Export

func (e *Exporter) Export() *protos.MetricUpdate

Export produces a MetricUpdate that summarizes the changes to all metrics since the last call to MetricUpdate.

type Importer

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

An Importer maintains a snapshot of all metric values, updating over time using the MetricUpdates generated by an Exporter.

func (*Importer) Import

func (i *Importer) Import(update *protos.MetricUpdate) ([]*MetricSnapshot, error)

Import updates the Importer's snapshot with the latest metric changes.

type Metric

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

Metric is a thread-safe readable and writeable metric. It is the underlying implementation of the user-facing metrics like Counter and Gauge.

Every metric has a unique name assigned by the user. For example, the user may create a histogram called "http_request_duration". Every metric also has a fixed, possibly empty, set of labels. For example, the user may assign an "endpoint" label to their "http_request_duration" to differentiate the latency of different HTTP endpoints. A metric name and set of label values uniquely identify a metric. For example, the following two metrics are different:

http_request_duration{endpoint="/"}
http_request_duration{endpoint="/foo"}

func Register

func Register(typ protos.MetricType, name string, help string, bounds []float64) *Metric

Register registers and returns a new metric. Panics if a metric with the same name has already been registered.

func (*Metric) Add

func (m *Metric) Add(delta float64)

Add adds the provided delta to the metric's value.

func (*Metric) Inc

func (m *Metric) Inc()

Inc adds one to the metric value.

func (*Metric) MetricDef

func (m *Metric) MetricDef() *protos.MetricDef

MetricDef returns a MetricDef derived from the metric. You must call Init at least once before calling Snapshot.

func (*Metric) MetricValue

func (m *Metric) MetricValue() *protos.MetricValue

MetricValue returns a MetricValue derived from the metric.

func (*Metric) Name

func (m *Metric) Name() string

Name returns the name of the metric.

func (*Metric) Put

func (m *Metric) Put(val float64)

Put adds the provided value to the metric's histogram.

func (*Metric) Set

func (m *Metric) Set(val float64)

Set sets the metric's value.

func (*Metric) Snapshot

func (m *Metric) Snapshot() *MetricSnapshot

Snapshot returns a snapshot of the metric. You must call Init at least once before calling Snapshot.

func (*Metric) Sub

func (m *Metric) Sub(delta float64)

Sub subtracts the provided delta from the metric's value.

type MetricMap

type MetricMap[L comparable] struct {
	// contains filtered or unexported fields
}

MetricMap is a collection of metrics with the same name and label schema but with different label values. See public metric documentation for an explanation of labels.

TODO(mwhittaker): Understand the behavior of prometheus and Google Cloud Metrics when we add or remove metric labels over time.

func RegisterMap

func RegisterMap[L comparable](typ protos.MetricType, name string, help string, bounds []float64) *MetricMap[L]

func (*MetricMap[L]) Get

func (mm *MetricMap[L]) Get(labels L) *Metric

Get returns the metric with the provided labels, constructing it if it doesn't already exist. Multiple calls to Get with the same labels will return the same metric.

func (*MetricMap[L]) Name

func (mm *MetricMap[L]) Name() string

Name returns the name of the metricMap.

type MetricSnapshot

type MetricSnapshot struct {
	Id     uint64
	Type   protos.MetricType
	Name   string
	Labels map[string]string
	Help   string

	Value  float64
	Bounds []float64
	Counts []uint64
}

A MetricSnapshot is a snapshot of a metric.

func Snapshot

func Snapshot() []*MetricSnapshot

Snapshot returns a snapshot of all currently registered metrics. The snapshot is not guaranteed to be atomic.

func UnProto

func UnProto(m *protos.MetricSnapshot) *MetricSnapshot

UnProto converts a protos.MetricSnapshot into a metrics.MetricSnapshot.

func (*MetricSnapshot) Clone

func (m *MetricSnapshot) Clone() *MetricSnapshot

Clone returns a deep copy of m.

func (*MetricSnapshot) MetricDef

func (m *MetricSnapshot) MetricDef() *protos.MetricDef

MetricDef returns a MetricDef derived from the metric.

func (*MetricSnapshot) MetricValue

func (m *MetricSnapshot) MetricValue() *protos.MetricValue

MetricValue returns a MetricValue derived from the metric.

func (*MetricSnapshot) ToProto

func (m *MetricSnapshot) ToProto() *protos.MetricSnapshot

ToProto converts a MetricSnapshot to its proto equivalent.