metric

package
v0.0.0-...-a3ba52b Latest Latest
Warning

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

 Go to latest Published: Jul 23, 2016 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package metric provides server metrics (a.k.a. transient stats) for a CockroachDB server. These metrics are persisted to the time-series database and are viewable through the web interface and the /_status/metrics/<NODEID> HTTP endpoint.

Adding a new metric

First, add the metric to a Registry.

Next, call methods such as Counter() and Rate() on the Registry to register the metric. For example: 

exec := &Executor{
	...
	selectCount: sqlRegistry.Counter("sql.select.count"),
	...
}

This code block registers the metric "sql.select.count" in sql.Registry. The metric can then be accessed through the "selectCount" variable, which can be updated as follows: 

func (e *Executor) doSelect() {
	// do the SELECT
	e.selectCount.Inc(1)
}

To add the metric to the web UI, modify the appropriate file in "ui/ts/pages/*.ts". Someone more qualified than me can elaborate, like @maxlang.

Sub-registries

It's common for a Registry to become part of another Registry through the "Add" and "MustAdd" methods. 

func NewNodeStatusMonitor(serverRegistry *registry) {
	nodeRegistry := metric.NewRegistry()

	// Add the registry for this node to the root-level server Registry. When
	// accessed from through the serverRegistry, all metrics from the
	// nodeRegistry will have the prefix "cr.node.".
	serverRegistry.MustAdd("cr.node.%s", nodeRegistry)
}

Node-level sub-registries are added by calling: 

(*metric.MetricRecorder).AddNodeRegistry(YOUR_NODE_SUBREGISTRY)

Testing

After your test does something to trigger your new metric update, you'll probably want to call methods in TestServer such as MustGetSQLCounter() to verify that the metric was updated correctly. See "sql/metric_test.go" for an example.

Additionally, you can manually verify that your metric is updating by using the metrics endpoint. For example, if you're running the Cockroach DB server with the "--insecure" flag, you can use access the endpoint as follows: 

$ curl http://localhost:26257/_status/metrics/1

(some other output)
"cr.node.sql.select.count.1": 5,
(some other output)

Note that a prefix and suffix have been added. The prefix "cr.node." denotes that this metric is node-level. The suffix ".1" specifies that this metric is for node 1.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// Scale1M is a 1 minute window for windowed stats (e.g. Rates and Histograms).
	Scale1M = TimeScale{"1m", 1 * time.Minute}

	// Scale10M is a 10 minute window for windowed stats (e.g. Rates and Histograms).
	Scale10M = TimeScale{"10m", 10 * time.Minute}

	// Scale1H is a 1 hour window for windowed stats (e.g. Rates and Histograms).
	Scale1H = TimeScale{"1h", time.Hour}
)
View Source 
var DefaultTimeScales = []TimeScale{Scale1M, Scale10M, Scale1H}

DefaultTimeScales are the durations used for helpers which create windowed metrics in bulk (such as Latency or Rates).

Functions

func TestingSetNow 

func TestingSetNow(f func() time.Time) func()

TestingSetNow changes the clock used by the metric system. For use by testing to precisely control the clock.

Types

type Counter 

type Counter struct {
	metrics.Counter
}

A Counter holds a single mutable atomic value.

func NewCounter 

func NewCounter() *Counter

NewCounter creates a counter.

func (*Counter) Each 

func (c *Counter) Each(f func(string, interface{}))

Each calls the given closure with the empty string and itself.

func (*Counter) FillPrometheusMetric 

func (c *Counter) FillPrometheusMetric(promMetric *prometheusgo.MetricFamily)

FillPrometheusMetric fills the appropriate metric fields.

func (*Counter) MarshalJSON 

func (c *Counter) MarshalJSON() ([]byte, error)

MarshalJSON marshals to JSON.

type Gauge 

type Gauge struct {
	metrics.Gauge
}

A Gauge atomically stores a single integer value.

func NewGauge 

func NewGauge() *Gauge

NewGauge creates a Gauge.

func (*Gauge) Each 

func (g *Gauge) Each(f func(string, interface{}))

Each calls the given closure with the empty string and itself.

func (*Gauge) FillPrometheusMetric 

func (g *Gauge) FillPrometheusMetric(promMetric *prometheusgo.MetricFamily)

FillPrometheusMetric fills the appropriate metric fields.

func (*Gauge) MarshalJSON 

func (g *Gauge) MarshalJSON() ([]byte, error)

MarshalJSON marshals to JSON.

type GaugeFloat64 

type GaugeFloat64 struct {
	metrics.GaugeFloat64
}

A GaugeFloat64 atomically stores a single float64 value.

func NewGaugeFloat64 

func NewGaugeFloat64() *GaugeFloat64

NewGaugeFloat64 creates a GaugeFloat64.

func (*GaugeFloat64) Each 

func (g *GaugeFloat64) Each(f func(string, interface{}))

Each calls the given closure with the empty string and itself.

func (*GaugeFloat64) FillPrometheusMetric 

func (g *GaugeFloat64) FillPrometheusMetric(promMetric *prometheusgo.MetricFamily)

FillPrometheusMetric fills the appropriate metric fields.

func (*GaugeFloat64) MarshalJSON 

func (g *GaugeFloat64) MarshalJSON() ([]byte, error)

MarshalJSON marshals to JSON.

type Histogram 

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

A Histogram is a wrapper around an hdrhistogram.WindowedHistogram.

func NewHistogram 

func NewHistogram(duration time.Duration, maxVal int64, sigFigs int) *Histogram

NewHistogram creates a new windowed HDRHistogram with the given parameters. Data is kept in the active window for approximately the given duration. See the documentation for hdrhistogram.WindowedHistogram for details.

func (*Histogram) Current 

func (h *Histogram) Current() *hdrhistogram.Histogram

Current returns a copy of the data currently in the window.

func (*Histogram) Each 

func (h *Histogram) Each(f func(string, interface{}))

Each calls the closure with the empty string and the receiver.

func (*Histogram) FillPrometheusMetric 

func (h *Histogram) FillPrometheusMetric(promMetric *prometheusgo.MetricFamily)

FillPrometheusMetric fills the appropriate metric fields.

func (*Histogram) MarshalJSON 

func (h *Histogram) MarshalJSON() ([]byte, error)

MarshalJSON outputs to JSON.

func (*Histogram) RecordValue 

func (h *Histogram) RecordValue(v int64)

RecordValue adds the given value to the histogram, truncating if necessary.

type Histograms 

type Histograms map[TimeScale]*Histogram

Histograms is a map of Histogram metrics.

func (Histograms) RecordValue 

func (hs Histograms) RecordValue(v int64)

RecordValue calls through to each individual Histogram.

type Iterable 

type Iterable interface {
	// Each calls the given closure with each contained item.
	Each(func(string, interface{}))
}

Iterable provides a method for synchronized access to interior objects.

type PrometheusExportable 

type PrometheusExportable interface {
	// FillPrometheusMetric takes an initialized prometheus metric object and
	// fills the appropriate fields for the metric type.
	FillPrometheusMetric(promMetric *prometheusgo.MetricFamily)
}

PrometheusExportable provides a method to fill in a prometheus object.

type Rate 

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

A Rate is a exponential weighted moving average.

func NewRate 

func NewRate(timescale time.Duration) *Rate

NewRate creates an EWMA rate on the given timescale. Timescales at or below 2s are illegal and will cause a panic.

func (*Rate) Add 

func (e *Rate) Add(v float64)

Add adds the given measurement to the Rate.

func (*Rate) Each 

func (e *Rate) Each(f func(string, interface{}))

Each calls the given closure with the empty string and the Rate's current value. TODO(mrtracy): Fix this to pass the Rate object itself to 'f', to match the 'visitor' behavior as the other metric types (currently, it passes the current value of the Rate as a float64.)

func (*Rate) MarshalJSON 

func (e *Rate) MarshalJSON() ([]byte, error)

MarshalJSON marshals to JSON.

func (*Rate) Value 

func (e *Rate) Value() float64

Value returns the current value of the Rate.

type Rates 

type Rates struct {
	*Counter
	Rates map[TimeScale]*Rate
}

Rates is a counter and associated EWMA backed rates at different time scales.

func (Rates) Add 

func (es Rates) Add(v int64)

Add adds the given value to all contained objects.

type Registry 

type Registry struct {
	sync.Mutex
	// contains filtered or unexported fields
}

A Registry bundles up various iterables (i.e. typically metrics or other registries) to provide a single point of access to them.

A Registry can be added to another Registry through the Add/MustAdd methods. This allows a hierarchy of Registry instances to be created.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry creates a new Registry.

func (*Registry) Add 

func (r *Registry) Add(format string, item Iterable) error

Add links the given Iterable into this registry using the given format string. The individual items in the registry will be formatted via fmt.Sprintf(format, <name>). As a special case, *Registry implements Iterable and can thus be added. Metric types in this package have helpers that allow them to be created and registered in a single step. Add is called manually only when adding a registry to another, or when integrating metrics defined elsewhere.

func (*Registry) Counter 

func (r *Registry) Counter(name string) *Counter

Counter registers new counter to the registry.

func (*Registry) Each 

func (r *Registry) Each(f func(name string, val interface{}))

Each calls the given closure for all metrics.

func (*Registry) Gauge 

func (r *Registry) Gauge(name string) *Gauge

Gauge registers a new Gauge with the given name.

func (*Registry) GaugeFloat64 

func (r *Registry) GaugeFloat64(name string) *GaugeFloat64

GaugeFloat64 registers a new GaugeFloat64 with the given name.

func (*Registry) GetCounter 

func (r *Registry) GetCounter(name string) *Counter

GetCounter returns the Counter in this registry with the given name. If a Counter with this name is not present (including if a non-Counter Iterable is registered with the name), nil is returned.

func (*Registry) GetGauge 

func (r *Registry) GetGauge(name string) *Gauge

GetGauge returns the Gauge in this registry with the given name. If a Gauge with this name is not present (including if a non-Gauge Iterable is registered with the name), nil is returned.

func (*Registry) GetRate 

func (r *Registry) GetRate(name string) *Rate

GetRate returns the Rate in this registry with the given name. If a Rate with this name is not present (including if a non-Rate Iterable is registered with the name), nil is returned.

func (*Registry) Histogram 

func (r *Registry) Histogram(name string, duration time.Duration, maxVal int64,
	sigFigs int) *Histogram

Histogram registers a new windowed HDRHistogram with the given parameters. Data is kept in the active window for approximately the given duration.

func (*Registry) Latency 

func (r *Registry) Latency(prefix string) Histograms

Latency is a convenience function which registers histograms with suitable defaults for latency tracking. Values are expressed in ns, are truncated into the interval [0, time.Minute] and are recorded with two digits of precision (i.e. errors of <1ms at 100ms, <.6s at 1m). The generated names of the metric will begin with the given prefix.

TODO(mrtracy,tschottdorf): need to discuss roll-ups and generally how (and which) information flows between metrics and time series.

func (*Registry) MarshalJSON 

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

MarshalJSON marshals to JSON.

func (*Registry) MustAdd 

func (r *Registry) MustAdd(format string, item Iterable)

MustAdd calls Add and panics on error.

func (*Registry) PrintAsText 

func (r *Registry) PrintAsText(w io.Writer) error

PrintAsText outputs all metrics in text format.

func (*Registry) Rate 

func (r *Registry) Rate(name string, timescale time.Duration) *Rate

Rate creates an EWMA rate over the given timescale. The comments on NewRate apply.

func (*Registry) Rates 

func (r *Registry) Rates(prefix string) Rates

Rates registers and returns a new Rates instance, which contains a set of EWMA-based rates with generally useful time scales and a cumulative counter.

type TimeScale 

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

A TimeScale is a named duration.

func (TimeScale) Name 

func (ts TimeScale) Name() string

Name returns the name of the TimeScale.

Source Files

View all Source files

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.