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 Broker::metrics_port or using the BROKER_METRICS_PORT environment variable.

Namespace: Telemetry
Imports: 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::HistogramMetric`: `record`	Type of elements returned by the `Telemetry::collect_histogram_metrics` function.
`Telemetry::Metric`: `record`	Type of elements returned by the `Telemetry::collect_metrics` function.
`Telemetry::MetricOpts`: `record`	Type that captures options used to create metrics.
`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 dbl_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 dbl_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 dbl_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 dbl_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 dbl_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 dbl_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::HistogramMetric 

Type

record

opts: Telemetry::MetricOpts: A Telemetry::MetricOpts record describing this histogram.
labels: vector of string: The label values associated with this histogram, if any.
values: vector of double: Individual counters for each of the buckets as described by the bounds field in opts;
count_values: vector of count &optional: If the underlying data type of the histogram is int64_t, this vector will hold the values as counts, otherwise it is unset. Only histograms created with the C++ API have may have this value set.
observations: double: The number of observations made for this histogram.
sum: double: The sum of all observations for this histogram.
count_observations: count &optional: If the underlying data type of the histogram is int64_t, the number of observations as count, otherwise unset.
count_sum: count &optional: If the underlying data type of the histogram is int64_t, the sum of all observations as count, otherwise unset.

Type of elements returned by the Telemetry::collect_histogram_metrics function.

Telemetry::Metric 

Type

record

opts: Telemetry::MetricOpts: A Telemetry::MetricOpts record describing this metric.
labels: vector of string: The label values associated with this metric, if any.
value: double &optional: The value of gauge or counter cast to a double independent of the underlying data type. This value is set for all counter and gauge metrics, it is unset for histograms.
count_value: count &optional: The value of the underlying gauge or counter as a double if the underlying metric type uses int64_t. Only counters and gauges created with the C++ API may have this value set.

Type of elements returned by the Telemetry::collect_metrics function.

Telemetry::MetricOpts 

Type

record

prefix: string: The prefix (namespace) of the metric.
name: string: The human-readable name of the metric.
unit: string: The unit of the metric. Use the pseudo-unit “1” if this is a unit-less metric.
help_text: string: Documentation for this metric.
labels: vector of string &default = [] &optional: The label names (also called dimensions) of the metric. When instantiating or working with concrete metrics, corresponding label values have to be provided.
is_total: bool &optional: Whether the metric represents something that is accumulating. Defaults to T for counters and F for gauges and histograms.
bounds: vector of double &optional: When creating a Telemetry::HistogramFamily, describes the number and bounds of the individual buckets.
count_bounds: vector of count &optional: The same meaning as bounds, but as count. Only set in the return value of Telemetry::collect_histogram_metrics. for histograms when the underlying type is int64_t, otherwise ignored.
metric_type: Telemetry::MetricType &optional: Describes the underlying metric type. Only set in the return value of Telemetry::collect_metrics or Telemetry::collect_histogram_metrics, otherwise ignored.

Type that captures options used to create metrics.

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