main.zeek

Telemetry

Module for recording and querying metrics. This modules wraps the lower-level telemetry.bif functions.

Metrics will be exposed through a Prometheus HTTP endpoint when enabled by setting Telemetry::metrics_port.

Namespace: Telemetry
Imports: base/frameworks/cluster, base/frameworks/telemetry/options.zeek, base/misc/version.zeek

Summary

Runtime Options

Telemetry::sync_interval: interval &redef

Interval at which the Telemetry::sync hook is invoked.

Types

`Telemetry::Counter`: `record`	Type representing a counter metric with initialized label values.
`Telemetry::CounterFamily`: `record`	Type representing a family of counters with uninitialized label values.
`Telemetry::Gauge`: `record`	Type representing a gauge metric with initialized label values.
`Telemetry::GaugeFamily`: `record`	Type representing a family of gauges with uninitialized label values.
`Telemetry::Histogram`: `record`	Type representing a histogram metric with initialized label values.
`Telemetry::HistogramFamily`: `record`	Type representing a family of histograms with uninitialized label values.
`Telemetry::labels_vector`: `vector`	Alias for a vector of label values.

Hooks

Telemetry::sync: hook

Telemetry sync hook.

Functions

`Telemetry::collect_histogram_metrics`: `function`	Collect all histograms and their observations matching the given prefix and name.
`Telemetry::collect_metrics`: `function`	Collect all counter and gauge metrics matching the given name and prefix.
`Telemetry::counter_family_inc`: `function`	Increment a `Telemetry::Counter` through the `Telemetry::CounterFamily`.
`Telemetry::counter_family_set`: `function`	Set a `Telemetry::Counter` through the `Telemetry::CounterFamily`.
`Telemetry::counter_inc`: `function`	Increment a `Telemetry::Counter` by amount.
`Telemetry::counter_set`: `function`	Helper to set a `Telemetry::Counter` to the given value.
`Telemetry::counter_with`: `function`	Get a `Telemetry::Counter` instance given family and label values.
`Telemetry::gauge_dec`: `function`	Decrement a `Telemetry::Gauge` by amount.
`Telemetry::gauge_family_dec`: `function`	Decrement a `Telemetry::Gauge` by the given amount through the `Telemetry::GaugeFamily`.
`Telemetry::gauge_family_inc`: `function`	Increment a `Telemetry::Gauge` by the given amount through the `Telemetry::GaugeFamily`.
`Telemetry::gauge_family_set`: `function`	Set a `Telemetry::Gauge` to the given value through the `Telemetry::GaugeFamily`.
`Telemetry::gauge_inc`: `function`	Increment a `Telemetry::Gauge` by amount.
`Telemetry::gauge_set`: `function`	Helper to set a `Telemetry::Gauge` to the given value.
`Telemetry::gauge_with`: `function`	Get a `Telemetry::Gauge` instance given family and label values.
`Telemetry::histogram_family_observe`: `function`	Observe a measurement for a `Telemetry::Histogram` through the `Telemetry::HistogramFamily`.
`Telemetry::histogram_observe`: `function`	Observe a measurement for a `Telemetry::Histogram`.
`Telemetry::histogram_with`: `function`	Get a `Telemetry::Histogram` instance given family and label values.
`Telemetry::register_counter_family`: `function`	Register a counter family.
`Telemetry::register_gauge_family`: `function`	Register a gauge family.
`Telemetry::register_histogram_family`: `function`	Register a histogram family.

Detailed Interface

Runtime Options

Telemetry::sync_interval 

Type: interval
Attributes: &redef
Default: 10.0 secs

Interval at which the Telemetry::sync hook is invoked.

Types

Telemetry::Counter 

Type

record

__metric: opaque of counter_metric

Type representing a counter metric with initialized label values.

Counter metrics only ever go up and reset when the process restarts. Use Telemetry::counter_inc or Telemetry::counter_set to modify counters. An example for a counter is the number of log writes per Log::Stream or number connections broken down by protocol and service.

Telemetry::CounterFamily 

Type

record

__family: opaque of counter_metric_family

__labels: vector of string

Type representing a family of counters with uninitialized label values.

To create concrete Telemetry::Counter instances, use Telemetry::counter_with. To modify counters directly use Telemetry::counter_family_inc.

Telemetry::Gauge 

Type

record

__metric: opaque of gauge_metric

Type representing a gauge metric with initialized label values.

Use Telemetry::gauge_inc, Telemetry::gauge_dec, or Telemetry::gauge_set to modify the gauge. Example for gauges are process memory usage, table sizes or footprints of long-lived values as determined by val_footprint.

Telemetry::GaugeFamily 

Type

record

__family: opaque of gauge_metric_family

__labels: vector of string

Type representing a family of gauges with uninitialized label values.

Create concrete Telemetry::Gauge instances with Telemetry::gauge_with, or use Telemetry::gauge_family_inc or Telemetry::gauge_family_set directly.

Telemetry::Histogram 

Type

record

__metric: opaque of histogram_metric

Type representing a histogram metric with initialized label values. Use Telemetry::histogram_observe to make observations.

Telemetry::HistogramFamily 

Type

record

__family: opaque of histogram_metric_family

__labels: vector of string

Type representing a family of histograms with uninitialized label values. Create concrete Telemetry::Histogram instances with Telemetry::histogram_with or use Telemetry::histogram_family_observe directly.

Telemetry::labels_vector 

Type: vector of string

Alias for a vector of label values.

Hooks

Telemetry::sync 

Type: hook () : bool

Telemetry sync hook.

This hook is invoked every Telemetry::sync_interval for script writers to synchronize or mirror metrics with the telemetry subsystem. For example, when tracking table or value footprints with gauges, the value in question can be set on an actual Telemetry::Gauge instance during execution of this hook.

Implementations should be lightweight, this hook may be called multiple times per minute. The interval can increased by changing Telemetry::sync_interval at the cost of delaying metric updates and thereby reducing granularity.

Functions

Telemetry::collect_histogram_metrics 

Type: function (prefix: string &default = "*" &optional, name: string &default = "*" &optional) : vector of Telemetry::HistogramMetric

Collect all histograms and their observations matching the given prefix and name.

The prefix and name parameters support globbing. By default, all histogram metrics are returned.

Telemetry::collect_metrics 

Type: function (prefix: string &default = "*" &optional, name: string &default = "*" &optional) : vector of Telemetry::Metric

Collect all counter and gauge metrics matching the given name and prefix.

For histogram metrics, use the Telemetry::collect_histogram_metrics.

The prefix and name parameters support globbing. By default, all counters and gauges are returned.

Telemetry::counter_family_inc 

Type: function (cf: Telemetry::CounterFamily, label_values: Telemetry::labels_vector &default = [] &optional, amount: double &default = 1.0 &optional) : bool

Increment a Telemetry::Counter through the Telemetry::CounterFamily. This is a short-cut for Telemetry::counter_inc. Using a negative amount is an error.

Parameters

cf – The counter family to use.
label_values – The label values to use for the counter.
amount – The amount by which to increment the counter.

Returns

True if the counter was incremented successfully.

Telemetry::counter_family_set 

Type: function (cf: Telemetry::CounterFamily, label_values: Telemetry::labels_vector, value: double) : bool

Set a Telemetry::Counter through the Telemetry::CounterFamily. This is a short-cut for Telemetry::counter_set. Setting a value that is less than the current value of the metric is an error and will be ignored.

Parameters

cf – The counter family to use.
label_values – The label values to use for the counter.
value – The value to set the counter to.

Returns

True if the counter value was set successfully.

Telemetry::counter_inc 

Type: function (c: Telemetry::Counter, amount: double &default = 1.0 &optional) : bool

Increment a Telemetry::Counter by amount. Using a negative amount is an error.

Parameters

c – The counter instance.
amount – The amount by which to increment the counter.

Returns

True if the counter was incremented successfully.

Telemetry::counter_set 

Type: function (c: Telemetry::Counter, value: double) : bool

Helper to set a Telemetry::Counter to the given value. This can be useful for mirroring counter metrics in an Telemetry::sync hook implementation. Setting a value that is less than the current value of the metric is an error and will be ignored.

Parameters

c – The counter instance.
value – The value to set the counter to.

Returns

True if the counter value was set successfully.

Telemetry::counter_with 

Type: function (cf: Telemetry::CounterFamily, label_values: Telemetry::labels_vector &default = [] &optional) : Telemetry::Counter

Get a Telemetry::Counter instance given family and label values.

Telemetry::gauge_dec 

Type: function (g: Telemetry::Gauge, amount: double &default = 1.0 &optional) : bool

Decrement a Telemetry::Gauge by amount.

Parameters

g – The gauge instance.
amount – The amount by which to decrement the gauge.

Returns

True if the gauge was incremented successfully.

Telemetry::gauge_family_dec 

Type: function (gf: Telemetry::GaugeFamily, label_values: Telemetry::labels_vector &default = [] &optional, value: double &default = 1.0 &optional) : bool

Decrement a Telemetry::Gauge by the given amount through the Telemetry::GaugeFamily. This is a short-cut for Telemetry::gauge_dec.

Parameters

gf – The gauge family to use.
label_values – The label values to use for the gauge.
amount – The amount by which to increment the gauge.

Returns

True if the gauge was incremented successfully.

Telemetry::gauge_family_inc 

Type: function (gf: Telemetry::GaugeFamily, label_values: Telemetry::labels_vector &default = [] &optional, value: double &default = 1.0 &optional) : bool

Increment a Telemetry::Gauge by the given amount through the Telemetry::GaugeFamily. This is a short-cut for Telemetry::gauge_inc. Using a negative amount is an error.

Parameters