base/frameworks/telemetry/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
  • 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_set
Type

function (gf: Telemetry::GaugeFamily, label_values: Telemetry::labels_vector, value: double) : bool

Set a Telemetry::Gauge to the given value through the Telemetry::GaugeFamily. This is a short-cut for Telemetry::gauge_set.

Parameters
  • gf – The gauge family to use.

  • label_values – The label values to use for the gauge.

  • value – The value to set the gauge to.

Returns

True if the gauge value was set successfully.

Telemetry::gauge_inc
Type

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

Increment a Telemetry::Gauge by amount.

Parameters
  • g – The gauge instance.

  • amount – The amount by which to increment the gauge.

Returns

True if the gauge was incremented successfully.

Telemetry::gauge_set
Type

function (g: Telemetry::Gauge, value: double) : bool

Helper to set a Telemetry::Gauge to the given value.

Parameters
  • g – The gauge instance.

  • value – The value to set the gauge to.

Returns

True if the gauge value was set successfully.

Telemetry::gauge_with
Type

function (gf: Telemetry::GaugeFamily, label_values: Telemetry::labels_vector &default = [] &optional) : Telemetry::Gauge

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

Telemetry::histogram_family_observe
Type

function (hf: Telemetry::HistogramFamily, label_values: Telemetry::labels_vector, measurement: double) : bool

Observe a measurement for a Telemetry::Histogram through the Telemetry::HistogramFamily. This is a short-cut for Telemetry::histogram_observe.

Parameters
  • hf – The histogram family to use.

  • label_values – The label values to use for the histogram.

  • measurement – The value for this observations.

Returns

True if measurement was observed successfully.

Telemetry::histogram_observe
Type

function (h: Telemetry::Histogram, measurement: double) : bool

Observe a measurement for a Telemetry::Histogram.

Parameters
  • h – The histogram instance.

  • measurement – The value for this observations.

Returns

True if measurement was observed successfully.

Telemetry::histogram_with
Type

function (hf: Telemetry::HistogramFamily, label_values: Telemetry::labels_vector &default = [] &optional) : Telemetry::Histogram

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

Telemetry::register_counter_family
Type

function (opts: Telemetry::MetricOpts) : Telemetry::CounterFamily

Register a counter family.

Telemetry::register_gauge_family
Type

function (opts: Telemetry::MetricOpts) : Telemetry::GaugeFamily

Register a gauge family.

Telemetry::register_histogram_family
Type

function (opts: Telemetry::MetricOpts) : Telemetry::HistogramFamily

Register a histogram family.