Skip to content

Commit 4438b9c

Browse files
drbugfinder-workedsiper
drbugfinder-work
authored and
edsiper
committed
filter_log_to_metrics: Log To Metrics Filter Plugin Documentation
Documentation for the new fluent/fluent-bit#6674 Log Metrics Filter Plugin Signed-off-by: Richard Treu <[email protected]>
1 parent 7dbd808 commit 4438b9c

File tree

1 file changed

+154
-0
lines changed

1 file changed

+154
-0
lines changed

‎pipeline/filters/log-to-metrics.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
description: Generate metrics from logs
3+
---
4+
5+
# Log To Metrics
6+
7+
The _Log To Metrics Filter_ plugin allows you to generate log-derived metrics. It currently supports modes to count records, sum up field values over a record stream or provide a gauge for field values. You can also match or exclude specific records based on regular expression patterns for values or nested values. This filter plugin does not actually act as a record filter and does not change or drop records. All records will pass this filter untouched and generated metrics will be emitted into a seperate metric pipeline.
8+
9+
_Please note that this plugin is an experimental feature and is not recommended for production use. Configuration parameters and plugin functionality are subject to change without notice._
10+
11+
12+
## Configuration Parameters
13+
14+
The plugin supports the following configuration parameters:
15+
16+
| Key | Description | Mandatory | Value Format
17+
| :--- | :--- | :--- | :---
18+
| tag | Defines the tag for the generated metrics record| Yes | |
19+
| metric_mode | Defines the mode for the metric. Valid values are [`counter`, `sum` or `gauge`] | Yes | |
20+
| metric_name | Sets the name of the metric. | Yes | |
21+
| metric_description | Sets a help text for the metric. | Yes | |
22+
| label_field | Includes a record field as label dimension in the metric. | | Name of record key. Supports [Record Accessor](../../administration/configuring-fluent-bit/classic-mode/record-accessor.md) notation for nested fields.
23+
| value_field | Specify the record field that holds a numerical value to either sum up or take as most recent value | Yes, for modes [`sum` and `gauge`] | Name of record key. Supports [Record Accessor](../../administration/configuring-fluent-bit/classic-mode/record-accessor.md) notation for nested fields.
24+
| kubernetes_mode | If enabled, it will automatically put pod_id, pod_name, namespace_name, docker_id and container_name into the metric as labels. This option is intended to be used in combination with the [kubernetes](./kubernetes.md) filter plugin, which fills those fields. | |
25+
| Regex | Include records in which the content of KEY matches the regular expression. | | KEY REGEX
26+
| Exclude | Exclude records in which the content of KEY matches the regular expression. | | KEY REGEX
27+
28+
## Getting Started
29+
30+
The following example takes records from two dummy inputs and counts all messages passing through the `log_to_metrics` filter. It then generates metric records which are provided to the `prometheus_exporter`:
31+
32+
### Configuration - Counter
33+
34+
```python
35+
[SERVICE]
36+
flush 1
37+
log_level info
38+
39+
[INPUT]
40+
Name dummy
41+
Dummy {"message":"dummy", "kubernetes":{"namespace_name": "default", "docker_id": "abc123", "pod_name": "pod1", "container_name": "mycontainer", "pod_id": "def456"}, "duration": 20, "color": "red", "shape": "circle"}
42+
Tag dummy.log
43+
44+
[INPUT]
45+
Name dummy
46+
Dummy {"message":"hello", "kubernetes":{"namespace_name": "default", "docker_id": "abc123", "pod_name": "pod1", "container_name": "mycontainer", "pod_id": "def456"}, "duration": 60, "color": "blue", "shape": "square"}
47+
Tag dummy.log2
48+
49+
[FILTER]
50+
name log_to_metrics
51+
match dummy.log*
52+
tag test_metric
53+
metric_mode counter
54+
metric_name count_all_dummy_messages
55+
metric_description This metric counts dummy messages
56+
57+
[OUTPUT]
58+
name prometheus_exporter
59+
match *
60+
host 0.0.0.0
61+
port 2021
62+
```
63+
64+
You can then use e.g. curl command to retrieve the generated metric:
65+
```text
66+
> curl -s http://127.0.0.1:2021/metrics
67+
68+
69+
# HELP log_metric_counter_count_all_dummy_messages This metric counts dummy messages
70+
# TYPE log_metric_counter_count_all_dummy_messages counter
71+
log_metric_counter_count_all_dummy_messages 49
72+
```
73+
74+
### Configuration - Sum
75+
76+
If you want to sum up values within a record and provide the result as a metric, you have to specify a `value_field` to sum up. In this example we also add two labels via the `label_field` options:
77+
```python
78+
[FILTER]
79+
name log_to_metrics
80+
match dummy.log*
81+
tag test_metric
82+
metric_mode sum
83+
metric_name sum_up_durations
84+
metric_description This metric sums up duration field values
85+
value_field duration
86+
label_field color
87+
label_field shape
88+
```
89+
90+
You can then use e.g. curl command to retrieve the generated metric:
91+
```text
92+
> curl -s http://127.0.0.1:2021/metrics
93+
94+
95+
# HELP log_metric_counter_sum_up_durations This metric sums up duration field values
96+
# TYPE log_metric_counter_sum_up_durations counter
97+
log_metric_counter_sum_up_durations{color="red",shape="circle"} 400
98+
log_metric_counter_sum_up_durations{color="blue",shape="square"} 1140
99+
```
100+
#### Metric label_values
101+
As you can see, the label sets defined by `label_field` are added to the metric. The lines in the metric represent every combination of labels. Only actually used combinations are displayed here. To see this, you can add a third `dummy` input (with "color": "blue") to your configuration:
102+
103+
```python
104+
[INPUT]
105+
Name dummy
106+
Dummy {"message":"dummy", "kubernetes":{"namespace_name": "default", "docker_id": "abc123", "pod_name": "pod1", "container_name": "mycontainer", "pod_id": "def456"}, "duration": 20, "color": "blue", "shape": "circle"}
107+
Tag dummy.log
108+
```
109+
110+
The metric output would then look like:
111+
```text
112+
> curl -s http://127.0.0.1:2021/metrics
113+
114+
# HELP log_metric_counter_sum_up_durations This metric sums up duration field values
115+
# TYPE log_metric_counter_sum_up_durations counter
116+
log_metric_counter_sum_up_durations{color="red",shape="circle"} 140
117+
log_metric_counter_sum_up_durations{color="blue",shape="circle"} 120
118+
log_metric_counter_sum_up_durations{color="blue",shape="square"} 360
119+
```
120+
121+
### Configuration - Gauge
122+
123+
Similar to the `sum` mode, `gauge` needs a `value_field` specified, where the current metric values are generated from. In this example we also apply a regex filter and enable the `kubernetes_mode` option:
124+
```python
125+
[FILTER]
126+
name log_to_metrics
127+
match dummy.log*
128+
tag test_metric
129+
metric_mode gauge
130+
metric_name current_duration
131+
metric_description This metric shows the current duration
132+
value_field duration
133+
kubernetes_mode on
134+
regex message .*el.*
135+
label_field color
136+
label_field shape
137+
```
138+
You can then use e.g. curl command to retrieve the generated metric:
139+
```text
140+
> curl -s http://127.0.0.1:2021/metrics
141+
142+
143+
# HELP log_metric_gauge_current_duration This metric shows the current duration
144+
# TYPE log_metric_gauge_current_duration gauge
145+
log_metric_gauge_current_duration{namespace_name="default",pod_name="pod1",container_name="mycontainer",docker_id="abc123",pod_id="def456",color="blue",shape="square"} 60
146+
```
147+
148+
As you can see in the output, only one line is printed, as the records from the first input plugin are ignored, as they do not match the regex.
149+
150+
The filter also allows to use multiple rules which are applied in order, you can have many _Regex_ and _Exclude_ entries as required (see [grep](./grep.md) filter plugin).
151+
152+
If you execute the above `curl` command multiple times, you see, that in this example the metric value stays at `60`, as the messages generated by the dummy plugin are not changing. In a real-world scenario the values would change and return the last processed value.
153+
154+
You can also see, that all the kubernetes labels have been attached to the metric, idential to the behavior of `label_field` described in [the previous chapter](#metric-label_values)

0 commit comments

Comments
 (0)