README
¶
Go stats clients
Overview
Install with:
go get github.com/hamba/statter/v2
Supported stats clients
- L2met Writes l2met to a
Loggerinterface - 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)
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 Reporter interface is the only contract that backend adapters must satisfy. Richer adapters may additionally implement HistogramReporter, TimingReporter, and the corresponding Removable* interfaces.
Index ¶
- Variables
- func WithContext(ctx context.Context, tags ...Tag) context.Context
- type Counter
- type Gauge
- type Histogram
- type HistogramReporter
- type Option
- type RemovableHistogramReporter
- type RemovableReporter
- type RemovableTimingReporter
- type Reporter
- type Statter
- func (s *Statter) Close() error
- func (s *Statter) Counter(name string, tags ...Tag) *Counter
- func (s *Statter) FromContext(ctx context.Context) *Statter
- func (s *Statter) FullName(name string) string
- func (s *Statter) Gauge(name string, tags ...Tag) *Gauge
- func (s *Statter) HasCounter(name string, tags ...Tag) bool
- func (s *Statter) HasGauge(name string, tags ...Tag) bool
- func (s *Statter) HasHistogram(name string, tags ...Tag) bool
- func (s *Statter) HasTiming(name string, tags ...Tag) bool
- func (s *Statter) Histogram(name string, tags ...Tag) *Histogram
- func (s *Statter) Reporter() Reporter
- func (s *Statter) Timing(name string, tags ...Tag) *Timing
- func (s *Statter) With(prefix string, tags ...Tag) *Statter
- type Tag
- type Timing
- type TimingReporter
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var DiscardReporter = discardReporter{}
DiscardReporter is a reporter that discards all stats.
Functions ¶
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) Inc ¶
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)
}
Output:
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.
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 ¶
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)
}
Output:
type HistogramReporter ¶
HistogramReporter represents a stats reporter that handles histograms.
type Option ¶
type Option func(*config)
Option represents a statter option function.
func WithPercentileSamples ¶
WithPercentileSamples sets the number of samples taken to calculate percentiles.
func WithPercentiles ¶
WithPercentiles sets the percentiles to calculate and report for aggregated histograms and timings.
func WithPrefix ¶ added in v2.3.3
WithPrefix sets the initial prefix on a statter.
func WithSeparator ¶
WithSeparator sets the key separator on a statter.
type RemovableHistogramReporter ¶ added in v2.6.0
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
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.
type Statter ¶
type Statter struct {
// contains filtered or unexported fields
}
Statter collects and reports stats.
func New ¶
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 ¶
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 ¶
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
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
FullName returns the full name with prefix for the given name.
func (*Statter) 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
HasCounter determines if the counter exists.
func (*Statter) HasHistogram ¶ added in v2.6.0
HasHistogram determines if the histogram exists.
func (*Statter) 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
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) 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 ¶
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 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.
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. |