metric

package
v0.0.0-...-1dc08c0 Latest Latest
Warning

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

 Go to latest Published: Jun 17, 2021 License: Apache-2.0 Imports: 24 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: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

View Source 
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

View Source 
var (
	ErrInvalidLengthMetric = fmt.Errorf("proto: negative length found during unmarshaling")
	ErrIntOverflowMetric   = fmt.Errorf("proto: integer overflow")
)
View Source 
var Unit_name = map[int32]string{
	0: "UNSET",
	1: "BYTES",
	2: "CONST",
	3: "COUNT",
	4: "NANOSECONDS",
	5: "PERCENT",
	6: "SECONDS",
	7: "TIMESTAMP_NS",
	8: "TIMESTAMP_SEC",
}
View Source 
var Unit_value = map[string]int32{
	"UNSET":         0,
	"BYTES":         1,
	"CONST":         2,
	"COUNT":         3,
	"NANOSECONDS":   4,
	"PERCENT":       5,
	"SECONDS":       6,
	"TIMESTAMP_NS":  7,
	"TIMESTAMP_SEC": 8,
}

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 {
	Metadata
	metrics.Counter
}

A Counter holds a single mutable atomic value.

func NewCounter 

func NewCounter(metadata Metadata) *Counter

NewCounter creates a counter.

func (*Counter) Dec 

func (c *Counter) Dec(int64)

Dec overrides the metric.Counter method. This method should NOT be used and serves only to prevent misuse of the metric type.

func (*Counter) GetMetadata 

func (c *Counter) GetMetadata() Metadata

GetMetadata returns the metric's metadata including the Prometheus MetricType.

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 

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

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 Gauge 

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

A Gauge atomically stores a single integer value.

func NewFunctionalGauge 

func NewFunctionalGauge(metadata Metadata, f func() int64) *Gauge

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 NewGauge 

func NewGauge(metadata Metadata) *Gauge

NewGauge creates a Gauge.

func (*Gauge) Dec 

func (g *Gauge) Dec(i int64)

Dec decrements the gauge's value.

func (*Gauge) GetMetadata 

func (g *Gauge) GetMetadata() Metadata

GetMetadata returns the metric's metadata including the Prometheus MetricType.

func (*Gauge) GetType 

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

GetType returns the prometheus type enum for this metric.

func (*Gauge) Inc 

func (g *Gauge) Inc(i int64)

Inc increments the gauge's value.

func (*Gauge) Inspect 

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

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

func (*Gauge) MarshalJSON 

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

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.

func (*Gauge) Update 

func (g *Gauge) Update(v int64)

Update updates the gauge's value.

func (*Gauge) Value 

func (g *Gauge) Value() int64

Value returns the gauge's current value.

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) GetMetadata 

func (g *GaugeFloat64) GetMetadata() Metadata

GetMetadata returns the metric's metadata including the Prometheus MetricType.

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 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 GraphiteExporter 

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

GraphiteExporter scrapes PrometheusExporter for metrics and pushes them to a Graphite or Carbon server.

func MakeGraphiteExporter 

func MakeGraphiteExporter(pm *PrometheusExporter) GraphiteExporter

MakeGraphiteExporter returns an initialized graphite exporter.

func (*GraphiteExporter) Push 

func (ge *GraphiteExporter) Push(ctx context.Context, endpoint string) error

Push metrics scraped from registry to Graphite or Carbon server. It converts the same metrics that are pulled by Prometheus into Graphite-format.

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 

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

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 

func NewLatency(metadata Metadata, histogramWindow time.Duration) *Histogram

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) GetMetadata 

func (h *Histogram) GetMetadata() Metadata

GetMetadata returns the metric's metadata including the Prometheus MetricType.

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) Min 

func (h *Histogram) Min() int64

Min returns the minimum.

func (*Histogram) RecordValue 

func (h *Histogram) RecordValue(v int64)

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 

func (h *Histogram) TotalCount() int64

TotalCount returns the (cumulative) number of samples.

func (*Histogram) Windowed 

func (h *Histogram) Windowed() (*hdrhistogram.Histogram, time.Duration)

Windowed returns a copy of the current windowed histogram data and its rotation interval.

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
	// GetMeasurement returns the label for the metric, which describes the entity
	// it measures.
	GetMeasurement() string
	// GetUnit returns the unit that should be used to display the metric
	// (e.g. in bytes).
	GetUnit() Unit
	// GetMetadata returns the metric's metadata, which can be used in charts.
	GetMetadata() Metadata
	// Inspect calls the given closure with each contained item.
	Inspect(func(interface{}))
}

Iterable provides a method for synchronized access to interior objects.

type LabelPair 

type LabelPair struct {
	Name  *string `protobuf:"bytes,1,opt,name=name" json:"name,omitempty"`
	Value *string `protobuf:"bytes,2,opt,name=value" json:"value,omitempty"`
}

metric.LabelPair is a proxy for io.prometheus.client.LabelPair. io.prometheus.client.LabelPair doesn't support gogoproto.marshaler and gogoproto.unmarshaler which are required by gRPC. metric.LabelPair stores information that is similarly structured, supports the requisite gogoproto options, and is convertible to io.prometheus.client.LabelPair to satisfy PrometheusExportable's GetLabels method.

func (*LabelPair) Descriptor 

func (*LabelPair) Descriptor() ([]byte, []int)

func (*LabelPair) Marshal 

func (m *LabelPair) Marshal() (dAtA []byte, err error)

func (*LabelPair) MarshalTo 

func (m *LabelPair) MarshalTo(dAtA []byte) (int, error)

func (*LabelPair) ProtoMessage 

func (*LabelPair) ProtoMessage()

func (*LabelPair) Reset 

func (m *LabelPair) Reset()

func (*LabelPair) Size 

func (m *LabelPair) Size() (n int)

func (*LabelPair) String 

func (m *LabelPair) String() string

func (*LabelPair) Unmarshal 

func (m *LabelPair) Unmarshal(dAtA []byte) error

func (*LabelPair) XXX_DiscardUnknown 

func (m *LabelPair) XXX_DiscardUnknown()

func (*LabelPair) XXX_Marshal 

func (m *LabelPair) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*LabelPair) XXX_Merge 

func (m *LabelPair) XXX_Merge(src proto.Message)

func (*LabelPair) XXX_Size 

func (m *LabelPair) XXX_Size() int

func (*LabelPair) XXX_Unmarshal 

func (m *LabelPair) XXX_Unmarshal(b []byte) error

type Metadata 

type Metadata struct {
	Name        string         `protobuf:"bytes,1,req,name=name" json:"name"`
	Help        string         `protobuf:"bytes,2,req,name=help" json:"help"`
	Measurement string         `protobuf:"bytes,3,req,name=measurement" json:"measurement"`
	Unit        Unit           `protobuf:"varint,4,req,name=unit,enum=cockroach.util.metric.Unit" json:"unit"`
	MetricType  _go.MetricType `protobuf:"varint,5,opt,name=metricType,enum=io.prometheus.client.MetricType" json:"metricType"`
	Labels      []*LabelPair   `protobuf:"bytes,6,rep,name=labels" json:"labels,omitempty"`
}

Metadata holds metadata about a metric. It must be embedded in each metric object. It's used to export information about the metric to Prometheus and for Admin UI charts.

func (*Metadata) AddLabel 

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

AddLabel adds a label/value pair for this metric.

func (*Metadata) Descriptor 

func (*Metadata) Descriptor() ([]byte, []int)

func (*Metadata) GetHelp 

func (m *Metadata) GetHelp() string

GetHelp returns the metric's help string.

func (*Metadata) GetLabels 

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

GetLabels returns the metric's labels. For rationale behind the conversion from metric.LabelPair to prometheusgo.LabelPair, see the LabelPair comment in pkg/util/metric/metric.proto.

func (*Metadata) GetMeasurement 

func (m *Metadata) GetMeasurement() string

GetMeasurement returns the entity measured by the metric.

func (*Metadata) GetName 

func (m *Metadata) GetName() string

GetName returns the metric's name.

func (*Metadata) GetUnit 

func (m *Metadata) GetUnit() Unit

GetUnit returns the metric's unit of measurement.

func (*Metadata) Marshal 

func (m *Metadata) Marshal() (dAtA []byte, err error)

func (*Metadata) MarshalTo 

func (m *Metadata) MarshalTo(dAtA []byte) (int, error)

func (*Metadata) ProtoMessage 

func (*Metadata) ProtoMessage()

func (*Metadata) Reset 

func (m *Metadata) Reset()

func (*Metadata) Size 

func (m *Metadata) Size() (n int)

func (*Metadata) String 

func (m *Metadata) String() string

func (*Metadata) Unmarshal 

func (m *Metadata) Unmarshal(dAtA []byte) error

func (*Metadata) XXX_DiscardUnknown 

func (m *Metadata) XXX_DiscardUnknown()

func (*Metadata) XXX_Marshal 

func (m *Metadata) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*Metadata) XXX_Merge 

func (m *Metadata) XXX_Merge(src proto.Message)

func (*Metadata) XXX_Size 

func (m *Metadata) XXX_Size() int

func (*Metadata) XXX_Unmarshal 

func (m *Metadata) XXX_Unmarshal(b []byte) error

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 our metric objects here so we can avoid creating new prometheus.Metric every time we are scraped. see: https://github.com/ruiaylin/pgparser/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) Gather 

func (pm *PrometheusExporter) Gather() ([]*prometheusgo.MetricFamily, error)

Gather implements prometheus.Gatherer

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 PrometheusIterable 

type PrometheusIterable interface {
	PrometheusExportable

	// Each takes a slice of label pairs associated with the parent metric and
	// calls the passed function with each of the children metrics.
	Each([]*prometheusgo.LabelPair, func(metric *prometheusgo.Metric))
}

PrometheusIterable is an extension of PrometheusExportable to indicate that this metric is comprised of children metrics which augment the parent's label values.

The motivating use-case for this interface is the existence of tenants. We'd like to capture per-tenant metrics and expose them to prometheus while not polluting the internal tsdb.

type Rate 

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

A Rate is a exponential weighted moving average.

func NewRate 

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 

func (e *Rate) Add(v float64)

Add adds the given measurement to the Rate.

func (*Rate) GetMetadata 

func (e *Rate) GetMetadata() Metadata

GetMetadata returns the metric's metadata including the Prometheus MetricType.

func (*Rate) GetType 

func (e *Rate) GetType() *prometheusgo.MetricType

GetType returns the prometheus type enum for this metric.

func (*Rate) Inspect 

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

Inspect calls the given closure with itself.

func (*Rate) MarshalJSON 

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

MarshalJSON marshals to JSON.

func (*Rate) ToPrometheusMetric 

func (e *Rate) ToPrometheusMetric() *prometheusgo.Metric

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

func (*Rate) Value 

func (e *Rate) Value() float64

Value returns the current value of the Rate.

type Registry 

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 

func NewRegistry() *Registry

NewRegistry creates a new Registry.

func (*Registry) AddLabel 

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

AddLabel adds a label/value pair for this registry.

func (*Registry) AddMetric 

func (r *Registry) AddMetric(metric Iterable)

AddMetric adds the passed-in metric to the registry.

func (*Registry) AddMetricStruct 

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

AddMetricStruct examines all fields of metricStruct and adds all Iterable or metric.Struct objects 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) MarshalJSON 

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

MarshalJSON marshals to JSON.

func (*Registry) WriteMetricsMetadata 

func (r *Registry) WriteMetricsMetadata(dest map[string]Metadata)

WriteMetricsMetadata writes metadata from all tracked metrics to the parameter map.

type Struct 

type Struct interface {
	MetricStruct()
}

Struct can be implemented by the types of members of a metric container so that the members get automatically registered.

type Unit 

type Unit int32

DisplayUnit describes how the metric's units should be displayed in charts. 

const (
	// UNSET expresses that the metric's DisplayUnit wasn't explicitly set.
	Unit_UNSET Unit = 0
	// BYTES expresses that the metric's measurement is in bytes.
	Unit_BYTES Unit = 1
	// CONST expresses that the metric's measurement is a constant value.
	Unit_CONST Unit = 2
	// COUNT expresses that the metric's measurement is a count.
	Unit_COUNT Unit = 3
	// NANOSECONDS expresses that the metric's measurement is in nanoseconds.
	Unit_NANOSECONDS Unit = 4
	// PERCENT expresses that the metric's measurement is a percentage value.
	Unit_PERCENT Unit = 5
	// SECONDS expresses that the metric's measurement is in seconds.
	Unit_SECONDS Unit = 6
	// TIMESTAMP_NS expresses that the metric's measurement is a time since the
	// Unix epoch in nanoseconds.
	Unit_TIMESTAMP_NS Unit = 7
	// TIMESTAMP_SEC expresses that the metric's measurement is a time since the
	// Unix epoch in seconds.
	Unit_TIMESTAMP_SEC Unit = 8
)

func (Unit) Enum 

func (x Unit) Enum() *Unit

func (Unit) EnumDescriptor 

func (Unit) EnumDescriptor() ([]byte, []int)

func (Unit) String 

func (x Unit) String() string

func (*Unit) UnmarshalJSON 

func (x *Unit) UnmarshalJSON(data []byte) error

Source Files

View all Source files

Directories

Path Synopsis
Package aggmetric provides functionality to create metrics which expose aggregate metrics for internal collection and additionally per-child reporting to prometheus.
 Package aggmetric provides functionality to create metrics which expose aggregate metrics for internal collection and additionally per-child reporting to prometheus.

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.