statter

package module
v2.10.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 22, 2026 License: MIT Imports: 11 Imported by: 14

README

Logo

Go Report Card Build Status Coverage Status Go Reference GitHub release GitHub license

Go stats clients

Overview

Install with:

go get github.com/hamba/statter/v2
Supported stats clients
  • L2met Writes l2met to a Logger interface
  • Statsd Writes statsd to UDP
  • Prometheus Exposes stats via HTTP
  • VictoriaMetrics Exposes stats via HTTP

Note: This project has renamed the default branch from master to main. You will need to update your local environment.

Usage

reporter := statsd.New(statsdAddr, "")
stats := statter.New(reporter, 10*time.Second).With("my-prefix")

stats.Counter("my-counter", tags.Str("tag", "value")).Inc(1)

Scopes

A Scope is a sub-statter identified by an id, which tracks the metrics created through it.

Requesting a scope with an existing id but different tags removes the previous scope and every metric created through it. This keeps a metric unique for a set of tags, such as a gauge carrying a revision that changes over time:

stats.Scope("build-info", tags.Str("revision", rev)).Gauge("info").Set(1)

The tracked metrics can also be removed together as a batch:

scope := stats.Scope("tenant:"+id, tags.Str("tenant", id))
scope.Counter("requests").Inc(1)
scope.Timing("latency").Observe(d)

scope.Delete() // Both metrics are removed.

Use HasScope to determine if a scope currently exists.

Note: Metrics are only removed from the backend if the reporter supports removal, which the Prometheus and VictoriaMetrics reporters do. Otherwise deletion only stops local aggregation.

Documentation

Overview

Package statter collects and reports statistics via a pluggable Reporter.

Stats are aggregated in memory and flushed to the reporter on a fixed interval. Counters accumulate deltas between flushes; gauges hold their last-set value. Histograms and timings are either delegated directly to the reporter (when it implements HistogramReporter / TimingReporter) or aggregated locally and emitted as a set of derived gauges and a counter.

Metrics are identified by a name and an optional set of key/value Tag pairs. The Statter.With method creates a scoped sub-statter that prepends a prefix and merges tags into every metric it records. Sub-statters with identical resolved prefix and tags are deduplicated and share the same instance.

The Statter.Scope method returns a Scope, a sub-statter identified by a caller supplied id. A Scope tracks the metrics created through it, so they can be removed together with Scope.Delete. Requesting a Scope with an existing id but different tags deletes the previous Scope and its metrics, which keeps metrics unique for a set of tags, such as a gauge carrying a revision that changes over time.

The Reporter interface is the only contract that backend adapters must satisfy. Richer adapters may additionally implement HistogramReporter, TimingReporter, and the corresponding Removable* interfaces. Metrics are only removed from the backend if the reporter implements the relevant Removable* interface, otherwise deletion only stops local aggregation.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var DiscardReporter = discardReporter{}

DiscardReporter is a reporter that discards all stats.

Functions

func WithContext added in v2.9.0 

func WithContext(ctx context.Context, tags ...Tag) context.Context

WithContext returns a new context with the given tags attached. If tags are already present in ctx, the new tags are merged with them; a new tag whose key already exists overrides the stored value.

Types

type Counter 

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

Counter implements a counter that monotonically accumulates a value between flushes. The accumulated delta is reported and reset to zero on each flush.

func (*Counter) Delete added in v2.6.0 

func (c *Counter) Delete()

Delete removes the counter.

func (*Counter) Inc 

func (c *Counter) Inc(v int64)

Inc increments the counter by v.

Example 
package main

import (
	"time"

	"github.com/hamba/statter/v2"
	"github.com/hamba/statter/v2/tags"
)

func main() {
	stat := statter.New(statter.DiscardReporter, time.Second)

	stat.Counter("my_counter", tags.Str("tag", "value")).Inc(1)
}

type Gauge 

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

Gauge implements a gauge that holds its last-set value and reports it on each flush.

func (*Gauge) Add added in v2.7.0 

func (g *Gauge) Add(v float64)

Add increases the gauge's value by v.

func (*Gauge) Dec added in v2.7.0 

func (g *Gauge) Dec()

Dec decrements the gauge by 1.

func (*Gauge) Delete added in v2.6.0 

func (g *Gauge) Delete()

Delete removes the gauge.

func (*Gauge) Inc added in v2.7.0 

func (g *Gauge) Inc()

Inc increments the gauge by 1.

func (*Gauge) Set 

func (g *Gauge) Set(v float64)

Set sets the gauge value.

Example 
package main

import (
	"time"

	"github.com/hamba/statter/v2"
	"github.com/hamba/statter/v2/tags"
)

func main() {
	stat := statter.New(statter.DiscardReporter, time.Second)

	stat.Gauge("my_gauge", tags.Int("int", 1)).Set(1.23)
}

func (*Gauge) Sub added in v2.7.0 

func (g *Gauge) Sub(v float64)

Sub subtracts the argument from the gauge's value.

type Histogram 

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

Histogram implements a histogram.

When the reporter implements HistogramReporter, observations are delegated to it directly. Otherwise observations are aggregated locally and reported each interval as a set of gauges (_sum, _mean, _stddev, _min, _max, and each configured percentile) plus a _count counter.

func (*Histogram) Delete added in v2.6.0 

func (h *Histogram) Delete()

Delete removes the histogram.

func (*Histogram) Observe 

func (h *Histogram) Observe(v float64)

Observe observes a histogram value.

Example 
package main

import (
	"time"

	"github.com/hamba/statter/v2"
	"github.com/hamba/statter/v2/tags"
)

func main() {
	stat := statter.New(statter.DiscardReporter, time.Second)

	stat.Histogram("my_histo", tags.Str("label", "blah")).Observe(2.34)
}

type HistogramReporter 

type HistogramReporter interface {
	Histogram(name string, tags [][2]string) func(v float64)
}

HistogramReporter represents a stats reporter that handles histograms.

type Option 

type Option func(*config)

Option represents a statter option function.

func WithPercentileSamples 

func WithPercentileSamples(n int) Option

WithPercentileSamples sets the number of samples taken to calculate percentiles.

func WithPercentiles 

func WithPercentiles(p []float64) Option

WithPercentiles sets the percentiles to calculate and report for aggregated histograms and timings.

func WithPrefix added in v2.3.3 

func WithPrefix(prefix string) Option

WithPrefix sets the initial prefix on a statter.

func WithSeparator 

func WithSeparator(sep string) Option

WithSeparator sets the key separator on a statter.

func WithTags added in v2.3.3 

func WithTags(tags ...Tag) Option

WithTags sets the initial tags on a statter.

type RemovableHistogramReporter added in v2.6.0 

type RemovableHistogramReporter interface {
	RemoveHistogram(name string, tags [][2]string)
}

RemovableHistogramReporter represents a stats reporter that handles histogram removal.

type RemovableReporter added in v2.6.0 

type RemovableReporter interface {
	RemoveCounter(name string, tags [][2]string)
	RemoveGauge(name string, tags [][2]string)
}

RemovableReporter represents a stats reporter that handles removal.

type RemovableTimingReporter added in v2.6.0 

type RemovableTimingReporter interface {
	RemoveTiming(name string, tags [][2]string)
}

RemovableTimingReporter represents a stats reporter that handles timing removal.

type Reporter 

type Reporter interface {
	Counter(name string, v int64, tags [][2]string)
	Gauge(name string, v float64, tags [][2]string)
}

Reporter represents a stats reporter.

The statter passes tags sorted by key.

type Scope added in v2.10.0 

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

Scope is a sub-statter identified by a unique id.

Metrics created through a Scope are tracked by it, and are removed together when the Scope is deleted or replaced. See Statter.Scope.

func (*Scope) Counter added in v2.10.0 

func (sc *Scope) Counter(name string, tags ...Tag) *Counter

Counter returns a counter for the given name and tags, tracking it against the scope.

func (*Scope) Delete added in v2.10.0 

func (sc *Scope) Delete()

Delete removes the scope and all metrics created through it.

Delete is idempotent. Metrics requested from a deleted scope are returned to the caller but are not tracked, and are removed immediately.

Example 
package main

import (
	"time"

	"github.com/hamba/statter/v2"
	"github.com/hamba/statter/v2/tags"
)

func main() {
	stat := statter.New(statter.DiscardReporter, time.Second)

	scope := stat.Scope("tenant:1", tags.Str("tenant", "1"))
	scope.Counter("requests").Inc(1)
	scope.Timing("latency").Observe(time.Second)

	// Both the counter and the timing are removed.
	scope.Delete()
}

func (*Scope) FullName added in v2.10.0 

func (sc *Scope) FullName(name string) string

FullName returns the full name with prefix for the given name.

func (*Scope) Gauge added in v2.10.0 

func (sc *Scope) Gauge(name string, tags ...Tag) *Gauge

Gauge returns a gauge for the given name and tags, tracking it against the scope.

func (*Scope) Histogram added in v2.10.0 

func (sc *Scope) Histogram(name string, tags ...Tag) *Histogram

Histogram returns a histogram for the given name and tags, tracking it against the scope.

func (*Scope) Timing added in v2.10.0 

func (sc *Scope) Timing(name string, tags ...Tag) *Timing

Timing returns a timing for the given name and tags, tracking it against the scope.

type Statter 

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

Statter collects and reports stats.

func New 

func New(r Reporter, interval time.Duration, opts ...Option) *Statter

New returns a Statter that aggregates stats and flushes them to r on every interval tick. Options may be used to set an initial prefix, tags, key separator, and percentile configuration.

func (*Statter) Close 

func (s *Statter) Close() error

Close stops the reporting loop, flushes any pending stats to the reporter, and closes the reporter if it implements io.Closer. Close must be called on the root statter; calling it on a sub-statter returns an error.

func (*Statter) Counter 

func (s *Statter) Counter(name string, tags ...Tag) *Counter

Counter returns a counter for the given name and tags. The counter is created on the first call and the same instance is returned for subsequent calls with identical name and tags.

func (*Statter) FromContext added in v2.9.0 

func (s *Statter) FromContext(ctx context.Context) *Statter

FromContext returns a sub-statter whose tags include those stored in ctx by WithContext. If no tags are found in ctx, s is returned unchanged.

func (*Statter) FullName added in v2.2.0 

func (s *Statter) FullName(name string) string

FullName returns the full name with prefix for the given name.

func (*Statter) Gauge 

func (s *Statter) Gauge(name string, tags ...Tag) *Gauge

Gauge returns a gauge for the given name and tags. The gauge is created on the first call and the same instance is returned for subsequent calls with identical name and tags.

func (*Statter) HasCounter added in v2.6.0 

func (s *Statter) HasCounter(name string, tags ...Tag) bool

HasCounter determines if the counter exists.

func (*Statter) HasGauge added in v2.6.0 

func (s *Statter) HasGauge(name string, tags ...Tag) bool

HasGauge determines if the gauge exists.

func (*Statter) HasHistogram added in v2.6.0 

func (s *Statter) HasHistogram(name string, tags ...Tag) bool

HasHistogram determines if the histogram exists.

func (*Statter) HasScope added in v2.10.0 

func (s *Statter) HasScope(id string) bool

HasScope determines if a scope with the given id exists.

func (*Statter) HasTiming added in v2.6.0 

func (s *Statter) HasTiming(name string, tags ...Tag) bool

HasTiming determines if the timing exists.

func (*Statter) Histogram 

func (s *Statter) Histogram(name string, tags ...Tag) *Histogram

Histogram returns a histogram for the given name and tags. The histogram is created on the first call and the same instance is returned for subsequent calls with identical name and tags.

When the reporter implements HistogramReporter, observations are delegated to it directly. Otherwise observations are aggregated locally and reported each interval as a set of gauges (_sum, _mean, _stddev, _min, _max, and each configured percentile) plus a _count counter.

func (*Statter) Reporter added in v2.1.1 

func (s *Statter) Reporter() Reporter

Reporter returns the underlying stats reporter.

The reporter is exposed for advanced use cases such as pre-registering metrics with helpers like RegisterCounter, RegisterGauge, and RegisterHistogram. Observing or mutating stats through the reporter directly bypasses aggregation and should otherwise be avoided.

func (*Statter) Scope added in v2.10.0 

func (s *Statter) Scope(id string, tags ...Tag) *Scope

Scope returns a Scope with the given id and tags, derived from s. Metrics created through the Scope are tracked by it, and can be removed as a batch with Scope.Delete.

If a Scope with the same id already exists, derived from the same statter and with identical tags, it is returned. If it exists with different tags, or was derived from a different statter, the existing Scope and every metric created through it are deleted and a new Scope is returned. This makes a Scope useful for metrics that must be unique for a set of tags, such as a gauge carrying a revision that changes over time.

Scope ids are global to the statter tree and are not namespaced by prefix.

A metric created through a Scope shares its registration with an identical metric created directly on a statter. Deleting the Scope therefore also removes the metric from the direct caller.

Example 
package main

import (
	"time"

	"github.com/hamba/statter/v2"
	"github.com/hamba/statter/v2/tags"
)

func main() {
	stat := statter.New(statter.DiscardReporter, time.Second)

	// The gauge is unique for the given revision. When the revision changes,
	// the gauge reported for the previous revision is removed.
	stat.Scope("build-info", tags.Str("revision", "abc123")).Gauge("info").Set(1)
}

func (*Statter) Timing 

func (s *Statter) Timing(name string, tags ...Tag) *Timing

Timing returns a timing for the given name and tags. The timing is created on the first call and the same instance is returned for subsequent calls with identical name and tags.

When the reporter implements TimingReporter, observations are delegated to it directly. Otherwise observations are aggregated locally in milliseconds and reported each interval as a set of gauges (_sum_ms, _mean_ms, _stddev_ms, _min_ms, _max_ms, and each configured percentile) plus a _count counter.

func (*Statter) With 

func (s *Statter) With(prefix string, tags ...Tag) *Statter

With returns a sub-statter whose metrics are prefixed with prefix and carry the additional tags. The prefix is joined to the parent prefix with the configured separator. Tags are merged with the parent tags; a call-site tag whose key already exists in the parent overrides the parent value.

Sub-statters with the same resolved prefix and tags are deduplicated: the same instance is returned for repeated calls with identical arguments.

type Tag 

type Tag = [2]string

Tag is a stat tag.

type Timing 

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

Timing implements a timing.

When the reporter implements TimingReporter, observations are delegated to it directly. Otherwise observations are aggregated locally in milliseconds and reported each interval as a set of gauges (_sum_ms, _mean_ms, _stddev_ms, _min_ms, _max_ms, and each configured percentile) plus a _count counter.

func (*Timing) Delete added in v2.6.0 

func (t *Timing) Delete()

Delete removes the timing.

func (*Timing) Observe 

func (t *Timing) Observe(d time.Duration)

Observe observes a timing duration.

If the reporter does not handle timings, the duration will be aggregated in milliseconds.

type TimingReporter 

type TimingReporter interface {
	Timing(name string, tags [][2]string) func(v time.Duration)
}

TimingReporter represents a stats reporter that handles timings.

Source Files

View all Source files

Directories

Path Synopsis
internal
bytes
Package bytes implements performant bytes implementations.
 Package bytes implements performant bytes implementations.
stats
Package stats implements performant statistics implementations.
 Package stats implements performant statistics implementations.
reporter
l2met
Package l2met implements a l2met stats client.
 Package l2met implements a l2met stats client.
prometheus
Package prometheus implements a prometheus stats client.
 Package prometheus implements a prometheus stats client.
statsd
Package statsd implements a statsd client.
 Package statsd implements a statsd client.
victoriametrics
Package victoriametrics implements a VictoriaMetrics stats reporter.
 Package victoriametrics implements a VictoriaMetrics stats reporter.
Package runtime implements runtime stats collection convenience functions.
 Package runtime implements runtime stats collection convenience functions.
Package tags implements statter tags convenience functions.
 Package tags implements statter tags convenience functions.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.