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/bif/telemetry_functions.bif.zeek, base/misc/version.zeek

Summary

Runtime Options

Telemetry::sync_interval: interval &deprecated = … &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.

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:: &deprecated = “Remove in 8.1. If you require regular sync invocation, do so explicitly in a scheduled event.” &redef
Default:: 0 secs

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

By default, the hook is invoked on demand, setting this option to a positive interval allows to invoke it regularly, too. Regular invocations are relative to Zeek’s network time.

Note that on-demand hook invocation will happen even if this is set.

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.

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: