From cc6d7208ed10b911397460405fda6c25f12d4e2b Mon Sep 17 00:00:00 2001 From: Tim Wojtulewicz Date: Thu, 16 May 2024 12:02:31 -0700 Subject: [PATCH] Update docs for telemetry after ZEEK_METRICS_ removal --- frameworks/telemetry.rst | 14 ---- scripts/base/bif/event.bif.zeek.rst | 2 +- scripts/base/frameworks/telemetry/index.rst | 3 +- .../base/frameworks/telemetry/main.zeek.rst | 59 +++++++------- .../frameworks/telemetry/options.zeek.rst | 11 +-- scripts/base/init-bare.zeek.rst | 77 ++++++++++--------- scripts/base/utils/conn-ids.zeek.rst | 6 +- .../frameworks/telemetry/prometheus.zeek.rst | 13 ++-- 8 files changed, 84 insertions(+), 101 deletions(-) diff --git a/frameworks/telemetry.rst b/frameworks/telemetry.rst index 2a1398453..f847b72b2 100644 --- a/frameworks/telemetry.rst +++ b/frameworks/telemetry.rst @@ -379,17 +379,3 @@ process, but keep the export and import of metrics enabled, use the following sn @ifdef ( Cluster::local_node_type() == Cluster::MANAGER ) redef Telemetry::metrics_port = 1234/tcp; @endif - - -Environment variables -^^^^^^^^^^^^^^^^^^^^^ - -Above Zeek options can also be controlled via environment variables. Instead -of setting :zeek:see:`Telemetry::metrics_port` in a Zeek script, you can set -the ``ZEEK_METRICS_PORT`` environment variable which takes precedence -over the Zeek option. - -As with Zeek script options, there are two configuration possibilities for a -cluster. Either configure a unique ``ZEEK_METRICS_PORT`` and -``ZEEK_METRICS_ENDPOINT_NAME`` for each of the Zeek processes. Then, setup a -Prometheus server to scrape each of these individual endpoints. diff --git a/scripts/base/bif/event.bif.zeek.rst b/scripts/base/bif/event.bif.zeek.rst index 93f3200c9..7bdcc90e3 100644 --- a/scripts/base/bif/event.bif.zeek.rst +++ b/scripts/base/bif/event.bif.zeek.rst @@ -826,7 +826,7 @@ Events .. zeek:see:: new_packet tcp_packet ipv6_ext_headers .. zeek:id:: net_done - :source-code: base/init-bare.zeek 5951 5953 + :source-code: base/init-bare.zeek 5952 5954 :Type: :zeek:type:`event` (t: :zeek:type:`time`) diff --git a/scripts/base/frameworks/telemetry/index.rst b/scripts/base/frameworks/telemetry/index.rst index 7e01881d5..e7e6ca4d2 100644 --- a/scripts/base/frameworks/telemetry/index.rst +++ b/scripts/base/frameworks/telemetry/index.rst @@ -16,6 +16,5 @@ Package: base/frameworks/telemetry the lower-level telemetry.bif functions. Metrics will be exposed through a Prometheus HTTP endpoint when - enabled by setting :zeek:see:`Telemetry::metrics_port` or using the - `ZEEK_METRICS_PORT` environment variable. + enabled by setting :zeek:see:`Telemetry::metrics_port`. diff --git a/scripts/base/frameworks/telemetry/main.zeek.rst b/scripts/base/frameworks/telemetry/main.zeek.rst index 89a9d01f8..58b598dde 100644 --- a/scripts/base/frameworks/telemetry/main.zeek.rst +++ b/scripts/base/frameworks/telemetry/main.zeek.rst @@ -8,8 +8,7 @@ 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` or using the -`ZEEK_METRICS_PORT` environment variable. +enabled by setting :zeek:see:`Telemetry::metrics_port`. :Namespace: Telemetry :Imports: :doc:`base/frameworks/telemetry/options.zeek `, :doc:`base/misc/version.zeek ` @@ -76,7 +75,7 @@ Detailed Interface Runtime Options ############### .. zeek:id:: Telemetry::sync_interval - :source-code: base/frameworks/telemetry/main.zeek 264 264 + :source-code: base/frameworks/telemetry/main.zeek 263 263 :Type: :zeek:type:`interval` :Attributes: :zeek:attr:`&redef` @@ -87,7 +86,7 @@ Runtime Options Types ##### .. zeek:type:: Telemetry::Counter - :source-code: base/frameworks/telemetry/main.zeek 35 37 + :source-code: base/frameworks/telemetry/main.zeek 34 36 :Type: :zeek:type:`record` @@ -103,7 +102,7 @@ Types by protocol and service. .. zeek:type:: Telemetry::CounterFamily - :source-code: base/frameworks/telemetry/main.zeek 22 25 + :source-code: base/frameworks/telemetry/main.zeek 21 24 :Type: :zeek:type:`record` @@ -118,7 +117,7 @@ Types use :zeek:see:`Telemetry::counter_family_inc`. .. zeek:type:: Telemetry::Gauge - :source-code: base/frameworks/telemetry/main.zeek 118 120 + :source-code: base/frameworks/telemetry/main.zeek 117 119 :Type: :zeek:type:`record` @@ -133,7 +132,7 @@ Types :zeek:see:`val_footprint`. .. zeek:type:: Telemetry::GaugeFamily - :source-code: base/frameworks/telemetry/main.zeek 106 109 + :source-code: base/frameworks/telemetry/main.zeek 105 108 :Type: :zeek:type:`record` @@ -149,7 +148,7 @@ Types :zeek:see:`Telemetry::gauge_family_set` directly. .. zeek:type:: Telemetry::Histogram - :source-code: base/frameworks/telemetry/main.zeek 214 216 + :source-code: base/frameworks/telemetry/main.zeek 213 215 :Type: :zeek:type:`record` @@ -159,7 +158,7 @@ Types Use :zeek:see:`Telemetry::histogram_observe` to make observations. .. zeek:type:: Telemetry::HistogramFamily - :source-code: base/frameworks/telemetry/main.zeek 207 210 + :source-code: base/frameworks/telemetry/main.zeek 206 209 :Type: :zeek:type:`record` @@ -173,7 +172,7 @@ Types :zeek:see:`Telemetry::histogram_family_observe` directly. .. zeek:type:: Telemetry::labels_vector - :source-code: base/frameworks/telemetry/main.zeek 15 15 + :source-code: base/frameworks/telemetry/main.zeek 14 14 :Type: :zeek:type:`vector` of :zeek:type:`string` @@ -202,7 +201,7 @@ Hooks Functions ######### .. zeek:id:: Telemetry::collect_histogram_metrics - :source-code: base/frameworks/telemetry/main.zeek 473 476 + :source-code: base/frameworks/telemetry/main.zeek 472 475 :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` @@ -213,7 +212,7 @@ Functions all histogram metrics are returned. .. zeek:id:: Telemetry::collect_metrics - :source-code: base/frameworks/telemetry/main.zeek 468 471 + :source-code: base/frameworks/telemetry/main.zeek 467 470 :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` @@ -225,7 +224,7 @@ Functions all counters and gauges are returned. .. zeek:id:: Telemetry::counter_family_inc - :source-code: base/frameworks/telemetry/main.zeek 344 347 + :source-code: base/frameworks/telemetry/main.zeek 343 346 :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` @@ -246,7 +245,7 @@ Functions :returns: True if the counter was incremented successfully. .. zeek:id:: Telemetry::counter_family_set - :source-code: base/frameworks/telemetry/main.zeek 349 352 + :source-code: base/frameworks/telemetry/main.zeek 348 351 :Type: :zeek:type:`function` (cf: :zeek:type:`Telemetry::CounterFamily`, label_values: :zeek:type:`Telemetry::labels_vector`, value: :zeek:type:`double`) : :zeek:type:`bool` @@ -268,7 +267,7 @@ Functions :returns: True if the counter value was set successfully. .. zeek:id:: Telemetry::counter_inc - :source-code: base/frameworks/telemetry/main.zeek 328 331 + :source-code: base/frameworks/telemetry/main.zeek 327 330 :Type: :zeek:type:`function` (c: :zeek:type:`Telemetry::Counter`, amount: :zeek:type:`double` :zeek:attr:`&default` = ``1.0`` :zeek:attr:`&optional`) : :zeek:type:`bool` @@ -285,7 +284,7 @@ Functions :returns: True if the counter was incremented successfully. .. zeek:id:: Telemetry::counter_set - :source-code: base/frameworks/telemetry/main.zeek 333 342 + :source-code: base/frameworks/telemetry/main.zeek 332 341 :Type: :zeek:type:`function` (c: :zeek:type:`Telemetry::Counter`, value: :zeek:type:`double`) : :zeek:type:`bool` @@ -305,14 +304,14 @@ Functions :returns: True if the counter value was set successfully. .. zeek:id:: Telemetry::counter_with - :source-code: base/frameworks/telemetry/main.zeek 315 326 + :source-code: base/frameworks/telemetry/main.zeek 314 325 :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 392 395 + :source-code: base/frameworks/telemetry/main.zeek 391 394 :Type: :zeek:type:`function` (g: :zeek:type:`Telemetry::Gauge`, amount: :zeek:type:`double` :zeek:attr:`&default` = ``1.0`` :zeek:attr:`&optional`) : :zeek:type:`bool` @@ -328,7 +327,7 @@ Functions :returns: True if the gauge was incremented successfully. .. zeek:id:: Telemetry::gauge_family_dec - :source-code: base/frameworks/telemetry/main.zeek 413 416 + :source-code: base/frameworks/telemetry/main.zeek 412 415 :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` @@ -349,7 +348,7 @@ Functions :returns: True if the gauge was incremented successfully. .. zeek:id:: Telemetry::gauge_family_inc - :source-code: base/frameworks/telemetry/main.zeek 408 411 + :source-code: base/frameworks/telemetry/main.zeek 407 410 :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` @@ -371,7 +370,7 @@ Functions :returns: True if the gauge was incremented successfully. .. zeek:id:: Telemetry::gauge_family_set - :source-code: base/frameworks/telemetry/main.zeek 418 421 + :source-code: base/frameworks/telemetry/main.zeek 417 420 :Type: :zeek:type:`function` (gf: :zeek:type:`Telemetry::GaugeFamily`, label_values: :zeek:type:`Telemetry::labels_vector`, value: :zeek:type:`double`) : :zeek:type:`bool` @@ -392,7 +391,7 @@ Functions :returns: True if the gauge value was set successfully. .. zeek:id:: Telemetry::gauge_inc - :source-code: base/frameworks/telemetry/main.zeek 387 390 + :source-code: base/frameworks/telemetry/main.zeek 386 389 :Type: :zeek:type:`function` (g: :zeek:type:`Telemetry::Gauge`, amount: :zeek:type:`double` :zeek:attr:`&default` = ``1.0`` :zeek:attr:`&optional`) : :zeek:type:`bool` @@ -408,7 +407,7 @@ Functions :returns: True if the gauge was incremented successfully. .. zeek:id:: Telemetry::gauge_set - :source-code: base/frameworks/telemetry/main.zeek 397 406 + :source-code: base/frameworks/telemetry/main.zeek 396 405 :Type: :zeek:type:`function` (g: :zeek:type:`Telemetry::Gauge`, value: :zeek:type:`double`) : :zeek:type:`bool` @@ -424,14 +423,14 @@ Functions :returns: True if the gauge value was set successfully. .. zeek:id:: Telemetry::gauge_with - :source-code: base/frameworks/telemetry/main.zeek 375 385 + :source-code: base/frameworks/telemetry/main.zeek 374 384 :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 463 466 + :source-code: base/frameworks/telemetry/main.zeek 462 465 :Type: :zeek:type:`function` (hf: :zeek:type:`Telemetry::HistogramFamily`, label_values: :zeek:type:`Telemetry::labels_vector`, measurement: :zeek:type:`double`) : :zeek:type:`bool` @@ -452,7 +451,7 @@ Functions :returns: True if measurement was observed successfully. .. zeek:id:: Telemetry::histogram_observe - :source-code: base/frameworks/telemetry/main.zeek 458 461 + :source-code: base/frameworks/telemetry/main.zeek 457 460 :Type: :zeek:type:`function` (h: :zeek:type:`Telemetry::Histogram`, measurement: :zeek:type:`double`) : :zeek:type:`bool` @@ -468,28 +467,28 @@ Functions :returns: True if measurement was observed successfully. .. zeek:id:: Telemetry::histogram_with - :source-code: base/frameworks/telemetry/main.zeek 445 456 + :source-code: base/frameworks/telemetry/main.zeek 444 455 :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 294 305 + :source-code: base/frameworks/telemetry/main.zeek 293 304 :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 354 365 + :source-code: base/frameworks/telemetry/main.zeek 353 364 :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 423 434 + :source-code: base/frameworks/telemetry/main.zeek 422 433 :Type: :zeek:type:`function` (opts: :zeek:type:`Telemetry::MetricOpts`) : :zeek:type:`Telemetry::HistogramFamily` diff --git a/scripts/base/frameworks/telemetry/options.zeek.rst b/scripts/base/frameworks/telemetry/options.zeek.rst index 0315e5679..3485a740b 100644 --- a/scripts/base/frameworks/telemetry/options.zeek.rst +++ b/scripts/base/frameworks/telemetry/options.zeek.rst @@ -23,7 +23,7 @@ Detailed Interface Redefinable Options ################### .. zeek:id:: Telemetry::metrics_endpoint_name - :source-code: base/frameworks/telemetry/options.zeek 19 19 + :source-code: base/frameworks/telemetry/options.zeek 16 16 :Type: :zeek:type:`string` :Attributes: :zeek:attr:`&redef` @@ -31,19 +31,16 @@ Redefinable Options ID for the metrics exporter. This is used as the 'endpoint' label value when exporting data to Prometheus. In a cluster setup, this - defaults to the name of the node in the cluster configuration. Zeek - overrides any value provided in zeek_init or earlier at startup if - the environment variable ZEEK_METRICS_ENDPOINT_NAME is defined. + defaults to the name of the node in the cluster configuration. .. zeek:id:: Telemetry::metrics_port - :source-code: base/frameworks/telemetry/options.zeek 12 12 + :source-code: base/frameworks/telemetry/options.zeek 11 11 :Type: :zeek:type:`port` :Attributes: :zeek:attr:`&redef` :Default: ``0/unknown`` Port used to make metric data available to Prometheus scrapers via - HTTP. Zeek overrides any value provided in zeek_init or earlier at - startup if the environment variable ZEEK_METRICS_PORT is defined. + HTTP. diff --git a/scripts/base/init-bare.zeek.rst b/scripts/base/init-bare.zeek.rst index baa8794ef..bec1bceea 100644 --- a/scripts/base/init-bare.zeek.rst +++ b/scripts/base/init-bare.zeek.rst @@ -587,9 +587,9 @@ Types :zeek:type:`SYN_packet`: :zeek:type:`record` Fields of a SYN packet. :zeek:type:`TCP::Option`: :zeek:type:`record` A TCP Option field parsed from a TCP header. :zeek:type:`TCP::OptionList`: :zeek:type:`vector` The full list of TCP Option fields parsed from a TCP header. -:zeek:type:`Telemetry::HistogramMetric`: :zeek:type:`record` Type of elements returned by the :zeek:see:`Telemetry::collect_histogram_metrics` function. +:zeek:type:`Telemetry::HistogramMetric`: :zeek:type:`record` Histograms returned by the :zeek:see:`Telemetry::collect_histogram_metrics` function. :zeek:type:`Telemetry::HistogramMetricVector`: :zeek:type:`vector` -:zeek:type:`Telemetry::Metric`: :zeek:type:`record` Type of elements returned by the :zeek:see:`Telemetry::collect_metrics` function. +:zeek:type:`Telemetry::Metric`: :zeek:type:`record` Metrics returned by the :zeek:see:`Telemetry::collect_metrics` function. :zeek:type:`Telemetry::MetricOpts`: :zeek:type:`record` Type that captures options used to create metrics. :zeek:type:`Telemetry::MetricType`: :zeek:type:`enum` :zeek:type:`Telemetry::MetricVector`: :zeek:type:`vector` @@ -1424,7 +1424,7 @@ Redefinable Options .. zeek:id:: bits_per_uid - :source-code: base/init-bare.zeek 5907 5907 + :source-code: base/init-bare.zeek 5908 5908 :Type: :zeek:type:`count` :Attributes: :zeek:attr:`&redef` @@ -1465,7 +1465,7 @@ Redefinable Options be reported via :zeek:see:`content_gap`. .. zeek:id:: digest_salt - :source-code: base/init-bare.zeek 5915 5915 + :source-code: base/init-bare.zeek 5916 5916 :Type: :zeek:type:`string` :Attributes: :zeek:attr:`&redef` @@ -1649,7 +1649,7 @@ Redefinable Options means "forever", which resists evasion, but can lead to state accrual. .. zeek:id:: global_hash_seed - :source-code: base/init-bare.zeek 5902 5902 + :source-code: base/init-bare.zeek 5903 5903 :Type: :zeek:type:`string` :Attributes: :zeek:attr:`&redef` @@ -1706,7 +1706,7 @@ Redefinable Options .. zeek:see:: conn_stats .. zeek:id:: io_poll_interval_default - :source-code: base/init-bare.zeek 5932 5932 + :source-code: base/init-bare.zeek 5933 5933 :Type: :zeek:type:`count` :Attributes: :zeek:attr:`&redef` @@ -1725,7 +1725,7 @@ Redefinable Options .. zeek:see:: io_poll_interval_live .. zeek:id:: io_poll_interval_live - :source-code: base/init-bare.zeek 5947 5947 + :source-code: base/init-bare.zeek 5948 5948 :Type: :zeek:type:`count` :Attributes: :zeek:attr:`&redef` @@ -1965,7 +1965,7 @@ Redefinable Options was observed. .. zeek:id:: max_find_all_string_length - :source-code: base/init-bare.zeek 5919 5919 + :source-code: base/init-bare.zeek 5920 5920 :Type: :zeek:type:`int` :Attributes: :zeek:attr:`&redef` @@ -3356,7 +3356,7 @@ State Variables .. zeek:see:: dns_skip_all_auth dns_skip_addl .. zeek:id:: done_with_network - :source-code: base/init-bare.zeek 5950 5950 + :source-code: base/init-bare.zeek 5951 5951 :Type: :zeek:type:`bool` :Default: ``F`` @@ -7706,7 +7706,7 @@ Types The full list of TCP Option fields parsed from a TCP header. .. zeek:type:: Telemetry::HistogramMetric - :source-code: base/init-bare.zeek 5859 5891 + :source-code: base/init-bare.zeek 5861 5892 :Type: :zeek:type:`record` @@ -7721,10 +7721,9 @@ Types described by the *bounds* field in *opts*; count_values: :zeek:type:`vector` of :zeek:type:`count` :zeek:attr:`&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. + Integer values for the individual counters for each of the + bckets as described in the ``bounds`` field in ``opts``. This + value will be unset if the metric type is DOUBLE_HISTOGRAM. observations: :zeek:type:`double` The number of observations made for this histogram. @@ -7733,25 +7732,25 @@ Types The sum of all observations for this histogram. count_observations: :zeek:type:`count` :zeek:attr:`&optional` - If the underlying data type of the histogram is ``int64_t``, - the number of observations as :zeek:type:`count`, otherwise - unset. + The integer value of the number of observations made for this + histogram. This value will be unset if the metric type is + DOUBLE_HISTOGRAM. count_sum: :zeek:type:`count` :zeek:attr:`&optional` - If the underlying data type of the histogram is ``int64_t``, - the sum of all observations as :zeek:type:`count`, otherwise - unset. + The integer value of the sum of all observations for this + histogram. This value will be unset if the metric type is + DOUBLE_HISTOGRAM. - Type of elements returned by the :zeek:see:`Telemetry::collect_histogram_metrics` function. + Histograms returned by the :zeek:see:`Telemetry::collect_histogram_metrics` function. .. zeek:type:: Telemetry::HistogramMetricVector - :source-code: base/init-bare.zeek 5894 5894 + :source-code: base/init-bare.zeek 5895 5895 :Type: :zeek:type:`vector` of :zeek:type:`Telemetry::HistogramMetric` .. zeek:type:: Telemetry::Metric - :source-code: base/init-bare.zeek 5838 5856 + :source-code: base/init-bare.zeek 5841 5858 :Type: :zeek:type:`record` @@ -7768,22 +7767,21 @@ Types it is unset for histograms. count_value: :zeek:type:`count` :zeek:attr:`&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. + The integer value of underlying instrument if the metric type + is INT_COUNTER or INT_GAUGE. This will be unset if the type + is DOUBLE_COUNTER or DOUBLE_GAUGE. - Type of elements returned by the :zeek:see:`Telemetry::collect_metrics` function. + Metrics returned by the :zeek:see:`Telemetry::collect_metrics` function. .. zeek:type:: Telemetry::MetricOpts - :source-code: base/init-bare.zeek 5787 5835 + :source-code: base/init-bare.zeek 5787 5838 :Type: :zeek:type:`record` - prefix: :zeek:type:`string` :zeek:attr:`&optional` - The prefix (namespace) of the metric. Will be unset when - returned from :zeek:see:`Telemetry::collect_metrics` or - :zeek:see:`Telemetry::collect_histogram_metrics`. + prefix: :zeek:type:`string` + The prefix (namespace) of the metric. Zeek uses the ``zeek`` + prefix for any internal metrics and the ``process`` prefix + for any metrics involving process state (CPU, memory, etc). name: :zeek:type:`string` The human-readable name of the metric. This is set to the @@ -7792,18 +7790,21 @@ Types :zeek:see:`Telemetry::collect_histogram_metrics`. unit: :zeek:type:`string` :zeek:attr:`&optional` - The unit of the metric. Set to a blank string if this is a - unit-less metric. Will be unset when returned from + The unit of the metric. Leave this unset for a unit-less + metric. Will be unset when returned from :zeek:see:`Telemetry::collect_metrics` or :zeek:see:`Telemetry::collect_histogram_metrics`. - help_text: :zeek:type:`string` + help_text: :zeek:type:`string` :zeek:attr:`&optional` Documentation for this metric. labels: :zeek:type:`vector` of :zeek:type:`string` :zeek:attr:`&default` = ``[]`` :zeek:attr:`&optional` The label names (also called dimensions) of the metric. When instantiating or working with concrete metrics, corresponding - label values have to be provided. + label values have to be provided. Examples of a label might + be the protocol a general observation applies to, the + directionality in a traffic flow, or protocol-specific + context like a particular message type. is_total: :zeek:type:`bool` :zeek:attr:`&optional` Whether the metric represents something that is accumulating. @@ -7849,7 +7850,7 @@ Types .. zeek:type:: Telemetry::MetricVector - :source-code: base/init-bare.zeek 5893 5893 + :source-code: base/init-bare.zeek 5894 5894 :Type: :zeek:type:`vector` of :zeek:type:`Telemetry::Metric` diff --git a/scripts/base/utils/conn-ids.zeek.rst b/scripts/base/utils/conn-ids.zeek.rst index b3ffbd800..f1d4d72ad 100644 --- a/scripts/base/utils/conn-ids.zeek.rst +++ b/scripts/base/utils/conn-ids.zeek.rst @@ -29,7 +29,7 @@ Detailed Interface Functions ######### .. zeek:id:: directed_id_string - :source-code: base/utils/conn-ids.zeek 39 42 + :source-code: base/utils/conn-ids.zeek 35 38 :Type: :zeek:type:`function` (id: :zeek:type:`conn_id`, is_orig: :zeek:type:`bool`) : :zeek:type:`string` @@ -37,7 +37,7 @@ Functions second argument is T or F, respectively. .. zeek:id:: id_string - :source-code: base/utils/conn-ids.zeek 25 30 + :source-code: base/utils/conn-ids.zeek 21 26 :Type: :zeek:type:`function` (id: :zeek:type:`conn_id`) : :zeek:type:`string` @@ -46,7 +46,7 @@ Functions on the left to the responder on the right. .. zeek:id:: reverse_id_string - :source-code: base/utils/conn-ids.zeek 32 37 + :source-code: base/utils/conn-ids.zeek 28 33 :Type: :zeek:type:`function` (id: :zeek:type:`conn_id`) : :zeek:type:`string` diff --git a/scripts/policy/frameworks/telemetry/prometheus.zeek.rst b/scripts/policy/frameworks/telemetry/prometheus.zeek.rst index 15e900679..0702f61d5 100644 --- a/scripts/policy/frameworks/telemetry/prometheus.zeek.rst +++ b/scripts/policy/frameworks/telemetry/prometheus.zeek.rst @@ -3,17 +3,18 @@ policy/frameworks/telemetry/prometheus.zeek =========================================== -In a cluster configuration, open port 9911 on the manager for -Prometheus exposition and import all metrics from the -`zeek/cluster/metrics/...` topic. +In a cluster configuration, open the port number for metrics +from the cluster node configuration for exporting data t +Prometheus. For customization or disabling, redef the involved Telemetry options again. Specifically, to disable listening on port 9911, set :zeek:see:`Telemetry::metrics_port` to `0/unknown` again. -Note that in large clusters, metrics import may cause significant -communication overhead as well as load on the manager. - +The manager node will also provide a ``/services.json`` endpoint +for the HTTP Service Discovery system in Prometheus to use for +configuration. This endpoint will include information for all of +the other nodes in the cluster. :Imports: :doc:`base/frameworks/cluster `