:tocdepth: 3 base/frameworks/telemetry/main.zeek =================================== .. zeek:namespace:: 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 :zeek:see:`Telemetry::metrics_port`. :Namespace: Telemetry :Imports: :doc:`base/bif/telemetry_functions.bif.zeek `, :doc:`base/misc/version.zeek ` Summary ~~~~~~~ Types ##### ============================================================ ========================================================================= :zeek:type:`Telemetry::Counter`: :zeek:type:`record` Type representing a counter metric with initialized label values. :zeek:type:`Telemetry::CounterFamily`: :zeek:type:`record` Type representing a family of counters with uninitialized label values. :zeek:type:`Telemetry::Gauge`: :zeek:type:`record` Type representing a gauge metric with initialized label values. :zeek:type:`Telemetry::GaugeFamily`: :zeek:type:`record` Type representing a family of gauges with uninitialized label values. :zeek:type:`Telemetry::Histogram`: :zeek:type:`record` Type representing a histogram metric with initialized label values. :zeek:type:`Telemetry::HistogramFamily`: :zeek:type:`record` Type representing a family of histograms with uninitialized label values. :zeek:type:`Telemetry::labels_vector`: :zeek:type:`vector` Alias for a vector of label values. ============================================================ ========================================================================= Functions ######### ====================================================================== ============================================================================================ :zeek:id:`Telemetry::collect_histogram_metrics`: :zeek:type:`function` Collect all histograms and their observations matching the given *prefix* and *name*. :zeek:id:`Telemetry::collect_metrics`: :zeek:type:`function` Collect all counter and gauge metrics matching the given *name* and *prefix*. :zeek:id:`Telemetry::counter_family_inc`: :zeek:type:`function` Increment a :zeek:see:`Telemetry::Counter` through the :zeek:see:`Telemetry::CounterFamily`. :zeek:id:`Telemetry::counter_family_set`: :zeek:type:`function` Set a :zeek:see:`Telemetry::Counter` through the :zeek:see:`Telemetry::CounterFamily`. :zeek:id:`Telemetry::counter_inc`: :zeek:type:`function` Increment a :zeek:see:`Telemetry::Counter` by ``amount``. :zeek:id:`Telemetry::counter_set`: :zeek:type:`function` Helper to set a :zeek:see:`Telemetry::Counter` to the given ``value``. :zeek:id:`Telemetry::counter_with`: :zeek:type:`function` Get a :zeek:see:`Telemetry::Counter` instance given family and label values. :zeek:id:`Telemetry::gauge_dec`: :zeek:type:`function` Decrement a :zeek:see:`Telemetry::Gauge` by ``amount``. :zeek:id:`Telemetry::gauge_family_dec`: :zeek:type:`function` Decrement a :zeek:see:`Telemetry::Gauge` by the given ``amount`` through the :zeek:see:`Telemetry::GaugeFamily`. :zeek:id:`Telemetry::gauge_family_inc`: :zeek:type:`function` Increment a :zeek:see:`Telemetry::Gauge` by the given ``amount`` through the :zeek:see:`Telemetry::GaugeFamily`. :zeek:id:`Telemetry::gauge_family_set`: :zeek:type:`function` Set a :zeek:see:`Telemetry::Gauge` to the given ``value`` through the :zeek:see:`Telemetry::GaugeFamily`. :zeek:id:`Telemetry::gauge_inc`: :zeek:type:`function` Increment a :zeek:see:`Telemetry::Gauge` by ``amount``. :zeek:id:`Telemetry::gauge_set`: :zeek:type:`function` Helper to set a :zeek:see:`Telemetry::Gauge` to the given ``value``. :zeek:id:`Telemetry::gauge_with`: :zeek:type:`function` Get a :zeek:see:`Telemetry::Gauge` instance given family and label values. :zeek:id:`Telemetry::histogram_family_observe`: :zeek:type:`function` Observe a measurement for a :zeek:see:`Telemetry::Histogram` through the :zeek:see:`Telemetry::HistogramFamily`. :zeek:id:`Telemetry::histogram_observe`: :zeek:type:`function` Observe a measurement for a :zeek:see:`Telemetry::Histogram`. :zeek:id:`Telemetry::histogram_with`: :zeek:type:`function` Get a :zeek:see:`Telemetry::Histogram` instance given family and label values. :zeek:id:`Telemetry::register_counter_family`: :zeek:type:`function` Register a counter family. :zeek:id:`Telemetry::register_gauge_family`: :zeek:type:`function` Register a gauge family. :zeek:id:`Telemetry::register_histogram_family`: :zeek:type:`function` Register a histogram family. ====================================================================== ============================================================================================ Detailed Interface ~~~~~~~~~~~~~~~~~~ Types ##### .. zeek:type:: Telemetry::Counter :source-code: base/frameworks/telemetry/main.zeek 34 36 :Type: :zeek:type:`record` .. zeek:field:: __metric :zeek:type:`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 :zeek:see:`Telemetry::counter_inc` or :zeek:see:`Telemetry::counter_set` to modify counters. An example for a counter is the number of log writes per :zeek:see:`Log::Stream` or number connections broken down by protocol and service. .. zeek:type:: Telemetry::CounterFamily :source-code: base/frameworks/telemetry/main.zeek 21 24 :Type: :zeek:type:`record` .. zeek:field:: __family :zeek:type:`opaque` of counter_metric_family .. zeek:field:: __labels :zeek:type:`vector` of :zeek:type:`string` Type representing a family of counters with uninitialized label values. To create concrete :zeek:see:`Telemetry::Counter` instances, use :zeek:see:`Telemetry::counter_with`. To modify counters directly use :zeek:see:`Telemetry::counter_family_inc`. .. zeek:type:: Telemetry::Gauge :source-code: base/frameworks/telemetry/main.zeek 117 119 :Type: :zeek:type:`record` .. zeek:field:: __metric :zeek:type:`opaque` of gauge_metric Type representing a gauge metric with initialized label values. Use :zeek:see:`Telemetry::gauge_inc`, :zeek:see:`Telemetry::gauge_dec`, or :zeek:see:`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 :zeek:see:`val_footprint`. .. zeek:type:: Telemetry::GaugeFamily :source-code: base/frameworks/telemetry/main.zeek 105 108 :Type: :zeek:type:`record` .. zeek:field:: __family :zeek:type:`opaque` of gauge_metric_family .. zeek:field:: __labels :zeek:type:`vector` of :zeek:type:`string` Type representing a family of gauges with uninitialized label values. Create concrete :zeek:see:`Telemetry::Gauge` instances with :zeek:see:`Telemetry::gauge_with`, or use :zeek:see:`Telemetry::gauge_family_inc` or :zeek:see:`Telemetry::gauge_family_set` directly. .. zeek:type:: Telemetry::Histogram :source-code: base/frameworks/telemetry/main.zeek 213 215 :Type: :zeek:type:`record` .. zeek:field:: __metric :zeek:type:`opaque` of histogram_metric Type representing a histogram metric with initialized label values. Use :zeek:see:`Telemetry::histogram_observe` to make observations. .. zeek:type:: Telemetry::HistogramFamily :source-code: base/frameworks/telemetry/main.zeek 206 209 :Type: :zeek:type:`record` .. zeek:field:: __family :zeek:type:`opaque` of histogram_metric_family .. zeek:field:: __labels :zeek:type:`vector` of :zeek:type:`string` Type representing a family of histograms with uninitialized label values. Create concrete :zeek:see:`Telemetry::Histogram` instances with :zeek:see:`Telemetry::histogram_with` or use :zeek:see:`Telemetry::histogram_family_observe` directly. .. zeek:type:: Telemetry::labels_vector :source-code: base/frameworks/telemetry/main.zeek 14 14 :Type: :zeek:type:`vector` of :zeek:type:`string` Alias for a vector of label values. Functions ######### .. zeek:id:: Telemetry::collect_histogram_metrics :source-code: base/frameworks/telemetry/main.zeek 453 456 :Type: :zeek:type:`function` (prefix: :zeek:type:`string` :zeek:attr:`&default` = ``"*"`` :zeek:attr:`&optional`, name: :zeek:type:`string` :zeek:attr:`&default` = ``"*"`` :zeek:attr:`&optional`) : :zeek:type:`vector` of :zeek:type:`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. .. zeek:id:: Telemetry::collect_metrics :source-code: base/frameworks/telemetry/main.zeek 448 451 :Type: :zeek:type:`function` (prefix: :zeek:type:`string` :zeek:attr:`&default` = ``"*"`` :zeek:attr:`&optional`, name: :zeek:type:`string` :zeek:attr:`&default` = ``"*"`` :zeek:attr:`&optional`) : :zeek:type:`vector` of :zeek:type:`Telemetry::Metric` Collect all counter and gauge metrics matching the given *name* and *prefix*. For histogram metrics, use the :zeek:see:`Telemetry::collect_histogram_metrics`. The *prefix* and *name* parameters support globbing. By default, all counters and gauges are returned. .. zeek:id:: Telemetry::counter_family_inc :source-code: base/frameworks/telemetry/main.zeek 325 328 :Type: :zeek:type:`function` (cf: :zeek:type:`Telemetry::CounterFamily`, label_values: :zeek:type:`Telemetry::labels_vector` :zeek:attr:`&default` = ``[]`` :zeek:attr:`&optional`, amount: :zeek:type:`double` :zeek:attr:`&default` = ``1.0`` :zeek:attr:`&optional`) : :zeek:type:`bool` Increment a :zeek:see:`Telemetry::Counter` through the :zeek:see:`Telemetry::CounterFamily`. This is a short-cut for :zeek:see:`Telemetry::counter_inc`. Using a negative amount is an error. :param cf: The counter family to use. :param label_values: The label values to use for the counter. :param amount: The amount by which to increment the counter. :returns: True if the counter was incremented successfully. .. zeek:id:: Telemetry::counter_family_set :source-code: base/frameworks/telemetry/main.zeek 330 333 :Type: :zeek:type:`function` (cf: :zeek:type:`Telemetry::CounterFamily`, label_values: :zeek:type:`Telemetry::labels_vector`, value: :zeek:type:`double`) : :zeek:type:`bool` Set a :zeek:see:`Telemetry::Counter` through the :zeek:see:`Telemetry::CounterFamily`. This is a short-cut for :zeek:see:`Telemetry::counter_set`. Setting a value that is less than the current value of the metric is an error and will be ignored. :param cf: The counter family to use. :param label_values: The label values to use for the counter. :param value: The value to set the counter to. :returns: True if the counter value was set successfully. .. zeek:id:: Telemetry::counter_inc :source-code: base/frameworks/telemetry/main.zeek 309 312 :Type: :zeek:type:`function` (c: :zeek:type:`Telemetry::Counter`, amount: :zeek:type:`double` :zeek:attr:`&default` = ``1.0`` :zeek:attr:`&optional`) : :zeek:type:`bool` Increment a :zeek:see:`Telemetry::Counter` by ``amount``. Using a negative ``amount`` is an error. :param c: The counter instance. :param amount: The amount by which to increment the counter. :returns: True if the counter was incremented successfully. .. zeek:id:: Telemetry::counter_set :source-code: base/frameworks/telemetry/main.zeek 314 323 :Type: :zeek:type:`function` (c: :zeek:type:`Telemetry::Counter`, value: :zeek:type:`double`) : :zeek:type:`bool` Helper to set a :zeek:see:`Telemetry::Counter` to the given ``value``. This can be useful for mirroring counter metrics in an :zeek:see:`Telemetry::sync` hook implementation. Setting a value that is less than the current value of the metric is an error and will be ignored. :param c: The counter instance. :param value: The value to set the counter to. :returns: True if the counter value was set successfully. .. zeek:id:: Telemetry::counter_with :source-code: base/frameworks/telemetry/main.zeek 296 307 :Type: :zeek:type:`function` (cf: :zeek:type:`Telemetry::CounterFamily`, label_values: :zeek:type:`Telemetry::labels_vector` :zeek:attr:`&default` = ``[]`` :zeek:attr:`&optional`) : :zeek:type:`Telemetry::Counter` Get a :zeek:see:`Telemetry::Counter` instance given family and label values. .. zeek:id:: Telemetry::gauge_dec :source-code: base/frameworks/telemetry/main.zeek 372 375 :Type: :zeek:type:`function` (g: :zeek:type:`Telemetry::Gauge`, amount: :zeek:type:`double` :zeek:attr:`&default` = ``1.0`` :zeek:attr:`&optional`) : :zeek:type:`bool` Decrement a :zeek:see:`Telemetry::Gauge` by ``amount``. :param g: The gauge instance. :param amount: The amount by which to decrement the gauge. :returns: True if the gauge was incremented successfully. .. zeek:id:: Telemetry::gauge_family_dec :source-code: base/frameworks/telemetry/main.zeek 393 396 :Type: :zeek:type:`function` (gf: :zeek:type:`Telemetry::GaugeFamily`, label_values: :zeek:type:`Telemetry::labels_vector` :zeek:attr:`&default` = ``[]`` :zeek:attr:`&optional`, value: :zeek:type:`double` :zeek:attr:`&default` = ``1.0`` :zeek:attr:`&optional`) : :zeek:type:`bool` Decrement a :zeek:see:`Telemetry::Gauge` by the given ``amount`` through the :zeek:see:`Telemetry::GaugeFamily`. This is a short-cut for :zeek:see:`Telemetry::gauge_dec`. :param gf: The gauge family to use. :param label_values: The label values to use for the gauge. :param amount: The amount by which to increment the gauge. :returns: True if the gauge was incremented successfully. .. zeek:id:: Telemetry::gauge_family_inc :source-code: base/frameworks/telemetry/main.zeek 388 391 :Type: :zeek:type:`function` (gf: :zeek:type:`Telemetry::GaugeFamily`, label_values: :zeek:type:`Telemetry::labels_vector` :zeek:attr:`&default` = ``[]`` :zeek:attr:`&optional`, value: :zeek:type:`double` :zeek:attr:`&default` = ``1.0`` :zeek:attr:`&optional`) : :zeek:type:`bool` Increment a :zeek:see:`Telemetry::Gauge` by the given ``amount`` through the :zeek:see:`Telemetry::GaugeFamily`. This is a short-cut for :zeek:see:`Telemetry::gauge_inc`. Using a negative amount is an error. :param gf: The gauge family to use. :param label_values: The label values to use for the gauge. :param amount: The amount by which to increment the gauge. :returns: True if the gauge was incremented successfully. .. zeek:id:: Telemetry::gauge_family_set :source-code: base/frameworks/telemetry/main.zeek 398 401 :Type: :zeek:type:`function` (gf: :zeek:type:`Telemetry::GaugeFamily`, label_values: :zeek:type:`Telemetry::labels_vector`, value: :zeek:type:`double`) : :zeek:type:`bool` Set a :zeek:see:`Telemetry::Gauge` to the given ``value`` through the :zeek:see:`Telemetry::GaugeFamily`. This is a short-cut for :zeek:see:`Telemetry::gauge_set`. :param gf: The gauge family to use. :param label_values: The label values to use for the gauge. :param value: The value to set the gauge to. :returns: True if the gauge value was set successfully. .. zeek:id:: Telemetry::gauge_inc :source-code: base/frameworks/telemetry/main.zeek 367 370 :Type: :zeek:type:`function` (g: :zeek:type:`Telemetry::Gauge`, amount: :zeek:type:`double` :zeek:attr:`&default` = ``1.0`` :zeek:attr:`&optional`) : :zeek:type:`bool` Increment a :zeek:see:`Telemetry::Gauge` by ``amount``. :param g: The gauge instance. :param amount: The amount by which to increment the gauge. :returns: True if the gauge was incremented successfully. .. zeek:id:: Telemetry::gauge_set :source-code: base/frameworks/telemetry/main.zeek 377 386 :Type: :zeek:type:`function` (g: :zeek:type:`Telemetry::Gauge`, value: :zeek:type:`double`) : :zeek:type:`bool` Helper to set a :zeek:see:`Telemetry::Gauge` to the given ``value``. :param g: The gauge instance. :param value: The value to set the gauge to. :returns: True if the gauge value was set successfully. .. zeek:id:: Telemetry::gauge_with :source-code: base/frameworks/telemetry/main.zeek 355 365 :Type: :zeek:type:`function` (gf: :zeek:type:`Telemetry::GaugeFamily`, label_values: :zeek:type:`Telemetry::labels_vector` :zeek:attr:`&default` = ``[]`` :zeek:attr:`&optional`) : :zeek:type:`Telemetry::Gauge` Get a :zeek:see:`Telemetry::Gauge` instance given family and label values. .. zeek:id:: Telemetry::histogram_family_observe :source-code: base/frameworks/telemetry/main.zeek 443 446 :Type: :zeek:type:`function` (hf: :zeek:type:`Telemetry::HistogramFamily`, label_values: :zeek:type:`Telemetry::labels_vector`, measurement: :zeek:type:`double`) : :zeek:type:`bool` Observe a measurement for a :zeek:see:`Telemetry::Histogram` through the :zeek:see:`Telemetry::HistogramFamily`. This is a short-cut for :zeek:see:`Telemetry::histogram_observe`. :param hf: The histogram family to use. :param label_values: The label values to use for the histogram. :param measurement: The value for this observations. :returns: True if measurement was observed successfully. .. zeek:id:: Telemetry::histogram_observe :source-code: base/frameworks/telemetry/main.zeek 438 441 :Type: :zeek:type:`function` (h: :zeek:type:`Telemetry::Histogram`, measurement: :zeek:type:`double`) : :zeek:type:`bool` Observe a measurement for a :zeek:see:`Telemetry::Histogram`. :param h: The histogram instance. :param measurement: The value for this observations. :returns: True if measurement was observed successfully. .. zeek:id:: Telemetry::histogram_with :source-code: base/frameworks/telemetry/main.zeek 425 436 :Type: :zeek:type:`function` (hf: :zeek:type:`Telemetry::HistogramFamily`, label_values: :zeek:type:`Telemetry::labels_vector` :zeek:attr:`&default` = ``[]`` :zeek:attr:`&optional`) : :zeek:type:`Telemetry::Histogram` Get a :zeek:see:`Telemetry::Histogram` instance given family and label values. .. zeek:id:: Telemetry::register_counter_family :source-code: base/frameworks/telemetry/main.zeek 276 286 :Type: :zeek:type:`function` (opts: :zeek:type:`Telemetry::MetricOpts`) : :zeek:type:`Telemetry::CounterFamily` Register a counter family. .. zeek:id:: Telemetry::register_gauge_family :source-code: base/frameworks/telemetry/main.zeek 335 345 :Type: :zeek:type:`function` (opts: :zeek:type:`Telemetry::MetricOpts`) : :zeek:type:`Telemetry::GaugeFamily` Register a gauge family. .. zeek:id:: Telemetry::register_histogram_family :source-code: base/frameworks/telemetry/main.zeek 403 414 :Type: :zeek:type:`function` (opts: :zeek:type:`Telemetry::MetricOpts`) : :zeek:type:`Telemetry::HistogramFamily` Register a histogram family.