Categorygithub.com/ethereum/go-ethereummetrics
package
1.15.2
Repository: https://github.com/ethereum/go-ethereum.git
Documentation: pkg.go.dev
Versions
2
Dependencies
25
Dependents
9.2k
Files
2.2k SLOC

# 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 emit every metric to StatHat:

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

go stathat.Stathat(metrics.DefaultRegistry, 10e9, "[email protected]")

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:

# Packages

Package prometheus exposes go-metrics into a Prometheus format.

# Functions

CalculatePercentiles returns a slice of arbitrary percentiles of the slice of int64.
CaptureDebugGCStats captures new values for the Go garbage collector statistics exported in debug.GCStats.
CaptureDebugGCStatsOnce captures new values for the Go garbage collector statistics exported in debug.GCStats.
CollectProcessMetrics periodically collects various metrics about the running process.
Each call the given function for each registered metric.
Enable enables the metrics system.
Enabled is checked by functions that are deemed 'expensive', e.g.
Get the metric by the given name or nil if none is registered.
GetOrRegister gets an existing metric or creates and registers a new one.
GetOrRegisterCounter returns an existing Counter or constructs and registers a new Counter.
GetOrRegisterCounterFloat64 returns an existing *CounterFloat64 or constructs and registers a new CounterFloat64.
GetOrRegisterGauge returns an existing Gauge or constructs and registers a new Gauge.
GetOrRegisterGaugeFloat64 returns an existing GaugeFloat64 or constructs and registers a new GaugeFloat64.
GetOrRegisterGaugeInfo returns an existing GaugeInfo or constructs and registers a new GaugeInfo.
GetOrRegisterHistogram returns an existing Histogram or constructs and registers a new StandardHistogram.
GetOrRegisterHistogramLazy returns an existing Histogram or constructs and registers a new StandardHistogram.
GetOrRegisterMeter returns an existing Meter or constructs and registers a new Meter.
GetOrRegisterResettingTimer returns an existing ResettingTimer or constructs and registers a new ResettingTimer.
GetOrRegisterTimer returns an existing Timer or constructs and registers a new Timer.
LogScaled outputs each metric in the given registry periodically using the given logger.
MustRegister register the given metric under the given name.
NewCounter constructs a new Counter.
NewCounterFloat64 constructs a new CounterFloat64.
NewCustomTimer constructs a new Timer from a Histogram and a Meter.
NewEWMA constructs a new EWMA with the given alpha.
NewEWMA1 constructs a new EWMA for a one-minute moving average.
NewEWMA15 constructs a new EWMA for a fifteen-minute moving average.
NewEWMA5 constructs a new EWMA for a five-minute moving average.
NewExpDecaySample constructs a new exponentially-decaying sample with the given reservoir size and alpha.
NewGauge constructs a new Gauge.
NewGaugeFloat64 constructs a new GaugeFloat64.
NewGaugeInfo constructs a new GaugeInfo.
NewHealthcheck constructs a new Healthcheck which will use the given function to update its status.
NewHistogram constructs a new StandardHistogram from a Sample.
NewInactiveMeter returns a meter but does not start any goroutines.
NewMeter constructs a new Meter and launches a goroutine.
NewOrderedRegistry creates a new ordered registry (for testing).
NewRegisteredCounter constructs and registers a new Counter.
NewRegisteredCounterFloat64 constructs and registers a new CounterFloat64.
NewRegisteredGauge constructs and registers a new Gauge.
NewRegisteredGaugeFloat64 constructs and registers a new GaugeFloat64.
NewRegisteredGaugeInfo constructs and registers a new GaugeInfo.
NewRegisteredHistogram constructs and registers a new StandardHistogram from a Sample.
NewRegisteredMeter constructs and registers a new Meter and launches a goroutine.
NewRegisteredResettingTimer constructs and registers a new ResettingTimer.
NewRegisteredTimer constructs and registers a new Timer.
NewRegistry creates a new registry.
NewResettingTimer constructs a new ResettingTimer.
NewTimer constructs a new Timer using an exponentially-decaying sample with the same reservoir size and alpha as UNIX load averages.
NewUniformSample constructs a new uniform sample with the given reservoir size.
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.
OpenTSDBWithConfig is a blocking exporter function just like OpenTSDB, but it takes a OpenTSDBConfig instead.
ReadCPUStats retrieves the current CPU stats.
ReadDiskStats retrieves the disk IO stats belonging to the current process.
Register the given metric under the given name.
RegisterDebugGCStats registers metrics for the Go garbage collector statistics exported in debug.GCStats.
ResettingSample converts an ordinary sample into one that resets whenever its snapshot is retrieved.
RunHealthchecks run all registered healthchecks.
SamplePercentile returns an arbitrary percentile of the slice of int64.
SampleVariance returns the variance of the slice of int64.
Syslog outputs each metric in the given registry to syslog periodically using the given syslogger.
Unregister the metric with the given name.
Write sorts writes each metric in the given registry periodically to the given io.Writer.
WriteJSON writes metrics from the given registry periodically to the specified io.Writer as JSON.
WriteJSONOnce writes metrics from the given registry to the specified io.Writer as JSON.
WriteOnce sorts and writes metrics in the given registry to the given io.Writer.

# Variables

DefaultConfig is the default config for metrics used in go-ethereum.
ErrDuplicateMetric is the error returned by Registry.Register when a metric already exists.

# Structs

Config contains the configuration for the metric collection.
CPUStats is the system and process CPU stats.
DiskStats is the per process disk io stats.
EWMA continuously calculate an exponentially-weighted moving average based on an outside source of clock ticks.
ExpDecaySample is an exponentially-decaying sample using a forward-decaying priority reservoir.
GaugeInfo maintains a set of key/value mappings.
Healthcheck is the standard implementation of a Healthcheck and stores the status and a function to call to update the status.
Meter count events to produce exponentially-weighted moving average rates at one-, five-, and fifteen-minutes and a mean rate.
MeterSnapshot is a read-only copy of the meter's internal values.
OpenTSDBConfig provides a container with configuration parameters for the OpenTSDB exporter.
ResettingTimer is used for storing aggregated values for timers, which are reset on every flush interval.
ResettingTimerSnapshot is a point-in-time copy of another ResettingTimer.
StandardHistogram is the standard implementation of a Histogram and uses a Sample to bound its memory use.
StandardRegistry the standard implementation of a Registry uses sync.map of names to metrics.
Timer captures the duration and rate of events, using a Histogram and a Meter.
TimerSnapshot is a read-only copy of another Timer.
UniformSample implements a uniform sample using Vitter's Algorithm R.

# Interfaces

Histogram calculates distribution statistics from a series of int64 values.
A Registry holds references to a set of metrics by name and can iterate over them, calling callback functions provided by the user.
Sample maintains a statistically-significant selection of values from a stream.
Stoppable defines the metrics which has to be stopped.

# Type aliases

Counter hold an int64 value that can be incremented and decremented.
CounterFloat64 holds a float64 value that can be incremented and decremented.
CounterFloat64Snapshot is a read-only copy of a float64 counter.
CounterSnapshot is a read-only copy of a Counter.
EWMASnapshot is a read-only copy of an EWMA.
Gauge holds an int64 value that can be set arbitrarily.
GaugeFloat64 hold a float64 value that can be set arbitrarily.
GaugeFloat64Snapshot is a read-only copy of a GaugeFloat64.
GaugeInfoSnapshot is a read-only copy of another GaugeInfo.
GaugeInfoValue is a mapping of keys to values.
GaugeSnapshot is a read-only copy of a Gauge.