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. For example:
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)
}
I recommend keeping a root-level registry (for CockroachDB, that's Server.registry) and creating a hierarchy of Registry instances underneath that to make your metrics more manageable.
Testing ¶
After your test does something to trigger your new metric update, you'll probably want to call methods in TestServer such as MustGetCounter() 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 "--dev" 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 ¶
- Variables
- type Counter
- type Gauge
- type Histogram
- type Histograms
- type Iterable
- type Rate
- type Rates
- type Registry
- func (r *Registry) Add(format string, item Iterable) error
- func (r *Registry) Counter(name string) *Counter
- func (r *Registry) Each(f func(name string, val interface{}))
- func (r *Registry) Gauge(name string) *Gauge
- func (r *Registry) Histogram(name string, duration time.Duration, maxVal int64, sigFigs int) *Histogram
- func (r *Registry) Latency(prefix string) Histograms
- func (r *Registry) MarshalJSON() ([]byte, error)
- func (r *Registry) MustAdd(format string, item Iterable)
- func (r *Registry) Rate(name string, timescale time.Duration) *Rate
- func (r *Registry) Rates(prefix string) Rates
- type TimeScale
Constants ¶
This section is empty.
Variables ¶
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 ¶
This section is empty.
Types ¶
type Counter ¶
type Counter struct {
metrics.Counter
}
A Counter holds a single mutable atomic value.
func (*Counter) MarshalJSON ¶
MarshalJSON marshals to JSON.
type Gauge ¶
type Gauge struct {
metrics.Gauge
}
A Gauge atomically stores a single value.
func (*Gauge) MarshalJSON ¶
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 ¶
NewHistogram creates a new windowed HDRHistogram with the given parameters. Data is kept in the active window for approximately the given duration. See the 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) MarshalJSON ¶
MarshalJSON outputs to JSON.
func (*Histogram) RecordValue ¶
RecordValue adds the given value to the histogram, truncating if necessary.
type Histograms ¶
type Histograms []*Histogram
Histograms is a slice 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 Rate ¶
type Rate struct {
// contains filtered or unexported fields
}
A Rate is a exponential weighted moving average.
func NewRate ¶
NewRate creates an EWMA rate on the given timescale. Timescales at or below 2s are illegal and will cause a panic.
func (*Rate) Each ¶
Each calls the given closure with the empty string and the Rate's current value.
func (*Rate) MarshalJSON ¶
MarshalJSON marshals to JSON.
type Registry ¶
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 (*Registry) Add ¶
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) 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 ¶
MarshalJSON marshals to JSON.
Source Files