# metrics-probe Available in AxoSyslog version 4.1.1 and newer. `metrics-probe()` is a special parser that counts the messages that pass through the log path, and creates labeled stats counters based on the fields of the passing messages. You can configure the name of the keys and the labels. Note that the keys are automatically prefixed with the `syslogng_` string. You can use templates in the values of the labels. See also the equivalent FilterX function, [`update_metric()`](../../docs/axosyslog-core/4.26/filterx/function-reference/index.md#update-metric), which takes the counter name as its first argument instead of in a `key()` option. The minimal configuration creates counters with the key `syslogng_classified_events_total` and labels `app`, `host`, `program` and `source`. For example: Terminal window ``` parser p_metrics_probe { metrics-probe(); # Same as: # # metrics-probe( # key("classified_events_total") # labels( # "app" => "${APP}" # "host" => "${HOST}" # "program" => "${PROGRAM}" # "source" => "${SOURCE}" # ) # ); }; ``` This configuration results in counters like: Terminal window ``` syslogng_classified_events_total{app="example-app", host="localhost", program="baz", source="s_local_1"} 3 syslogng_classified_events_total{app="example-app", host="localhost", program="bar", source="s_local_1"} 1 syslogng_classified_events_total{app="example-app", host="localhost", program="foo", source="s_local_1"} 1 ``` You can query the metrics by running the following command: Terminal window ``` syslog-ng-ctl stats prometheus ``` For example, the following `metrics-probe()` parser creates a counter called `syslogng_custom_key` that counts messages that have their `custom_label_name_1` field set to `foobar`, and for these messages it creates separate counters based on the value of the `custom_label_name_2` field. Terminal window ``` parser p_metrics_probe { metrics-probe( key("custom_key") # adds "syslogng_" prefix => "syslogng_custom_key" labels( "custom_label_name_1" => "foobar" "custom_label_name_2" => "${.custom.field}" ) ); }; ``` This configuration results in counters like: Terminal window ``` syslogng_custom_key{custom_label_name_1="foobar", custom_label_name_2="bar"} 1 syslogng_custom_key{custom_label_name_1="foobar", custom_label_name_2="foo"} 1 syslogng_custom_key{custom_label_name_1="foobar", custom_label_name_2="baz"} 3 ``` Starting with AxoSyslog 4.4, you can create [dynamic labels](../../docs/axosyslog-core/4.26/chapter-parsers/metrics-probe/index.md#dynamic-labels) as well. ## Options The `metrics-probe()` parser has the following options. In addition to the options listed here, `metrics-probe()` accepts the [`value-pairs()` options](../../docs/axosyslog-core/4.26/chapter-concepts/concepts-value-pairs/option-value-pairs/index.md) — such as `cast()`, `exclude()`, `include-bytes()`, `key()`, `pair()`, `rekey()`, and `scope()` — inside its `labels()` option. For details, see [Dynamic labels](../../docs/axosyslog-core/4.26/chapter-parsers/metrics-probe/index.md#dynamic-labels). ## frac-digits() | ---|--- Type: | number Default: | 0 _Description:_ The AxoSyslog application can store fractions of a second in the timestamps according to the ISO8601 format. The `frac-digits()` parameter specifies the number of digits stored. The digits storing the fractions are padded by zeros if the original timestamp of the message specifies only seconds. Fractions can always be stored for the time the message was received. Note The AxoSyslog application can add the fractions to non-ISO8601 timestamps as well. Note As AxoSyslog is precise up to the microsecond, when the `frac-digits()` option is set to a value higher than 6, AxoSyslog will truncate the fraction seconds in the timestamps after 6 digits. ## increment() | ---|--- Type: | integer or template Default: | 1 Available in AxoSyslog version 4.2 and newer. Sets a template, which resolves to a number that defines the increment of the counter. The following example defines a counter called `syslogng_input_event_bytes_total`, and increases its value with the size of the incoming message (in bytes). Terminal window ``` metrics-probe( key("input_event_bytes_total") labels( "cluster" => "`cluster-name`" "driver" => "kubernetes" "id" => "${SOURCE}" "namespace" => "${`prefix`namespace_name}" "pod" => "${`prefix`pod_name}" ) increment("${RAWMSG_SIZE}") ); ``` ## internal() | ---|--- Accepted values: | `yes`, `no` Default: | `no` _Description:_ Marks this pipeline element as internal. Elements marked as `internal()` are treated as an implementation detail, so for example statistics of the given pipe are available only on higher stats level. This option is mainly useful for developers or when writing SCL blocks and integrations. ## key() | ---|--- Type: | string Default: | `classified_events_total` The name of the counter to create. Note that the value of this option is always prefixed with `syslogng_`, so for example `key("my-custom-key")` becomes `syslogng_my-custom-key`. ## labels() | ---|--- Type: | Default: | See the description The labels used to create separate counters, based on the fields of the messages processed by `metrics-probe()`. Use the following format: Terminal window ``` labels( "name-of-the-label-in-the-output" => "field-of-the-message" ) ``` Default value: Terminal window ``` labels( "app" => "${APP}" "host" => "${HOST}" "program" => "${PROGRAM}" "source" => "${SOURCE}" ) ``` This results in counters like: Terminal window ``` syslogng_classified_events_total{app="example-app", host="localhost", program="baz", source="s_local_1"} 3 ``` ### Dynamic labels Available in AxoSyslog 4.4 and newer. Dynamic labelling allows you to use every available [`value-pairs()` options](../../docs/axosyslog-core/4.26/chapter-concepts/concepts-value-pairs/option-value-pairs/index.md) in the labels, for example, `key()`, `rekey()`, `pair()`, or `scope()`. For example: Terminal window ``` metrics-probe( key("foo") labels( "static-label" => "bar" key(".my_prefix.*" rekey(shift-levels(1))) ) ); ``` Terminal window ``` syslogng_foo{static_label="bar",my_prefix_baz="anotherlabel",my_prefix_foo="bar",my_prefix_nested_axo="flow"} 4 ``` ## level() | ---|--- Type: | integer (0-3) Default: | 0 Available in AxoSyslog version 4.2 and newer. Sets the stats level of the generated metrics. > Note: Drivers configured with `internal(yes)` register their metrics on level 3. That way if you are creating an SCL, you can disable the built-in metrics of the driver, and create metrics manually using `metrics-probe()`. ## local-time-zone() | ---|--- Type: | name of the timezone, or the timezone offset Default: | The local timezone. _Description:_ Sets the timezone that AxoSyslog uses when it expands a timestamp macro in the `increment()` or `labels()` templates as a local time. The timezone can be specified by using the name, for example, `time-zone("Europe/Budapest")`), or as the timezone offset in +/-HH:MM format, for example, `+01:00`). On Linux and UNIX platforms, the valid timezone names are listed under the `/usr/share/zoneinfo` directory. ## on-error() Type: | One of: `drop-message`, `drop-property`, `fallback-to-string`, `silently-drop-message`, `silently-drop-property`, `silently-fallback-to-string` ---|--- Default: | Use the global setting (which defaults to `drop-message`) _Description:_ Controls what happens when type-casting fails and AxoSyslog cannot convert some data to the specified type. By default, AxoSyslog drops the entire message and logs the error. Currently the `value-pairs()` option uses the settings of `on-error()`. * `drop-message`: Drop the entire message and log an error message to the `internal()` source. This is the default behavior of AxoSyslog. * `drop-property`: Omit the affected property (macro, template, or message-field) from the log message and log an error message to the `internal()` source. * `fallback-to-string`: Convert the property to string and log an error message to the `internal()` source. * `silently-drop-message`: Drop the entire message silently, without logging the error. * `silently-drop-property`: Omit the affected property (macro, template, or message-field) silently, without logging the error. * `silently-fallback-to-string`: Convert the property to string silently, without logging the error. ## send-time-zone() | ---|--- Type: | name of the timezone, or the timezone offset Default: | The local timezone. _Description:_ Sets the timezone that AxoSyslog uses when it expands a timestamp macro in the `increment()` or `labels()` templates. The `time-zone()` option is an alias of `send-time-zone()`. The timezone can be specified by using the name, for example, `time-zone("Europe/Budapest")`), or as the timezone offset in +/-HH:MM format, for example, `+01:00`). On Linux and UNIX platforms, the valid timezone names are listed under the `/usr/share/zoneinfo` directory. ## template() | ---|--- Synopsis: | `template("${}")` _Description:_ The macro that contains the part of the message that the parser will process. It can also be a macro created by a previous parser of the log path. By default, the parser processes the entire message (`${MESSAGE}`). ## template-escape() | ---|--- Type: | `yes`, `no` Default: | `no` _Description:_ Turns on escaping for the `'`, `"`, and backspace characters in the expanded value of the `increment()` and `labels()` templates. ## time-zone() | ---|--- Type: | name of the timezone, or the timezone offset Default: | The local timezone. _Description:_ Alias of [`send-time-zone()`](../../docs/axosyslog-core/4.26/chapter-parsers/metrics-probe/index.md#metrics-probe-option-send-time-zone). ## ts-format() | ---|--- Type: | `rfc3164`, `bsd`, `rfc3339`, `iso` Default: | `rfc3164` _Description:_ Overrides the global [`ts-format()`](../../docs/axosyslog-core/4.26/chapter-global-options/reference-options/index.md) option for the timestamp macros expanded in the `increment()` and `labels()` templates. Last modified August 6, 2026: [Sync metrics-probe parser with source code (b3bd0dce)]()