metrics

package
v1.10.53 Latest Latest
Warning

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

 Go to latest Published: Jan 23, 2024 License: GPL-3.0, GPL-3.0, BSD-2-Clause-Views Imports: 25 Imported by: 3

README

go-metrics

travis build status

Go port of Coda Hale's Metrics library: https://github.com/dropwizard/metrics.

Documentation: https://godoc.org/github.com/rcrowley/go-metrics.

Usage

Create and update metrics:

c := metrics.NewCounter()
metrics.Register("foo", c)
c.Inc(47)

g := metrics.NewGauge()
metrics.Register("bar", g)
g.Update(47)

r := NewRegistry()
g := metrics.NewRegisteredFunctionalGauge("cache-evictions", r, func() int64 { return cache.getEvictionsCount() })

s := metrics.NewExpDecaySample(1028, 0.015) // or metrics.NewUniformSample(1028)
h := metrics.NewHistogram(s)
metrics.Register("baz", h)
h.Update(47)

m := metrics.NewMeter()
metrics.Register("quux", m)
m.Mark(47)

t := metrics.NewTimer()
metrics.Register("bang", t)
t.Time(func() {})
t.Update(47)

Register() is not threadsafe. For threadsafe metric registration use GetOrRegister:

t := metrics.GetOrRegisterTimer("account.create.latency", nil)
t.Time(func() {})
t.Update(47)

NOTE: Be sure to unregister short-lived meters and timers otherwise they will leak memory:

// Will call Stop() on the Meter to allow for garbage collection
metrics.Unregister("quux")
// Or similarly for a Timer that embeds a Meter
metrics.Unregister("bang")

Periodically log every metric in human-readable form to standard error:

go metrics.Log(metrics.DefaultRegistry, 5 * time.Second, log.New(os.Stderr, "metrics: ", log.Lmicroseconds))

Periodically log every metric in slightly-more-parseable form to syslog:

w, _ := syslog.Dial("unixgram", "/dev/log", syslog.LOG_INFO, "metrics")
go metrics.Syslog(metrics.DefaultRegistry, 60e9, w)

Periodically emit every metric to Graphite using the Graphite client:


import "github.com/cyberdelia/go-metrics-graphite"

addr, _ := net.ResolveTCPAddr("tcp", "127.0.0.1:2003")
go graphite.Graphite(metrics.DefaultRegistry, 10e9, "metrics", addr)

Periodically emit every metric into InfluxDB:

NOTE: this has been pulled out of the library due to constant fluctuations in the InfluxDB API. In fact, all client libraries are on their way out. see issues #121 and #124 for progress and details.

import "github.com/vrischmann/go-metrics-influxdb"

go influxdb.InfluxDB(metrics.DefaultRegistry,
  10e9, 
  "127.0.0.1:8086", 
  "database-name", 
  "username", 
  "password"
)

Periodically upload every metric to Librato using the Librato client:

Note: the client included with this repository under the librato package has been deprecated and moved to the repository linked above.

import "github.com/mihasya/go-metrics-librato"

go librato.Librato(metrics.DefaultRegistry,
    10e9,                  // interval
    "example@example.com", // account owner email address
    "token",               // Librato API token
    "hostname",            // source
    []float64{0.95},       // percentiles to send
    time.Millisecond,      // time unit
)

Periodically emit every metric to StatHat:

import "github.com/rcrowley/go-metrics/stathat"

go stathat.Stathat(metrics.DefaultRegistry, 10e9, "example@example.com")

Maintain all metrics along with expvars at /debug/metrics:

This uses the same mechanism as the official expvar but exposed under /debug/metrics, which shows a json representation of all your usual expvars as well as all your go-metrics.

import "github.com/rcrowley/go-metrics/exp"

exp.Exp(metrics.DefaultRegistry)

Installation

go get github.com/rcrowley/go-metrics

StatHat support additionally requires their Go client:

go get github.com/stathat/go

Publishing Metrics

Clients are available for the following destinations:

Documentation

Overview

Go port of Coda Hale's Metrics library

<https://github.com/rcrowley/go-metrics>

Coda Hale's original work: <https://github.com/codahale/metrics>

Example 
c := NewCounter()
Register("money", c)
c.Inc(17)

// Threadsafe registration
t := GetOrRegisterTimer("db.get.latency", nil)
t.Time(func() { time.Sleep(10 * time.Millisecond) })
t.Update(1)

fmt.Println(c.Snapshot().Count())
fmt.Println(t.Snapshot().Min())

Output:

17
1

Index

Examples

Constants

View Source 
const InitialResettingTimerSliceCap = 10

Initial slice capacity for the values stored in a ResettingTimer

Variables

View Source 
var (
	DefaultRegistry    = NewRegistry()
	EphemeralRegistry  = NewRegistry()
	AccountingRegistry = NewRegistry() // registry used in swarm
)
View Source 
var DefaultConfig = Config{
	Enabled:          false,
	EnabledExpensive: false,
	HTTP:             "127.0.0.1",
	Port:             6060,
	EnableInfluxDB:   false,
	InfluxDBEndpoint: "http://localhost:8086",
	InfluxDBDatabase: "geth",
	InfluxDBUsername: "test",
	InfluxDBPassword: "test",
	InfluxDBTags:     "host=localhost",

	EnableInfluxDBV2:     false,
	InfluxDBToken:        "test",
	InfluxDBBucket:       "geth",
	InfluxDBOrganization: "geth",
}

DefaultConfig is the default config for metrics used in CortexTheseus.

View Source 
var Enabled = false

Enabled is checked by the constructor functions for all of the standard metrics. If it is true, the metric returned is a stub.

This global kill-switch helps quantify the observer effect and makes for less cluttered pprof profiles.

View Source 
var EnabledExpensive = false

EnabledExpensive is a soft-flag meant for external packages to check if costly metrics gathering is allowed or not. The goal is to separate standard metrics for health monitoring and debug metrics that might impact runtime performance.

Functions

func CalculatePercentiles added in v1.10.49 

func CalculatePercentiles(values []int64, ps []float64) []float64

CalculatePercentiles returns a slice of arbitrary percentiles of the slice of int64. This method returns interpolated results, so e.g if there are only two values, [0, 10], a 50% percentile will land between them.

Note: As a side-effect, this method will also sort the slice of values. Note2: The input format for percentiles is NOT percent! To express 50%, use 0.5, not 50.

func CaptureDebugGCStats 

func CaptureDebugGCStats(r Registry, d time.Duration)

Capture new values for the Go garbage collector statistics exported in debug.GCStats. This is designed to be called as a goroutine.

func CaptureDebugGCStatsOnce 

func CaptureDebugGCStatsOnce(r Registry)

Capture new values for the Go garbage collector statistics exported in debug.GCStats. This is designed to be called in a background goroutine. Giving a registry which has not been given to RegisterDebugGCStats will panic.

Be careful (but much less so) with this because debug.ReadGCStats calls the C function runtime·lock(runtime·mheap) which, while not a stop-the-world operation, isn't something you want to be doing all the time.

func CollectProcessMetrics 

func CollectProcessMetrics(refresh time.Duration)

CollectProcessMetrics periodically collects various metrics about the running process.

func Each 

func Each(f func(string, any))

Call the given function for each registered metric.

func Get 

func Get(name string) any

Get the metric by the given name or nil if none is registered.

func GetOrRegister 

func GetOrRegister(name string, i any) any

Gets an existing metric or creates and registers a new one. Threadsafe alternative to calling Get and Register on failure.

func Graphite 

func Graphite(r Registry, d time.Duration, prefix string, addr *net.TCPAddr)

Graphite is a blocking exporter function which reports metrics in r to a graphite server located at addr, flushing them every d duration and prepending metric names with prefix.

Example 
addr, _ := net.ResolveTCPAddr("net", ":2003")
go Graphite(DefaultRegistry, 1*time.Second, "some.prefix", addr)

Output:

func GraphiteOnce 

func GraphiteOnce(c GraphiteConfig) error

GraphiteOnce performs a single submission to Graphite, returning a non-nil error on failed connections. This can be used in a loop similar to GraphiteWithConfig for custom error handling.

func GraphiteWithConfig 

func GraphiteWithConfig(c GraphiteConfig)

GraphiteWithConfig is a blocking exporter function just like Graphite, but it takes a GraphiteConfig instead.

Example 
addr, _ := net.ResolveTCPAddr("net", ":2003")
go GraphiteWithConfig(GraphiteConfig{
	Addr:          addr,
	Registry:      DefaultRegistry,
	FlushInterval: 1 * time.Second,
	DurationUnit:  time.Millisecond,
	Percentiles:   []float64{0.5, 0.75, 0.99, 0.999},
})

Output:

func Log 

func Log(r Registry, freq time.Duration, l Logger)

func LogScaled 

func LogScaled(r Registry, freq time.Duration, scale time.Duration, l Logger)

Output each metric in the given registry periodically using the given logger. Print timings in `scale` units (eg time.Millisecond) rather than nanos.

func MustRegister 

func MustRegister(name string, i any)

Register the given metric under the given name. Panics if a metric by the given name is already registered.

func OpenTSDB 

func OpenTSDB(r Registry, d time.Duration, prefix string, addr *net.TCPAddr)

OpenTSDB is a blocking exporter function which reports metrics in r to a TSDB server located at addr, flushing them every d duration and prepending metric names with prefix.

Example 
addr, _ := net.ResolveTCPAddr("net", ":2003")
go OpenTSDB(DefaultRegistry, 1*time.Second, "some.prefix", addr)

Output:

func OpenTSDBWithConfig 

func OpenTSDBWithConfig(c OpenTSDBConfig)

OpenTSDBWithConfig is a blocking exporter function just like OpenTSDB, but it takes a OpenTSDBConfig instead.

Example 
addr, _ := net.ResolveTCPAddr("net", ":2003")
go OpenTSDBWithConfig(OpenTSDBConfig{
	Addr:          addr,
	Registry:      DefaultRegistry,
	FlushInterval: 1 * time.Second,
	DurationUnit:  time.Millisecond,
})

Output:

func ReadCPUStats added in v1.9.51 

func ReadCPUStats(stats *CPUStats)

ReadCPUStats retrieves the current CPU stats.

func ReadDiskStats 

func ReadDiskStats(stats *DiskStats) error

ReadDiskStats retrieves the disk IO stats belonging to the current process.

func ReadRuntimeStats added in v1.10.49 

func ReadRuntimeStats() *runtimeStats

func Register 

func Register(name string, i any) error

Register the given metric under the given name. Returns a DuplicateMetric if a metric by the given name is already registered.

func RegisterDebugGCStats 

func RegisterDebugGCStats(r Registry)

Register metrics for the Go garbage collector statistics exported in debug.GCStats. The metrics are named by their fully-qualified Go symbols, i.e. debug.GCStats.PauseTotal.

func RunHealthchecks 

func RunHealthchecks()

Run all registered healthchecks.

func RuntimeHistogramFromData added in v1.10.49 

func RuntimeHistogramFromData(scale float64, hist *metrics.Float64Histogram) *runtimeHistogram

func SamplePercentile 

func SamplePercentile(values []int64, p float64) float64

SamplePercentiles returns an arbitrary percentile of the slice of int64.

func SampleVariance 

func SampleVariance(mean float64, values []int64) float64

SampleVariance returns the variance of the slice of int64.

func Syslog 

func Syslog(r Registry, d time.Duration, w *syslog.Writer)

Output each metric in the given registry to syslog periodically using the given syslogger.

func Unregister 

func Unregister(name string)

Unregister the metric with the given name.

func Write 

func Write(r Registry, d time.Duration, w io.Writer)

Write sorts writes each metric in the given registry periodically to the given io.Writer.

func WriteJSON 

func WriteJSON(r Registry, d time.Duration, w io.Writer)

WriteJSON writes metrics from the given registry periodically to the specified io.Writer as JSON.

func WriteJSONOnce 

func WriteJSONOnce(r Registry, w io.Writer)

WriteJSONOnce writes metrics from the given registry to the specified io.Writer as JSON.

func WriteOnce 

func WriteOnce(r Registry, w io.Writer)

WriteOnce sorts and writes metrics in the given registry to the given io.Writer.

Types

type CPUStats added in v1.9.51 

type CPUStats struct {
	GlobalTime float64 // Time spent by the CPU working on all processes
	GlobalWait float64 // Time spent by waiting on disk for all processes
	LocalTime  float64 // Time spent by the CPU working on this process
}

CPUStats is the system and process CPU stats. All values are in seconds.

type Config added in v1.10.42 

type Config struct {
	Enabled          bool   `toml:",omitempty"`
	EnabledExpensive bool   `toml:",omitempty"`
	HTTP             string `toml:",omitempty"`
	Port             int    `toml:",omitempty"`
	EnableInfluxDB   bool   `toml:",omitempty"`
	InfluxDBEndpoint string `toml:",omitempty"`
	InfluxDBDatabase string `toml:",omitempty"`
	InfluxDBUsername string `toml:",omitempty"`
	InfluxDBPassword string `toml:",omitempty"`
	InfluxDBTags     string `toml:",omitempty"`

	EnableInfluxDBV2     bool   `toml:",omitempty"`
	InfluxDBToken        string `toml:",omitempty"`
	InfluxDBBucket       string `toml:",omitempty"`
	InfluxDBOrganization string `toml:",omitempty"`
}

Config contains the configuration for the metric collection.

type Counter 

type Counter interface {
	Clear()
	Dec(int64)
	Inc(int64)
	Snapshot() CounterSnapshot
}

Counters hold an int64 value that can be incremented and decremented.

func GetOrRegisterCounter 

func GetOrRegisterCounter(name string, r Registry) Counter

GetOrRegisterCounter returns an existing Counter or constructs and registers a new StandardCounter.

func GetOrRegisterCounterForced added in v1.9.52 

func GetOrRegisterCounterForced(name string, r Registry) Counter

GetOrRegisterCounterForced returns an existing Counter or constructs and registers a new Counter no matter the global switch is enabled or not. Be sure to unregister the counter from the registry once it is of no use to allow for garbage collection.

func NewCounter 

func NewCounter() Counter

NewCounter constructs a new StandardCounter.

func NewCounterForced added in v1.9.52 

func NewCounterForced() Counter

NewCounterForced constructs a new StandardCounter and returns it no matter if the global switch is enabled or not.

func NewRegisteredCounter 

func NewRegisteredCounter(name string, r Registry) Counter

NewRegisteredCounter constructs and registers a new StandardCounter.

func NewRegisteredCounterForced added in v1.9.52 

func NewRegisteredCounterForced(name string, r Registry) Counter

NewRegisteredCounterForced constructs and registers a new StandardCounter and launches a goroutine no matter the global switch is enabled or not. Be sure to unregister the counter from the registry once it is of no use to allow for garbage collection.

type CounterFloat64 added in v1.10.42 

type CounterFloat64 interface {
	Clear()
	Dec(float64)
	Inc(float64)
	Snapshot() CounterFloat64Snapshot
}

CounterFloat64 holds a float64 value that can be incremented and decremented.

func GetOrRegisterCounterFloat64 added in v1.10.42 

func GetOrRegisterCounterFloat64(name string, r Registry) CounterFloat64

GetOrRegisterCounterFloat64 returns an existing CounterFloat64 or constructs and registers a new StandardCounterFloat64.

func GetOrRegisterCounterFloat64Forced added in v1.10.42 

func GetOrRegisterCounterFloat64Forced(name string, r Registry) CounterFloat64

GetOrRegisterCounterFloat64Forced returns an existing CounterFloat64 or constructs and registers a new CounterFloat64 no matter the global switch is enabled or not. Be sure to unregister the counter from the registry once it is of no use to allow for garbage collection.

func NewCounterFloat64 added in v1.10.42 

func NewCounterFloat64() CounterFloat64

NewCounterFloat64 constructs a new StandardCounterFloat64.

func NewCounterFloat64Forced added in v1.10.42 

func NewCounterFloat64Forced() CounterFloat64

NewCounterFloat64Forced constructs a new StandardCounterFloat64 and returns it no matter if the global switch is enabled or not.

func NewRegisteredCounterFloat64 added in v1.10.42 

func NewRegisteredCounterFloat64(name string, r Registry) CounterFloat64

NewRegisteredCounterFloat64 constructs and registers a new StandardCounterFloat64.

func NewRegisteredCounterFloat64Forced added in v1.10.42 

func NewRegisteredCounterFloat64Forced(name string, r Registry) CounterFloat64

NewRegisteredCounterFloat64Forced constructs and registers a new StandardCounterFloat64 and launches a goroutine no matter the global switch is enabled or not. Be sure to unregister the counter from the registry once it is of no use to allow for garbage collection.

type CounterFloat64Snapshot added in v1.10.42 

type CounterFloat64Snapshot interface {
	Count() float64
}

type CounterSnapshot 

type CounterSnapshot interface {
	Count() int64
}

type DiskStats 

type DiskStats struct {
	ReadCount  int64 // Number of read operations executed
	ReadBytes  int64 // Total number of bytes read
	WriteCount int64 // Number of write operations executed
	WriteBytes int64 // Total number of byte written
}

DiskStats is the per process disk io stats.

type DuplicateMetric 

type DuplicateMetric string

DuplicateMetric is the error returned by Registry.Register when a metric already exists. If you mean to Register that metric you must first Unregister the existing metric.

func (DuplicateMetric) Error 

func (err DuplicateMetric) Error() string

type EWMA 

type EWMA interface {
	Snapshot() EWMASnapshot
	Tick()
	Update(int64)
}

EWMAs continuously calculate an exponentially-weighted moving average based on an outside source of clock ticks.

func NewEWMA 

func NewEWMA(alpha float64) EWMA

NewEWMA constructs a new EWMA with the given alpha.

func NewEWMA1 

func NewEWMA1() EWMA

NewEWMA1 constructs a new EWMA for a one-minute moving average.

func NewEWMA15 

func NewEWMA15() EWMA

NewEWMA15 constructs a new EWMA for a fifteen-minute moving average.

func NewEWMA5 

func NewEWMA5() EWMA

NewEWMA5 constructs a new EWMA for a five-minute moving average.

type EWMASnapshot 

type EWMASnapshot interface {
	Rate() float64
}

type ExpDecaySample 

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

ExpDecaySample is an exponentially-decaying sample using a forward-decaying priority reservoir. See Cormode et al's "Forward Decay: A Practical Time Decay Model for Streaming Systems".

<http://dimacs.rutgers.edu/~graham/pubs/papers/fwddecay.pdf>

func (*ExpDecaySample) Clear 

func (s *ExpDecaySample) Clear()

Clear clears all samples.

func (*ExpDecaySample) SetRand added in v1.10.42 

func (s *ExpDecaySample) SetRand(prng *rand.Rand) Sample

SetRand sets the random source (useful in tests)

func (*ExpDecaySample) Snapshot 

func (s *ExpDecaySample) Snapshot() SampleSnapshot

Snapshot returns a read-only copy of the sample.

func (*ExpDecaySample) Update 

func (s *ExpDecaySample) Update(v int64)

Update samples a new value.

type Gauge 

type Gauge interface {
	Snapshot() GaugeSnapshot
	Update(int64)
	UpdateIfGt(int64)
	Dec(int64)
	Inc(int64)
}

Gauges hold an int64 value that can be set arbitrarily.

func GetOrRegisterGauge 

func GetOrRegisterGauge(name string, r Registry) Gauge

GetOrRegisterGauge returns an existing Gauge or constructs and registers a new StandardGauge.

func NewGauge 

func NewGauge() Gauge

NewGauge constructs a new StandardGauge.

func NewRegisteredGauge 

func NewRegisteredGauge(name string, r Registry) Gauge

NewRegisteredGauge constructs and registers a new StandardGauge.

type GaugeFloat64 

type GaugeFloat64 interface {
	Snapshot() GaugeFloat64Snapshot
	Update(float64)
}

GaugeFloat64 hold a float64 value that can be set arbitrarily.

func GetOrRegisterGaugeFloat64 

func GetOrRegisterGaugeFloat64(name string, r Registry) GaugeFloat64

GetOrRegisterGaugeFloat64 returns an existing GaugeFloat64 or constructs and registers a new StandardGaugeFloat64.

func NewGaugeFloat64 

func NewGaugeFloat64() GaugeFloat64

NewGaugeFloat64 constructs a new StandardGaugeFloat64.

func NewRegisteredGaugeFloat64 

func NewRegisteredGaugeFloat64(name string, r Registry) GaugeFloat64

NewRegisteredGaugeFloat64 constructs and registers a new StandardGaugeFloat64.

type GaugeFloat64Snapshot 

type GaugeFloat64Snapshot interface {
	Value() float64
}

type GaugeInfo added in v1.10.48 

type GaugeInfo interface {
	Update(GaugeInfoValue)
	Snapshot() GaugeInfoSnapshot
}

GaugeInfos hold a GaugeInfoValue value that can be set arbitrarily.

func GetOrRegisterGaugeInfo added in v1.10.48 

func GetOrRegisterGaugeInfo(name string, r Registry) GaugeInfo

GetOrRegisterGaugeInfo returns an existing GaugeInfo or constructs and registers a new StandardGaugeInfo.

func NewGaugeInfo added in v1.10.48 

func NewGaugeInfo() GaugeInfo

NewGaugeInfo constructs a new StandardGaugeInfo.

func NewRegisteredGaugeInfo added in v1.10.48 

func NewRegisteredGaugeInfo(name string, r Registry) GaugeInfo

NewRegisteredGaugeInfo constructs and registers a new StandardGaugeInfo.

type GaugeInfoSnapshot added in v1.10.48 

type GaugeInfoSnapshot interface {
	Value() GaugeInfoValue
}

type GaugeInfoValue added in v1.10.48 

type GaugeInfoValue map[string]string

GaugeInfoValue is a mapping of keys to values

func (GaugeInfoValue) String added in v1.10.48 

func (val GaugeInfoValue) String() string

type GaugeSnapshot 

type GaugeSnapshot interface {
	Value() int64
}

gaugeSnapshot contains a readonly int64.

type GraphiteConfig 

type GraphiteConfig struct {
	Addr          *net.TCPAddr  // Network address to connect to
	Registry      Registry      // Registry to be exported
	FlushInterval time.Duration // Flush interval
	DurationUnit  time.Duration // Time conversion unit for durations
	Prefix        string        // Prefix to be prepended to metric names
	Percentiles   []float64     // Percentiles to export from timers and histograms
}

GraphiteConfig provides a container with configuration parameters for the Graphite exporter

type Healthcheck 

type Healthcheck interface {
	Check()
	Error() error
	Healthy()
	Unhealthy(error)
}

Healthchecks hold an error value describing an arbitrary up/down status.

func NewHealthcheck 

func NewHealthcheck(f func(Healthcheck)) Healthcheck

NewHealthcheck constructs a new Healthcheck which will use the given function to update its status.

type Histogram 

type Histogram interface {
	Clear()
	Update(int64)
	Snapshot() HistogramSnapshot
}

Histograms calculate distribution statistics from a series of int64 values.

func GetOrRegisterHistogram 

func GetOrRegisterHistogram(name string, r Registry, s Sample) Histogram

GetOrRegisterHistogram returns an existing Histogram or constructs and registers a new StandardHistogram.

func GetOrRegisterHistogramLazy added in v1.10.34 

func GetOrRegisterHistogramLazy(name string, r Registry, s func() Sample) Histogram

GetOrRegisterHistogramLazy returns an existing Histogram or constructs and registers a new StandardHistogram.

func NewHistogram 

func NewHistogram(s Sample) Histogram

NewHistogram constructs a new StandardHistogram from a Sample.

func NewRegisteredHistogram 

func NewRegisteredHistogram(name string, r Registry, s Sample) Histogram

NewRegisteredHistogram constructs and registers a new StandardHistogram from a Sample.

type HistogramSnapshot 

type HistogramSnapshot interface {
	SampleSnapshot
}

type Logger 

type Logger interface {
	Printf(format string, v ...any)
}

type Meter 

type Meter interface {
	Mark(int64)
	Snapshot() MeterSnapshot
	Stop()
}

Meters count events to produce exponentially-weighted moving average rates at one-, five-, and fifteen-minutes and a mean rate.

func GetOrRegisterMeter 

func GetOrRegisterMeter(name string, r Registry) Meter

GetOrRegisterMeter returns an existing Meter or constructs and registers a new StandardMeter. Be sure to unregister the meter from the registry once it is of no use to allow for garbage collection.

func NewInactiveMeter added in v1.10.48 

func NewInactiveMeter() Meter

NewInactiveMeter returns a meter but does not start any goroutines. This method is mainly intended for testing.

func NewMeter 

func NewMeter() Meter

NewMeter constructs a new StandardMeter and launches a goroutine. Be sure to call Stop() once the meter is of no use to allow for garbage collection.

func NewRegisteredMeter 

func NewRegisteredMeter(name string, r Registry) Meter

NewRegisteredMeter constructs and registers a new StandardMeter and launches a goroutine. Be sure to unregister the meter from the registry once it is of no use to allow for garbage collection.

type MeterSnapshot 

type MeterSnapshot interface {
	Count() int64
	Rate1() float64
	Rate5() float64
	Rate15() float64
	RateMean() float64
}

type NilCounter 

type NilCounter struct{}

NilCounter is a no-op Counter.

func (NilCounter) Clear 

func (NilCounter) Clear()

func (NilCounter) Dec 

func (NilCounter) Dec(i int64)

func (NilCounter) Inc 

func (NilCounter) Inc(i int64)

func (NilCounter) Snapshot 

func (NilCounter) Snapshot() CounterSnapshot

type NilCounterFloat64 added in v1.10.42 

type NilCounterFloat64 struct{}

func (NilCounterFloat64) Clear added in v1.10.42 

func (NilCounterFloat64) Clear()

func (NilCounterFloat64) Count added in v1.10.42 

func (NilCounterFloat64) Count() float64

func (NilCounterFloat64) Dec added in v1.10.42 

func (NilCounterFloat64) Dec(i float64)

func (NilCounterFloat64) Inc added in v1.10.42 

func (NilCounterFloat64) Inc(i float64)

func (NilCounterFloat64) Snapshot added in v1.10.42 

func (NilCounterFloat64) Snapshot() CounterFloat64Snapshot

type NilEWMA 

type NilEWMA struct{}

NilEWMA is a no-op EWMA.

func (NilEWMA) Snapshot 

func (NilEWMA) Snapshot() EWMASnapshot

func (NilEWMA) Tick 

func (NilEWMA) Tick()

func (NilEWMA) Update 

func (NilEWMA) Update(n int64)

type NilGauge 

type NilGauge struct{}

NilGauge is a no-op Gauge.

func (NilGauge) Dec added in v1.9.52 

func (NilGauge) Dec(i int64)

func (NilGauge) Inc added in v1.9.52 

func (NilGauge) Inc(i int64)

func (NilGauge) Snapshot 

func (NilGauge) Snapshot() GaugeSnapshot

func (NilGauge) Update 

func (NilGauge) Update(v int64)

func (NilGauge) UpdateIfGt added in v1.10.49 

func (NilGauge) UpdateIfGt(v int64)

type NilGaugeFloat64 

type NilGaugeFloat64 struct{}

NilGauge is a no-op Gauge.

func (NilGaugeFloat64) Snapshot 

func (NilGaugeFloat64) Snapshot() GaugeFloat64Snapshot

func (NilGaugeFloat64) Update 

func (NilGaugeFloat64) Update(v float64)

func (NilGaugeFloat64) Value 

func (NilGaugeFloat64) Value() float64

type NilGaugeInfo added in v1.10.48 

type NilGaugeInfo struct{}

func (NilGaugeInfo) Snapshot added in v1.10.48 

func (NilGaugeInfo) Snapshot() GaugeInfoSnapshot

func (NilGaugeInfo) Update added in v1.10.48 

func (NilGaugeInfo) Update(v GaugeInfoValue)

func (NilGaugeInfo) Value added in v1.10.48 

func (NilGaugeInfo) Value() GaugeInfoValue

type NilHealthcheck 

type NilHealthcheck struct{}

NilHealthcheck is a no-op.

func (NilHealthcheck) Check 

func (NilHealthcheck) Check()

Check is a no-op.

func (NilHealthcheck) Error 

func (NilHealthcheck) Error() error

Error is a no-op.

func (NilHealthcheck) Healthy 

func (NilHealthcheck) Healthy()

Healthy is a no-op.

func (NilHealthcheck) Unhealthy 

func (NilHealthcheck) Unhealthy(error)

Unhealthy is a no-op.

type NilHistogram 

type NilHistogram struct{}

NilHistogram is a no-op Histogram.

func (NilHistogram) Clear 

func (NilHistogram) Clear()

func (NilHistogram) Snapshot 

func (NilHistogram) Snapshot() HistogramSnapshot

func (NilHistogram) Update 

func (NilHistogram) Update(v int64)

type NilMeter 

type NilMeter struct{}

NilMeter is a no-op Meter.

func (NilMeter) Count 

func (NilMeter) Count() int64

func (NilMeter) Mark 

func (NilMeter) Mark(n int64)

func (NilMeter) Snapshot 

func (NilMeter) Snapshot() MeterSnapshot

func (NilMeter) Stop 

func (NilMeter) Stop()

type NilResettingTimer 

type NilResettingTimer struct{}

NilResettingTimer is a no-op ResettingTimer.

func (NilResettingTimer) Count added in v1.10.49 

func (NilResettingTimer) Count() int

func (NilResettingTimer) Max added in v1.10.49 

func (NilResettingTimer) Max() int64

func (NilResettingTimer) Mean 

func (NilResettingTimer) Mean() float64

func (NilResettingTimer) Min added in v1.10.49 

func (NilResettingTimer) Min() int64

func (NilResettingTimer) Percentiles 

func (NilResettingTimer) Percentiles([]float64) []float64

func (NilResettingTimer) Snapshot 

func (n NilResettingTimer) Snapshot() ResettingTimerSnapshot

func (NilResettingTimer) Time 

func (NilResettingTimer) Time(f func())

func (NilResettingTimer) Update 

func (NilResettingTimer) Update(time.Duration)

func (NilResettingTimer) UpdateSince 

func (NilResettingTimer) UpdateSince(time.Time)

func (NilResettingTimer) Values 

func (NilResettingTimer) Values() []int64

type NilSample 

type NilSample struct{}

NilSample is a no-op Sample.

func (NilSample) Clear 

func (NilSample) Clear()

func (NilSample) Snapshot 

func (NilSample) Snapshot() SampleSnapshot

func (NilSample) Update 

func (NilSample) Update(v int64)

type NilTimer 

type NilTimer struct{}

NilTimer is a no-op Timer.

func (NilTimer) Snapshot 

func (NilTimer) Snapshot() TimerSnapshot

func (NilTimer) Stop 

func (NilTimer) Stop()

func (NilTimer) Time 

func (NilTimer) Time(f func())

func (NilTimer) Update 

func (NilTimer) Update(time.Duration)

func (NilTimer) UpdateSince 

func (NilTimer) UpdateSince(time.Time)

type OpenTSDBConfig 

type OpenTSDBConfig struct {
	Addr          *net.TCPAddr  // Network address to connect to
	Registry      Registry      // Registry to be exported
	FlushInterval time.Duration // Flush interval
	DurationUnit  time.Duration // Time conversion unit for durations
	Prefix        string        // Prefix to be prepended to metric names
}

OpenTSDBConfig provides a container with configuration parameters for the OpenTSDB exporter

type PrefixedRegistry 

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

func (*PrefixedRegistry) Each 

func (r *PrefixedRegistry) Each(fn func(string, any))

Call the given function for each registered metric.

func (*PrefixedRegistry) Get 

func (r *PrefixedRegistry) Get(name string) any

Get the metric by the given name or nil if none is registered.

func (*PrefixedRegistry) GetAll 

func (r *PrefixedRegistry) GetAll() map[string]map[string]any

GetAll metrics in the Registry

func (*PrefixedRegistry) GetOrRegister 

func (r *PrefixedRegistry) GetOrRegister(name string, metric any) any

Gets an existing metric or registers the given one. The interface can be the metric to register if not found in registry, or a function returning the metric for lazy instantiation.

func (*PrefixedRegistry) MarshalJSON 

func (p *PrefixedRegistry) MarshalJSON() ([]byte, error)

func (*PrefixedRegistry) Register 

func (r *PrefixedRegistry) Register(name string, metric any) error

Register the given metric under the given name. The name will be prefixed.

func (*PrefixedRegistry) RunHealthchecks 

func (r *PrefixedRegistry) RunHealthchecks()

Run all registered healthchecks.

func (*PrefixedRegistry) Unregister 

func (r *PrefixedRegistry) Unregister(name string)

Unregister the metric with the given name. The name will be prefixed.

type Registry 

type Registry interface {

	// Call the given function for each registered metric.
	Each(func(string, any))

	// Get the metric by the given name or nil if none is registered.
	Get(string) any

	// GetAll metrics in the Registry.
	GetAll() map[string]map[string]any

	// Gets an existing metric or registers the given one.
	// The interface can be the metric to register if not found in registry,
	// or a function returning the metric for lazy instantiation.
	GetOrRegister(string, any) any

	// Register the given metric under the given name.
	Register(string, any) error

	// Run all registered healthchecks.
	RunHealthchecks()

	// Unregister the metric with the given name.
	Unregister(string)
}

A Registry holds references to a set of metrics by name and can iterate over them, calling callback functions provided by the user.

This is an interface so as to encourage other structs to implement the Registry API as appropriate.

func NewOrderedRegistry added in v1.10.48 

func NewOrderedRegistry() Registry

NewOrderedRegistry creates a new ordered registry (for testing).

func NewPrefixedChildRegistry 

func NewPrefixedChildRegistry(parent Registry, prefix string) Registry

func NewPrefixedRegistry 

func NewPrefixedRegistry(prefix string) Registry

func NewRegistry 

func NewRegistry() Registry

NewRegistry creates a new registry.

type ResettingTimer 

type ResettingTimer interface {
	Snapshot() ResettingTimerSnapshot
	Time(func())
	Update(time.Duration)
	UpdateSince(time.Time)
}

ResettingTimer is used for storing aggregated values for timers, which are reset on every flush interval.

func GetOrRegisterResettingTimer 

func GetOrRegisterResettingTimer(name string, r Registry) ResettingTimer

GetOrRegisterResettingTimer returns an existing ResettingTimer or constructs and registers a new StandardResettingTimer.

func NewRegisteredResettingTimer 

func NewRegisteredResettingTimer(name string, r Registry) ResettingTimer

NewRegisteredResettingTimer constructs and registers a new StandardResettingTimer.

func NewResettingTimer 

func NewResettingTimer() ResettingTimer

NewResettingTimer constructs a new StandardResettingTimer

type ResettingTimerSnapshot 

type ResettingTimerSnapshot interface {
	Count() int
	Mean() float64
	Max() int64
	Min() int64
	Percentiles([]float64) []float64
}

type Sample 

type Sample interface {
	Snapshot() SampleSnapshot
	Clear()
	Update(int64)
}

Samples maintain a statistically-significant selection of values from a stream.

func NewExpDecaySample 

func NewExpDecaySample(reservoirSize int, alpha float64) Sample

NewExpDecaySample constructs a new exponentially-decaying sample with the given reservoir size and alpha.

func NewUniformSample 

func NewUniformSample(reservoirSize int) Sample

NewUniformSample constructs a new uniform sample with the given reservoir size.

func ResettingSample added in v1.10.34 

func ResettingSample(sample Sample) Sample

ResettingSample converts an ordinary sample into one that resets whenever its snapshot is retrieved. This will break for multi-monitor systems, but when only a single metric is being pushed out, this ensure that low-frequency events don't skew th charts indefinitely.

type SampleSnapshot 

type SampleSnapshot interface {
	Count() int64
	Max() int64
	Mean() float64
	Min() int64
	Percentile(float64) float64
	Percentiles([]float64) []float64
	Size() int
	StdDev() float64
	Sum() int64
	Variance() float64
}

type StandardCounter 

type StandardCounter atomic.Int64

StandardCounter is the standard implementation of a Counter and uses the sync/atomic package to manage a single int64 value.

func (*StandardCounter) Clear 

func (c *StandardCounter) Clear()

Clear sets the counter to zero.

func (*StandardCounter) Dec 

func (c *StandardCounter) Dec(i int64)

Dec decrements the counter by the given amount.

func (*StandardCounter) Inc 

func (c *StandardCounter) Inc(i int64)

Inc increments the counter by the given amount.

func (*StandardCounter) Snapshot 

func (c *StandardCounter) Snapshot() CounterSnapshot

Snapshot returns a read-only copy of the counter.

type StandardCounterFloat64 added in v1.10.42 

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

StandardCounterFloat64 is the standard implementation of a CounterFloat64 and uses the atomic to manage a single float64 value.

func (*StandardCounterFloat64) Clear added in v1.10.42 

func (c *StandardCounterFloat64) Clear()

Clear sets the counter to zero.

func (*StandardCounterFloat64) Dec added in v1.10.42 

func (c *StandardCounterFloat64) Dec(v float64)

Dec decrements the counter by the given amount.

func (*StandardCounterFloat64) Inc added in v1.10.42 

func (c *StandardCounterFloat64) Inc(v float64)

Inc increments the counter by the given amount.

func (*StandardCounterFloat64) Snapshot added in v1.10.42 

func (c *StandardCounterFloat64) Snapshot() CounterFloat64Snapshot

Snapshot returns a read-only copy of the counter.

type StandardEWMA 

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

StandardEWMA is the standard implementation of an EWMA and tracks the number of uncounted events and processes them on each tick. It uses the sync/atomic package to manage uncounted events.

func (*StandardEWMA) Snapshot 

func (a *StandardEWMA) Snapshot() EWMASnapshot

Snapshot returns a read-only copy of the EWMA.

func (*StandardEWMA) Tick 

func (a *StandardEWMA) Tick()

Tick ticks the clock to update the moving average. It assumes it is called every five seconds.

func (*StandardEWMA) Update 

func (a *StandardEWMA) Update(n int64)

Update adds n uncounted events.

type StandardGauge 

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

StandardGauge is the standard implementation of a Gauge and uses the sync/atomic package to manage a single int64 value.

func (*StandardGauge) Dec added in v1.9.52 

func (g *StandardGauge) Dec(i int64)

Dec decrements the gauge's current value by the given amount.

func (*StandardGauge) Inc added in v1.9.52 

func (g *StandardGauge) Inc(i int64)

Inc increments the gauge's current value by the given amount.

func (*StandardGauge) Snapshot 

func (g *StandardGauge) Snapshot() GaugeSnapshot

Snapshot returns a read-only copy of the gauge.

func (*StandardGauge) Update 

func (g *StandardGauge) Update(v int64)

Update updates the gauge's value.

func (*StandardGauge) UpdateIfGt added in v1.10.49 

func (g *StandardGauge) UpdateIfGt(v int64)

Update updates the gauge's value if v is larger then the current valie.

type StandardGaugeFloat64 

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

StandardGaugeFloat64 is the standard implementation of a GaugeFloat64 and uses atomic to manage a single float64 value.

func (*StandardGaugeFloat64) Snapshot 

func (g *StandardGaugeFloat64) Snapshot() GaugeFloat64Snapshot

Snapshot returns a read-only copy of the gauge.

func (*StandardGaugeFloat64) Update 

func (g *StandardGaugeFloat64) Update(v float64)

Update updates the gauge's value.

type StandardGaugeInfo added in v1.10.48 

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

StandardGaugeInfo is the standard implementation of a GaugeInfo and uses sync.Mutex to manage a single string value.

func (*StandardGaugeInfo) Snapshot added in v1.10.48 

func (g *StandardGaugeInfo) Snapshot() GaugeInfoSnapshot

Snapshot returns a read-only copy of the gauge.

func (*StandardGaugeInfo) Update added in v1.10.48 

func (g *StandardGaugeInfo) Update(v GaugeInfoValue)

Update updates the gauge's value.

type StandardHealthcheck 

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

StandardHealthcheck is the standard implementation of a Healthcheck and stores the status and a function to call to update the status.

func (*StandardHealthcheck) Check 

func (h *StandardHealthcheck) Check()

Check runs the healthcheck function to update the healthcheck's status.

func (*StandardHealthcheck) Error 

func (h *StandardHealthcheck) Error() error

Error returns the healthcheck's status, which will be nil if it is healthy.

func (*StandardHealthcheck) Healthy 

func (h *StandardHealthcheck) Healthy()

Healthy marks the healthcheck as healthy.

func (*StandardHealthcheck) Unhealthy 

func (h *StandardHealthcheck) Unhealthy(err error)

Unhealthy marks the healthcheck as unhealthy. The error is stored and may be retrieved by the Error method.

type StandardHistogram 

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

StandardHistogram is the standard implementation of a Histogram and uses a Sample to bound its memory use.

func (*StandardHistogram) Clear 

func (h *StandardHistogram) Clear()

Clear clears the histogram and its sample.

func (*StandardHistogram) Snapshot 

func (h *StandardHistogram) Snapshot() HistogramSnapshot

Snapshot returns a read-only copy of the histogram.

func (*StandardHistogram) Update 

func (h *StandardHistogram) Update(v int64)

Update samples a new value.

type StandardMeter 

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

StandardMeter is the standard implementation of a Meter.

func (*StandardMeter) Mark 

func (m *StandardMeter) Mark(n int64)

Mark records the occurrence of n events.

func (*StandardMeter) Snapshot 

func (m *StandardMeter) Snapshot() MeterSnapshot

Snapshot returns a read-only copy of the meter.

func (*StandardMeter) Stop 

func (m *StandardMeter) Stop()

Stop stops the meter, Mark() will be a no-op if you use it after being stopped.

type StandardRegistry 

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

The standard implementation of a Registry uses sync.map of names to metrics.

func (*StandardRegistry) Each 

func (r *StandardRegistry) Each(f func(string, any))

Call the given function for each registered metric.

func (*StandardRegistry) Get 

func (r *StandardRegistry) Get(name string) any

Get the metric by the given name or nil if none is registered.

func (*StandardRegistry) GetAll 

func (r *StandardRegistry) GetAll() map[string]map[string]any

GetAll metrics in the Registry

func (*StandardRegistry) GetOrRegister 

func (r *StandardRegistry) GetOrRegister(name string, i any) any

Gets an existing metric or creates and registers a new one. Threadsafe alternative to calling Get and Register on failure. The interface can be the metric to register if not found in registry, or a function returning the metric for lazy instantiation.

func (*StandardRegistry) MarshalJSON 

func (r *StandardRegistry) MarshalJSON() ([]byte, error)

MarshalJSON returns a byte slice containing a JSON representation of all the metrics in the Registry.

func (*StandardRegistry) Register 

func (r *StandardRegistry) Register(name string, i any) error

Register the given metric under the given name. Returns a DuplicateMetric if a metric by the given name is already registered.

func (*StandardRegistry) RunHealthchecks 

func (r *StandardRegistry) RunHealthchecks()

Run all registered healthchecks.

func (*StandardRegistry) Unregister 

func (r *StandardRegistry) Unregister(name string)

Unregister the metric with the given name.

type StandardResettingTimer 

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

StandardResettingTimer is the standard implementation of a ResettingTimer. and Meter.

func (*StandardResettingTimer) Snapshot 

func (t *StandardResettingTimer) Snapshot() ResettingTimerSnapshot

Snapshot resets the timer and returns a read-only copy of its contents.

func (*StandardResettingTimer) Time 

func (t *StandardResettingTimer) Time(f func())

Record the duration of the execution of the given function.

func (*StandardResettingTimer) Update 

func (t *StandardResettingTimer) Update(d time.Duration)

Record the duration of an event.

func (*StandardResettingTimer) UpdateSince 

func (t *StandardResettingTimer) UpdateSince(ts time.Time)

Record the duration of an event that started at a time and ends now.

type StandardTimer 

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

StandardTimer is the standard implementation of a Timer and uses a Histogram and Meter.

func (*StandardTimer) Snapshot 

func (t *StandardTimer) Snapshot() TimerSnapshot

Snapshot returns a read-only copy of the timer.

func (*StandardTimer) Stop 

func (t *StandardTimer) Stop()

Stop stops the meter.

func (*StandardTimer) Time 

func (t *StandardTimer) Time(f func())

Record the duration of the execution of the given function.

func (*StandardTimer) Update 

func (t *StandardTimer) Update(d time.Duration)

Record the duration of an event.

func (*StandardTimer) UpdateSince 

func (t *StandardTimer) UpdateSince(ts time.Time)

Record the duration of an event that started at a time and ends now.

type Stoppable 

type Stoppable interface {
	Stop()
}

Stoppable defines the metrics which has to be stopped.

type Timer 

type Timer interface {
	Snapshot() TimerSnapshot
	Stop()
	Time(func())
	UpdateSince(time.Time)
	Update(time.Duration)
}

Timers capture the duration and rate of events.

func GetOrRegisterTimer 

func GetOrRegisterTimer(name string, r Registry) Timer

GetOrRegisterTimer returns an existing Timer or constructs and registers a new StandardTimer. Be sure to unregister the meter from the registry once it is of no use to allow for garbage collection.

Example 
m := "account.create.latency"
t := GetOrRegisterTimer(m, nil)
t.Update(47)
fmt.Println(t.Snapshot().Max()) 

Output:

47

func NewCustomTimer 

func NewCustomTimer(h Histogram, m Meter) Timer

NewCustomTimer constructs a new StandardTimer from a Histogram and a Meter. Be sure to call Stop() once the timer is of no use to allow for garbage collection.

func NewRegisteredTimer 

func NewRegisteredTimer(name string, r Registry) Timer

NewRegisteredTimer constructs and registers a new StandardTimer. Be sure to unregister the meter from the registry once it is of no use to allow for garbage collection.

func NewTimer 

func NewTimer() Timer

NewTimer constructs a new StandardTimer using an exponentially-decaying sample with the same reservoir size and alpha as UNIX load averages. Be sure to call Stop() once the timer is of no use to allow for garbage collection.

type TimerSnapshot 

type TimerSnapshot interface {
	HistogramSnapshot
	MeterSnapshot
}

type UniformSample 

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

A uniform sample using Vitter's Algorithm R.

<http://www.cs.umd.edu/~samir/498/vitter.pdf>

func (*UniformSample) Clear 

func (s *UniformSample) Clear()

Clear clears all samples.

func (*UniformSample) SetRand added in v1.10.42 

func (s *UniformSample) SetRand(prng *rand.Rand) Sample

SetRand sets the random source (useful in tests)

func (*UniformSample) Snapshot 

func (s *UniformSample) Snapshot() SampleSnapshot

Snapshot returns a read-only copy of the sample.

func (*UniformSample) Update 

func (s *UniformSample) Update(v int64)

Update samples a new value.

Source Files

View all Source files

Directories

Path Synopsis
Hook go-metrics into expvar on any /debug/metrics request, load all vars from the registry into expvar, and execute regular expvar handler
 Hook go-metrics into expvar on any /debug/metrics request, load all vars from the registry into expvar, and execute regular expvar handler
Package prometheus exposes go-metrics into a Prometheus format.
 Package prometheus exposes go-metrics into a Prometheus format.

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.