cockroach: github.com/aishraj/cockroach/util/metric Index | Files

package metric

import "github.com/aishraj/cockroach/util/metric"

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:8080/_status/nodes/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

Package Files

doc.go metric.go metric_group.go prometheus_exporter.go registry.go

Variables

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}
)
var DefaultTimeScales = []TimeScale{Scale1M, Scale10M, Scale1H}

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

func TestingSetNow Uses

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.

type Counter Uses

type Counter struct {
    Metadata
    metrics.Counter
}

A Counter holds a single mutable atomic value.

func NewCounter Uses

func NewCounter(metadata Metadata) *Counter

NewCounter creates a counter.

func (*Counter) GetType Uses

func (c *Counter) GetType() *prometheusgo.MetricType

GetType returns the prometheus type enum for this metric.

func (*Counter) Inspect Uses

func (c *Counter) Inspect(f func(interface{}))

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

func (*Counter) MarshalJSON Uses

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

MarshalJSON marshals to JSON.

func (*Counter) ToPrometheusMetric Uses

func (c *Counter) ToPrometheusMetric() *prometheusgo.Metric

ToPrometheusMetric returns a filled-in prometheus metric of the right type.

type Gauge Uses

type Gauge struct {
    Metadata
    metrics.Gauge
}

A Gauge atomically stores a single integer value.

func NewGauge Uses

func NewGauge(metadata Metadata) *Gauge

NewGauge creates a Gauge.

func (*Gauge) GetType Uses

func (g *Gauge) GetType() *prometheusgo.MetricType

GetType returns the prometheus type enum for this metric.

func (*Gauge) Inspect Uses

func (g *Gauge) Inspect(f func(interface{}))

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

func (*Gauge) MarshalJSON Uses

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

MarshalJSON marshals to JSON.

func (*Gauge) ToPrometheusMetric Uses

func (g *Gauge) ToPrometheusMetric() *prometheusgo.Metric

ToPrometheusMetric returns a filled-in prometheus metric of the right type.

type GaugeFloat64 Uses

type GaugeFloat64 struct {
    Metadata
    metrics.GaugeFloat64
}

A GaugeFloat64 atomically stores a single float64 value.

func NewGaugeFloat64 Uses

func NewGaugeFloat64(metadata Metadata) *GaugeFloat64

NewGaugeFloat64 creates a GaugeFloat64.

func (*GaugeFloat64) GetType Uses

func (g *GaugeFloat64) GetType() *prometheusgo.MetricType

GetType returns the prometheus type enum for this metric.

func (*GaugeFloat64) Inspect Uses

func (g *GaugeFloat64) Inspect(f func(interface{}))

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

func (*GaugeFloat64) MarshalJSON Uses

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

MarshalJSON marshals to JSON.

func (*GaugeFloat64) ToPrometheusMetric Uses

func (g *GaugeFloat64) ToPrometheusMetric() *prometheusgo.Metric

ToPrometheusMetric returns a filled-in prometheus metric of the right type.

type Histogram Uses

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

A Histogram is a wrapper around an hdrhistogram.WindowedHistogram.

func NewHistogram Uses

func NewHistogram(metadata Metadata, 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 Uses

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

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

func (*Histogram) GetType Uses

func (h *Histogram) GetType() *prometheusgo.MetricType

GetType returns the prometheus type enum for this metric.

func (*Histogram) Inspect Uses

func (h *Histogram) Inspect(f func(interface{}))

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

func (*Histogram) MarshalJSON Uses

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

MarshalJSON outputs to JSON.

func (*Histogram) RecordValue Uses

func (h *Histogram) RecordValue(v int64)

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

func (*Histogram) ToPrometheusMetric Uses

func (h *Histogram) ToPrometheusMetric() *prometheusgo.Metric

ToPrometheusMetric returns a filled-in prometheus metric of the right type.

type Histograms Uses

type Histograms map[TimeScale]*Histogram

Histograms is a map of Histogram metrics.

func NewLatency Uses

func NewLatency(metadata Metadata) Histograms

NewLatency 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 (Histograms) RecordValue Uses

func (hs Histograms) RecordValue(v int64)

RecordValue calls through to each individual Histogram.

type Iterable Uses

type Iterable interface {
    // GetName returns the fully-qualified name of the metric.
    GetName() string
    // GetHelp returns the help text for the metric.
    GetHelp() string
    // Inspect calls the given closure with each contained item.
    Inspect(func(interface{}))
}

Iterable provides a method for synchronized access to interior objects.

type Metadata Uses

type Metadata struct {
    Name, Help string
    // contains filtered or unexported fields
}

Metadata holds metadata about a metric. It must be embedded in each metric object.

func (*Metadata) AddLabel Uses

func (m *Metadata) AddLabel(name, value string)

AddLabel adds a label/value pair for this metric.

func (*Metadata) GetHelp Uses

func (m *Metadata) GetHelp() string

GetHelp returns the metric's help string.

func (*Metadata) GetLabels Uses

func (m *Metadata) GetLabels() []*prometheusgo.LabelPair

GetLabels returns the metric's labels.

func (*Metadata) GetName Uses

func (m *Metadata) GetName() string

GetName returns the metric's name.

type PrometheusExportable Uses

type PrometheusExportable interface {
    // GetName is a method on Metadata
    GetName() string
    // GetHelp is a method on Metadata
    GetHelp() string
    // GetType returns the prometheus type enum for this metric.
    GetType() *prometheusgo.MetricType
    // GetLabels is a method on Metadata
    GetLabels() []*prometheusgo.LabelPair
    // ToPrometheusMetric returns a filled-in prometheus metric of the right type
    // for the given metric. It does not fill in labels.
    ToPrometheusMetric() *prometheusgo.Metric
}

PrometheusExportable is the standard interface for an individual metric that can be exported to prometheus.

type PrometheusExporter Uses

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

PrometheusExporter contains a map of metric families (a metric with multiple labels). It initializes each metric family once and reuses it for each prometheus scrape. It is NOT thread-safe. TODO(marc): we should really keep out metric objects here so we can avoid creating new prometheus.Metric every time we are scraped. see: https://github.com/cockroachdb/cockroach/issues/9326

pe := MakePrometheusExporter()
pe.AddMetricsFromRegistry(nodeRegistry)
pe.AddMetricsFromRegistry(storeOneRegistry)
...
pe.AddMetricsFromRegistry(storeNRegistry)
pe.Export(w)

func MakePrometheusExporter Uses

func MakePrometheusExporter() PrometheusExporter

MakePrometheusExporter returns an initialized prometheus exporter.

func (*PrometheusExporter) AddMetricsFromRegistry Uses

func (pm *PrometheusExporter) AddMetricsFromRegistry(registry *Registry)

AddMetricsFromRegistry takes a registry and adds all metrics to the metric family map. It creates a new family if needed.

func (*PrometheusExporter) Export Uses

func (pm *PrometheusExporter) Export(w io.Writer) error

Export writes all metrics in the families map to the iowriter in prometheus' text format. It removes individual metrics from the families as it goes, readying the families for another found of registry additions.

type Rate Uses

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

A Rate is a exponential weighted moving average.

func NewRate Uses

func NewRate(metadata Metadata, 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 Uses

func (e *Rate) Add(v float64)

Add adds the given measurement to the Rate.

func (*Rate) Inspect Uses

func (e *Rate) Inspect(f func(interface{}))

Inspect 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 Uses

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

MarshalJSON marshals to JSON.

func (*Rate) Value Uses

func (e *Rate) Value() float64

Value returns the current value of the Rate.

type Rates Uses

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

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

func NewRates Uses

func NewRates(metadata Metadata) Rates

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

func (Rates) Add Uses

func (es Rates) Add(v int64)

Add adds the given value to all contained objects.

type Registry Uses

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

A Registry is a list of metrics. It provides a simple way of iterating over them, can marshal into JSON, and generate a prometheus format.

A registry can have label pairs that will be applied to all its metrics when exported to prometheus.

func NewRegistry Uses

func NewRegistry() *Registry

NewRegistry creates a new Registry.

func (*Registry) AddLabel Uses

func (r *Registry) AddLabel(name, value string)

AddLabel adds a label/value pair for this registry.

func (*Registry) AddMetric Uses

func (r *Registry) AddMetric(metric Iterable)

AddMetric adds the passed-in metric to the registry.

func (*Registry) AddMetricGroup Uses

func (r *Registry) AddMetricGroup(group metricGroup)

AddMetricGroup expands the metric group and adds all of them as individual metrics to the registry.

func (*Registry) AddMetricStruct Uses

func (r *Registry) AddMetricStruct(metricStruct interface{})

AddMetricStruct examines all fields of metricStruct and adds all Iterable or metricGroup objects to the registry.

func (*Registry) Each Uses

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

Each calls the given closure for all metrics.

func (*Registry) MarshalJSON Uses

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

MarshalJSON marshals to JSON.

type TimeScale Uses

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

A TimeScale is a named duration.

func (TimeScale) Name Uses

func (ts TimeScale) Name() string

Name returns the name of the TimeScale.

Package metric imports 16 packages (graph). Updated 2017-03-14. Refresh now. Tools for package owners. This is an inactive package (no imports and no commits in at least two years).