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: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 ¶
- Constants
- Variables
- func TestingSetNow(f func() time.Time) func()
- type Counter
- type CounterWithRates
- type Gauge
- func (g *Gauge) Dec(i int64)
- func (g *Gauge) GetType() *prometheusgo.MetricType
- func (g *Gauge) Inc(i int64)
- func (g *Gauge) Inspect(f func(interface{}))
- func (g *Gauge) MarshalJSON() ([]byte, error)
- func (g *Gauge) Snapshot() metrics.Gauge
- func (g *Gauge) ToPrometheusMetric() *prometheusgo.Metric
- func (g *Gauge) Update(v int64)
- func (g *Gauge) Value() int64
- type GaugeFloat64
- type Histogram
- func (h *Histogram) GetType() *prometheusgo.MetricType
- func (h *Histogram) Inspect(f func(interface{}))
- func (h *Histogram) Min() int64
- func (h *Histogram) RecordValue(v int64)
- func (h *Histogram) Snapshot() *hdrhistogram.Histogram
- func (h *Histogram) ToPrometheusMetric() *prometheusgo.Metric
- func (h *Histogram) TotalCount() int64
- func (h *Histogram) Windowed() (*hdrhistogram.Histogram, time.Duration)
- type Iterable
- type Metadata
- type PrometheusExportable
- type PrometheusExporter
- type Rate
- type Registry
- type Struct
- type TimeScale
Constants ¶
const ( // MaxLatency is the maximum value tracked in latency histograms. Higher // values will be recorded as this value instead. MaxLatency = 10 * time.Second // TestSampleInterval is passed to histograms during tests which don't // want to concern themselves with supplying a "correct" interval. TestSampleInterval = time.Duration(math.MaxInt64) )
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 Rates).
Functions ¶
func TestingSetNow ¶
TestingSetNow changes the clock used by the metric system. For use by testing to precisely control the clock.
Types ¶
type Counter ¶
type Counter struct {
Metadata
metrics.Counter
}
A Counter holds a single mutable atomic value.
func (*Counter) GetType ¶
func (c *Counter) GetType() *prometheusgo.MetricType
GetType returns the prometheus type enum for this metric.
func (*Counter) Inspect ¶
func (c *Counter) Inspect(f func(interface{}))
Inspect calls the given closure with the empty string and itself.
func (*Counter) MarshalJSON ¶
MarshalJSON marshals to JSON.
func (*Counter) ToPrometheusMetric ¶
func (c *Counter) ToPrometheusMetric() *prometheusgo.Metric
ToPrometheusMetric returns a filled-in prometheus metric of the right type.
type CounterWithRates ¶
CounterWithRates is a counter and associated EWMA backed rates at different time scales (which are ignored when visiting the object, and are thus not exported).
func NewCounterWithRates ¶
func NewCounterWithRates(metadata Metadata) *CounterWithRates
NewCounterWithRates registers and returns a new Counter along with some a set of EWMA-based rates at time scales specified by DefaultTimeScales. These rates are provided for convenience and are not exported to metrics frameworks. If they are not required, a Counter should be used instead.
type Gauge ¶
type Gauge struct {
Metadata
// contains filtered or unexported fields
}
A Gauge atomically stores a single integer value.
func NewFunctionalGauge ¶
NewFunctionalGauge creates a Gauge metric whose value is determined when asked for by calling the provided function. Note that Update, Inc, and Dec should NOT be called on a Gauge returned from NewFunctionalGauge.
func (*Gauge) GetType ¶
func (g *Gauge) GetType() *prometheusgo.MetricType
GetType returns the prometheus type enum for this metric.
func (*Gauge) Inspect ¶
func (g *Gauge) Inspect(f func(interface{}))
Inspect calls the given closure with the empty string and itself.
func (*Gauge) MarshalJSON ¶
MarshalJSON marshals to JSON.
func (*Gauge) Snapshot ¶
func (g *Gauge) Snapshot() metrics.Gauge
Snapshot returns a read-only copy of the gauge.
func (*Gauge) ToPrometheusMetric ¶
func (g *Gauge) ToPrometheusMetric() *prometheusgo.Metric
ToPrometheusMetric returns a filled-in prometheus metric of the right type.
type GaugeFloat64 ¶
type GaugeFloat64 struct {
Metadata
metrics.GaugeFloat64
}
A GaugeFloat64 atomically stores a single float64 value.
func NewGaugeFloat64 ¶
func NewGaugeFloat64(metadata Metadata) *GaugeFloat64
NewGaugeFloat64 creates a GaugeFloat64.
func (*GaugeFloat64) GetType ¶
func (g *GaugeFloat64) GetType() *prometheusgo.MetricType
GetType returns the prometheus type enum for this metric.
func (*GaugeFloat64) Inspect ¶
func (g *GaugeFloat64) Inspect(f func(interface{}))
Inspect calls the given closure with the empty string and itself.
func (*GaugeFloat64) MarshalJSON ¶
func (g *GaugeFloat64) MarshalJSON() ([]byte, error)
MarshalJSON marshals to JSON.
func (*GaugeFloat64) ToPrometheusMetric ¶
func (g *GaugeFloat64) ToPrometheusMetric() *prometheusgo.Metric
ToPrometheusMetric returns a filled-in prometheus metric of the right type.
type Histogram ¶
type Histogram struct {
Metadata
// contains filtered or unexported fields
}
A Histogram collects observed values by keeping bucketed counts. For convenience, internally two sets of buckets are kept: A cumulative set (i.e. data is never evicted) and a windowed set (which keeps only recently collected samples).
Top-level methods generally apply to the cumulative buckets; the windowed variant is exposed through the Windowed method.
func NewHistogram ¶
NewHistogram initializes a given Histogram. The contained windowed histogram rotates every 'duration'; both the windowed and the cumulative histogram track nonnegative values up to 'maxVal' with 'sigFigs' decimal points of precision.
func NewLatency ¶
NewLatency is a convenience function which returns a histogram with suitable defaults for latency tracking. Values are expressed in ns, are truncated into the interval [0, MaxLatency] and are recorded with one digit of precision (i.e. errors of <10ms at 100ms, <6s at 60s).
The windowed portion of the Histogram retains values for approximately histogramWindow.
func (*Histogram) GetType ¶
func (h *Histogram) GetType() *prometheusgo.MetricType
GetType returns the prometheus type enum for this metric.
func (*Histogram) Inspect ¶
func (h *Histogram) Inspect(f func(interface{}))
Inspect calls the closure with the empty string and the receiver.
func (*Histogram) RecordValue ¶
RecordValue adds the given value to the histogram. Recording a value in excess of the configured maximum value for that histogram results in recording the maximum value instead.
func (*Histogram) Snapshot ¶
func (h *Histogram) Snapshot() *hdrhistogram.Histogram
Snapshot returns a copy of the cumulative (i.e. all-time samples) histogram data.
func (*Histogram) ToPrometheusMetric ¶
func (h *Histogram) ToPrometheusMetric() *prometheusgo.Metric
ToPrometheusMetric returns a filled-in prometheus metric of the right type.
func (*Histogram) TotalCount ¶
TotalCount returns the (cumulative) number of samples.
type Iterable ¶
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 ¶
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) GetLabels ¶
func (m *Metadata) GetLabels() []*prometheusgo.LabelPair
GetLabels returns the metric's labels.
type PrometheusExportable ¶
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.
// The implementation must return thread-safe data to the caller, i.e.
// usually a copy of internal state.
ToPrometheusMetric() *prometheusgo.Metric
}
PrometheusExportable is the standard interface for an individual metric that can be exported to prometheus.
type PrometheusExporter ¶
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 ¶
func MakePrometheusExporter() PrometheusExporter
MakePrometheusExporter returns an initialized prometheus exporter.
func (*PrometheusExporter) PrintAsText ¶
func (pm *PrometheusExporter) PrintAsText(w io.Writer) error
PrintAsText writes all metrics in the families map to the io.Writer in prometheus' text format. It removes individual metrics from the families as it goes, readying the families for another found of registry additions.
func (*PrometheusExporter) ScrapeRegistry ¶
func (pm *PrometheusExporter) ScrapeRegistry(registry *Registry)
ScrapeRegistry scrapes all metrics contained in the registry to the metric family map, holding on only to the scraped data (which is no longer connected to the registry and metrics within) when returning from the the call. It creates new families as needed.
type Rate ¶
type Rate struct {
// contains filtered or unexported fields
}
A Rate is a exponential weighted moving average.
type Registry ¶
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 (*Registry) AddMetricStruct ¶
func (r *Registry) AddMetricStruct(metricStruct interface{})
AddMetricStruct examines all fields of metricStruct and adds all Iterable or metricGroup objects to the registry.
func (*Registry) MarshalJSON ¶
MarshalJSON marshals to JSON.
Source Files