axoflow · eldarnash · Aug 20, 2023 · Aug 20, 2023 · Aug 20, 2023 · Oct 17, 2023
diff --git a/content/app-man-syslog-ng/syslog-ng-ctl.1.md b/content/app-man-syslog-ng/syslog-ng-ctl.1.md
@@ -190,7 +190,12 @@ The `syslog-ng-ctl query get` command has the following options:
 
 `stats [options]`
 
-Use the `stats` command to display statistics about the processed messages. For details about the displayed statistics, see [The {{% param "product.ose" %}} documentation](https://axoflow.com/). The `stats` command has the following options:
+Use the `stats` command to display statistics and metrics about the processed messages.
+
+- For details about the available Prometheus-like metrics, see {{% xref "/metrics/reference-metrics/_index.md" %}}. You can retrieve these metrics with the [`syslog-ng-ctl stats prometheus` command](#syslog-ng-ctl-stats-prometheus).
+- For details about legacy statistics, see {{% xref "/chapter-log-statistics/_index.md" %}}.
+
+The `stats` command has the following options:
 
 - `--control=<socket>` or `-c`
 
@@ -202,7 +207,7 @@ Use the `stats` command to display statistics about the processed messages. For
 
 - `--remove-orphans`
 
-    Safely removes all counters that are not referenced by any syslog-ng stat producer objects.
+    Safely removes all counters that are not referenced by any statistics producer objects.
 
     The flag can be used to prune dynamic and static counters manually. This is useful, for example, when a templated file destination produces a lot of stats:
 
@@ -216,8 +221,7 @@ Use the `stats` command to display statistics about the processed messages. For
 The `stats-lifetime()` can be used to do the same automatically and periodically, but currently stats-lifetime() removes only dynamic counters that have a timestamp field set.
     {{% /alert %}}
 
-
-### Example
+### Example for statistics
 
 ```shell
 syslog-ng-ctl stats
@@ -255,6 +259,44 @@ center;;queued;a;processed;0
 destination;df_facility_dot_err;;a;processed;0
 ```
 
+For details about legacy statistics, see {{% xref "/chapter-log-statistics/_index.md" %}}.
+
+<span id="syslog-ng-ctl-stats-prometheus"></span>
+
+### Example for statistics
+
+```shell
+syslog-ng-ctl stats prometheus
+```
+
+The output is similar to:
+
+```shell
+syslogng_events_allocated_bytes 18446744073709550560
+syslogng_filtered_events_total{id="#anon-filter0",result="matched"} 0
+syslogng_filtered_events_total{id="#anon-filter0",result="not_matched"} 2
+syslogng_filtered_events_total{id="ff",result="matched"} 0
+syslogng_filtered_events_total{id="ff",result="not_matched"} 2
+syslogng_input_events_total{id="#anon-source0#0",driver_instance="-",result="processed"} 0
+syslogng_input_events_total{id="s_network#1",result="processed"} 2
+syslogng_internal_source{result="dropped"} 0
+syslogng_internal_source{result="queued"} 0
+syslogng_output_events_total{id="d_dest#0",driver_instance="tcp,127.0.0.1:5555",result="delivered"} 0
+syslogng_output_events_total{id="d_dest#0",driver_instance="tcp,127.0.0.1:5555",result="dropped"} 0
+syslogng_output_events_total{id="d_dest#0",driver_instance="tcp,127.0.0.1:5555",result="queued"} 0
+syslogng_output_events_total{id="d_dest#1",driver_instance="http,https://localhost:8080",result="delivered"} 0
+syslogng_output_events_total{id="d_dest#1",driver_instance="http,https://localhost:8080",result="dropped"} 0
+syslogng_output_events_total{id="d_dest#1",driver_instance="http,https://localhost:8080",result="queued"} 0
+syslogng_parsed_events_total{id="#anon-parser0",result="discarded"} 0
+syslogng_parsed_events_total{id="#anon-parser0",result="processed"} 0
+syslogng_scratch_buffers_bytes 0
+syslogng_scratch_buffers_total 3
+syslogng_tagged_events_total{id=".source.#anon-source0",result="processed"} 0
+syslogng_tagged_events_total{id=".source.s_network",result="processed"} 2
+```
+
+For details about the available Prometheus-like metrics, see {{% xref "/metrics/reference-metrics/_index.md" %}}.
+
 <span id="syslog-ng-ctl-credentials"></span>
 
 ## Handling password-protected private keys

diff --git a/content/chapter-log-statistics/_index.md b/content/chapter-log-statistics/_index.md
@@ -4,28 +4,22 @@ weight:  3700
 ---
 <!-- DISCLAIMER: This file is based on the syslog-ng Open Source Edition documentation https://github.com/balabit/syslog-ng-ose-guides/commit/2f4a52ee61d1ea9ad27cb4f3168b95408fddfdf2 and is used under the terms of The syslog-ng Open Source Edition Documentation License. The file has been modified by Axoflow. -->
 
-The {{% param "product.abbrev" %}} application collects various statistics and measures different metrics about the messages it receives and delivers. These metrics are collected into different counters, depending on the configuration of {{% param "product.abbrev" %}}. The [`stats-level()` global option]({{< relref "/chapter-global-options/reference-options/_index.md" >}}) determines exactly which statistics {{% param "product.abbrev" %}} collects. You can access these statistics and metrics using the following methods.
+{{% alert title="Note" color="info" %}}
+This chapter describes the legacy statistics of {{% param "product.abbrev" %}}. For the Prometheus-like metrics framework, see {{% xref "/metrics/_index.md" %}}.
+{{% /alert %}}
 
+The {{% param "product.abbrev" %}} application collects and measures various statistics about the messages it receives and delivers. These statistics are collected into different counters, depending on the configuration of {{% param "product.abbrev" %}}. The [`stats-level()` global option]({{< relref "/chapter-global-options/reference-options/_index.md" >}}) determines exactly which statistics {{% param "product.abbrev" %}} collects. You can access these statistics and metrics using the following methods.
 
-## Recommended: Structured, selective methods:
-
-  - Using the `monitoring()` source.
-
-  - Using the [`syslog-ng-ctl`]({{< relref "/chapter-quickstart/managing-and-checking-linux/_index.md#stats" >}}) query command.
-
-    For further information about using `syslog-ng-ctl` commands, see <span class="mcFormatColor" style="color: #04aada;">The `syslog-ng` manual pages</span>.
+## Structured, selective method
 
+Using the [`syslog-ng-ctl`]({{< relref "/chapter-quickstart/managing-and-checking-linux/_index.md#stats" >}}) query command. For further information about using `syslog-ng-ctl` commands, see <span class="mcFormatColor" style="color: #04aada;">The `syslog-ng` manual pages</span>.
 
+## Unstructured, bulk methods
 
-## Legacy: Unstructured, bulk methods:
+- Using the [`internal()` source]({{< relref "/chapter-log-statistics/log-statistics-internal-source/_index.md" >}}).
+- Using the [`syslog-ng-ctl stats`]({{< relref "/chapter-quickstart/managing-and-checking-linux/_index.md#stats" >}}) command.
 
-  - Using the [`internal()` source]({{< relref "/chapter-log-statistics/log-statistics-internal-source/_index.md" >}}).
-
-  - Using the [`syslog-ng-ctl stats`]({{< relref "/chapter-quickstart/managing-and-checking-linux/_index.md#stats" >}}) command.
-
     For further information about using `syslog-ng-ctl` commands, see <span class="mcFormatColor" style="color: #04aada;">The `syslog-ng` manual pages</span>.
 
-  - Use the `socat` application: `echo STATS | socat -vv UNIX-CONNECT:/opt/syslog-ng/var/run/syslog-ng.ctl -`
-
-  - If you have an OpenBSD-style `netcat` application installed, use the `echo STATS | nc -U /opt/syslog-ng/var/run/syslog-ng.ctl` command. Note that the `netcat` included in most Linux distributions is a GNU-style version that is not suitable to query the statistics of `syslog-ng`.
-
+- Use the `socat` application: `echo STATS | socat -vv UNIX-CONNECT:/opt/syslog-ng/var/run/syslog-ng.ctl -`
+- If you have an OpenBSD-style `netcat` application installed, use the `echo STATS | nc -U /opt/syslog-ng/var/run/syslog-ng.ctl` command. Note that the `netcat` included in most Linux distributions is a GNU-style version that is not suitable to query the statistics of `syslog-ng`.
diff --git a/content/headless/chunk/option-destination-diskbuffer.md b/content/headless/chunk/option-destination-diskbuffer.md
@@ -100,6 +100,25 @@ Available in {{% param "product.abbrev" %}} 4.0 and later.
 Hazard of data loss! If you change the value of `reliable()` option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.
 {{% /alert %}}
 
+## stats()
+
+| Type:        | `number [minutes]` |
+|--------------|-----------|
+| Default:     | 5        |
+
+Available in {{% param "product.abbrev" %}} 4.2 and later.
+
+*Description:* Set the frequency of generating [disk-buffer related metrics]({{< relref "/metrics/reference-metrics/_index.md#disk-buffer-metrics" >}}). Set it to zero to disable metrics.
+
+```shell
+options {
+  disk-buffer(
+    stats(
+      freq(10)
+    )
+  );
+};```
+
 ### truncate-size-ratio() {#diskbuf-trunkate-size-ratio}
 
 | Type:        | number((between 0 and 1))    |

diff --git a/content/metrics/_index.md b/content/metrics/_index.md
@@ -0,0 +1,82 @@
+---
+title: Prometheus-like metrics
+weight: 3800
+type: docs
+cascade:
+    type: docs
+---
+
+Starting with version 4.0, {{% param "product.abbrev" %}} provides a new metric naming scheme (labeling capability) to provide metrics and statistics about the processed events. You can query the metrics using `syslog-ng-ctl`, which can produce Prometheus-like metric exports.
+
+<!-- FIXME add/mention the new metrics exporter? https://github.com/axoflow/axosyslog-metrics-exporter -->
+
+Metrics are identified by names and partitioned by labels, similarly to the [Prometheus data model](https://prometheus.io/docs/concepts/data_model/), in the following format: `<metric-name>{<id>, <labels>} <value-of-the-metric>`
+
+The part with the curly braces is optional, and not used for certain metrics. For example:
+
+```shell
+syslogng_events_allocated_bytes 18446744073709550560
+syslogng_filtered_events_total{id="#anon-filter0",result="matched"} 0
+```
+
+Note that:
+
+- The order of the labels doesn't matter.
+- A label with an empty value is equivalent to a non-existing label.
+- If the related queue is specific to a worker, it also has the `worker` label.
+- If there is no information about the worker of the driver, it has the `abandoned=true` label.
+
+For example:
+
+```shell
+syslog-ng-ctl stats prometheus
+```
+
+The output is similar to:
+
+```shell
+syslogng_events_allocated_bytes 18446744073709550560
+syslogng_filtered_events_total{id="#anon-filter0",result="matched"} 0
+syslogng_filtered_events_total{id="#anon-filter0",result="not_matched"} 2
+syslogng_filtered_events_total{id="ff",result="matched"} 0
+syslogng_filtered_events_total{id="ff",result="not_matched"} 2
+syslogng_input_events_total{id="#anon-source0#0",driver_instance="-",result="processed"} 0
+syslogng_input_events_total{id="s_network#1",result="processed"} 2
+syslogng_internal_source{result="dropped"} 0
+syslogng_internal_source{result="queued"} 0
+syslogng_output_events_total{id="d_dest#0",driver_instance="tcp,127.0.0.1:5555",result="delivered"} 0
+syslogng_output_events_total{id="d_dest#0",driver_instance="tcp,127.0.0.1:5555",result="dropped"} 0
+syslogng_output_events_total{id="d_dest#0",driver_instance="tcp,127.0.0.1:5555",result="queued"} 0
+syslogng_output_events_total{id="d_dest#1",driver_instance="http,https://localhost:8080",result="delivered"} 0
+syslogng_output_events_total{id="d_dest#1",driver_instance="http,https://localhost:8080",result="dropped"} 0
+syslogng_output_events_total{id="d_dest#1",driver_instance="http,https://localhost:8080",result="queued"} 0
+syslogng_parsed_events_total{id="#anon-parser0",result="discarded"} 0
+syslogng_parsed_events_total{id="#anon-parser0",result="processed"} 0
+syslogng_scratch_buffers_bytes 0
+syslogng_scratch_buffers_total 3
+syslogng_tagged_events_total{id=".source.#anon-source0",result="processed"} 0
+syslogng_tagged_events_total{id=".source.s_network",result="processed"} 2
+```
+
+## Legacy metrics
+
+You can access the [old statistics]({{< relref "/chapter-log-statistics/_index.md" >}}) of {{% param "product.abbrev" %}} in the new format by running:
+
+```shell
+syslog-ng-ctl stats prometheus --with-legacy-metrics
+```
+
+The output should be similar to:
+
+```shell
+syslogng_src_facility_processed{stat_instance="18"} 0
+syslogng_dst_network_memory_usage{id="d_dest#0",stat_instance="tcp,127.0.0.1:5555"} 0
+syslogng_src_host_processed{id="s_network#1",stat_instance="AnnoW"} 2
+syslogng_global_sdata_updates_processed 0
+syslogng_global_msg_clones_processed 0
+syslogng_global_internal_queue_length_processed 0
+syslogng_global_payload_reallocs_processed 4
+...
+```
+
+For a detailed list of available metrics, see {{% xref "/metrics/reference-metrics/_index.md" %}}.