uber-go/tally

The Prometheus reporter supports two types of timers via the TimerType enum:

• SummaryTimerType: Reports into a Prometheus summary.
• HistogramTimerType: Reports into a Prometheus histogram (this is the default).

You can set the global default using Options.DefaultTimerType or specify a type per-metric using RegisterTimerOptions.

type TimerType int

const (
	SummaryTimerType   TimerType = iota
	HistogramTimerType
)

Tally uses three main abstractions to manage metrics:

1. Scope: The primary interface for developers. It keeps track of metrics (Counters, Gauges, Timers, and Histograms) and manages their common metadata (tags).
2. Metrics: The actual data points you record. Tally buffers counters, gauges, and histograms at a specified interval to reduce emission velocity, but does not buffer timer values so they can be sampled accurately.
3. Reporter: The backend implementation that accepts aggregated values from the Scope and forwards them to your metrics ingestion pipeline (e.g., Prometheus, StatsD).

You can create hierarchical scopes using Tagged (to add metadata) or SubScope (to add name prefixes).

To run the provided M3 reporter example, navigate to the example directory and use the Go CLI to execute the Go files in the current directory.

go run ./*.go

The StatsD reporter allows you to emit metrics to a StatsD server. It can be used with either a basic or a buffered StatsD client. When metrics are emitted, they follow the standard StatsD format (e.g., stats.name:value|type).

To see a complete end-to-end implementation, refer to the examples/statsd_main.go file in the repository.

stats.my-service.test-histogram.100ms-200ms:2|c
stats.my-service.test-counter:1|c
stats.my-service.test-gauge:813|g

Install the tally package using go get:

go get -u github.com/uber-go/tally

Use NewMultiCachedReporter to wrap multiple tally.CachedStatsReporter implementations into a single reporter. This is used when you need the buffering/caching capabilities of CachedStatsReporter across multiple backends.

reporter := NewMultiCachedReporter(m3Reporter, promReporter, ...)

To run the provided Prometheus reporter example, navigate to the prometheus/example directory and execute the Go files using the go run command.

go run ./*.go

Use NewMultiReporter to wrap multiple tally.StatsReporter implementations into a single reporter. This allows you to emit metrics to several different backends simultaneously using a single reporter instance.

reporter := NewMultiReporter(statsdReporter, ...)

The StatsD reporter is configured using the Options struct. Currently, it supports setting the emission sample rate.

Options

// Options is a set of options for the tally reporter.
type Options struct {
	// SampleRate is the metrics emission sample rate. If you
	// do not set this value it will be set to 1.
	SampleRate float32
}

When configuring SanitizeOptions, you use the ValidCharacters struct to specify which runes are allowed. A character is considered valid if it falls within any of the provided Ranges or matches any rune in the Characters slice.

SanitizeRange is an inclusive range defined by two runes: [start, end].

Tally provides four primary metric types:

1. Counter: Tracks a cumulative total that only increases (e.g., total_requests). Use Inc(v).
2. Gauge: Tracks an instantaneous measurement that can fluctuate (e.g., current_memory_usage). Use Update(v).
3. Timer: Measures the duration of events. Unlike Histograms, Timers in Tally are often buffered and flushed as individual observations to a reporter. Use Record(d) or Start().
4. Histogram: Categorizes observations into buckets to show distribution (e.g., request_latency_buckets). Use RecordValue(v) or RecordDuration(d).