Skip to content

Commit 4f4e758

Browse files
authored
Merge pull request #1690 from fluent/lynettemiles/sc-136153/update-fluent-bit-docs-pipeline-filters-multiline
2 parents 2604a02 + 49e3b0d commit 4f4e758

File tree

1 file changed

+51
-51
lines changed

1 file changed

+51
-51
lines changed

pipeline/filters/multiline-stacktrace.md

Lines changed: 51 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,73 +1,67 @@
11
---
2-
description: >-
3-
Concatenate Multiline or Stack trace log messages. Available on Fluent Bit >=
2+
description: Concatenate multiline or stack trace log messages. Available on Fluent Bit >=
43
v1.8.2.
54
---
65

76
# Multiline
87

9-
The Multiline Filter helps to concatenate messages that originally belong to one context but were split across multiple records or log lines. Common examples are stack traces or applications that print logs in multiple lines.
8+
The Multiline filter helps concatenate messages that originally belonged to one context but were split across multiple records or log lines. Common examples are stack traces or applications that print logs in multiple lines.
109

11-
As part of the built-in functionality, without major configuration effort, you can enable one of ours built-in parsers with auto detection and multi format support:
10+
Along with multiline filters, you can enable one of the following built-in Fluent Bit parsers with auto detection and multi-format support:
1211

13-
* go
14-
* python
15-
* ruby
16-
* java (Google Cloud Platform Java stacktrace format)
12+
- Go
13+
- Python
14+
- Ruby
15+
- Java (Google Cloud Platform Java stack trace format)
1716

18-
Some comments about this filter:
17+
When using this filter:
1918

20-
* The usage of this filter depends on a previous configuration of a [Multiline Parser](../../administration/configuring-fluent-bit/multiline-parsing.md) definition.
21-
* If you wish to concatenate messages read from a log file, it is highly recommended to use the multiline support in the [Tail plugin](https://docs.fluentbit.io/manual/pipeline/inputs/tail#multiline-support) itself. This is because performing concatenation while reading the log file is more performant. Concatenating messages originally split by Docker or CRI container engines, is supported in the [Tail plugin](https://docs.fluentbit.io/manual/pipeline/inputs/tail#multiline-support).
19+
- The usage of this filter depends on a previous configuration of a [multiline parser](../../administration/configuring-fluent-bit/multiline-parsing.md) definition.
20+
- To concatenate messages read from a log file, it's highly recommended to use the multiline support in the [Tail plugin](https://docs.fluentbit.io/manual/pipeline/inputs/tail#multiline-support) itself. This is because performing concatenation while reading the log file is more performant. Concatenating messages originally split by Docker or CRI container engines, is supported in the [Tail plugin](https://docs.fluentbit.io/manual/pipeline/inputs/tail#multiline-support).
2221

2322
{% hint style="warning" %}
24-
This filter only performs buffering that persists across different Chunks when `Buffer` is enabled. Otherwise, the filter will *process one Chunk at a time* and is not suitable for most inputs which might send multiline messages in separate chunks.
23+
This filter only performs buffering that persists across different Chunks when `Buffer` is enabled. Otherwise, the filter processes one chunk at a time and isn't suitable for most inputs which might send multiline messages in separate chunks.
2524

26-
When buffering is enabled, the filter does not immediately emit messages it receives. It uses the in_emitter plugin, same as the [Rewrite Tag Filter](pipeline/filters/rewrite-tag.md), and emits messages once they are fully concatenated, or a timeout is reached.
25+
When buffering is enabled, the filter doesn't immediately emit messages it receives. It uses the `in_emitter` plugin, similar to the [Rewrite Tag filter](pipeline/filters/rewrite-tag.md), and emits messages once they're fully concatenated, or a timeout is reached.
2726

2827
{% endhint %}
2928

3029
{% hint style="warning" %}
3130

3231
Since concatenated records are re-emitted to the head of the Fluent Bit log pipeline, you can not configure multiple multiline filter definitions that match the same tags. This will cause an infinite loop in the Fluent Bit pipeline; to use multiple parsers on the same logs, configure a single filter definitions with a comma separated list of parsers for `multiline.parser`. For more, see issue [#5235](https://github.com/fluent/fluent-bit/issues/5235).
3332

34-
Secondly, for the same reason, the multiline filter should be the **first** filter. Logs will be re-emitted by the multiline filter to the head of the pipeline- the filter will ignore its own re-emitted records, but other filters won't. If there are filters before the multiline filter, they will be applied twice.
33+
Secondly, for the same reason, the multiline filter should be the first filter. Logs will be re-emitted by the multiline filter to the head of the pipeline- the filter will ignore its own re-emitted records, but other filters won't. If there are filters before the multiline filter, they will be applied twice.
3534

3635
{% endhint %}
3736

38-
## Configuration Parameters
37+
## Configuration parameters
3938

4039
The plugin supports the following configuration parameters:
4140

42-
| Property | Description |
43-
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
44-
| multiline.parser | Specify one or multiple [Multiline Parser definitions](../../administration/configuring-fluent-bit/multiline-parsing.md) to apply to the content. You can specify multiple multiline parsers to detect different formats by separating them with a comma. |
45-
| multiline.key_content | Key name that holds the content to process. Note that a Multiline Parser definition can already specify the `key_content` to use, but this option allows to overwrite that value for the purpose of the filter. |
46-
| mode | Mode can be `parser` for regex concat, or `partial_message` to concat split docker logs. |
47-
| buffer | Enable buffered mode. In buffered mode, the filter can concatenate multilines from inputs that ingest records one by one (ex: Forward), rather than in chunks, re-emitting them into the beggining of the pipeline (with the same tag) using the in_emitter instance. With buffer off, this filter will not work with most inputs, except tail. |
48-
| flush_ms | Flush time for pending multiline records. Defaults to 2000. |
49-
| emitter_name | Name for the emitter input instance which re-emits the completed records at the beginning of the pipeline. |
50-
| emitter_storage.type | The storage type for the emitter input instance. This option supports the values `memory` \(default\) and `filesystem`. |
51-
| emitter\_mem\_buf\_limit | Set a limit on the amount of memory the emitter can consume if the outputs provide backpressure. The default for this limit is `10M`. The pipeline will pause once the buffer exceeds the value of this setting. For example, if the value is set to `10M` then the pipeline will pause if the buffer exceeds `10M`. The pipeline will remain paused until the output drains the buffer below the `10M` limit. |
41+
| Property | Description |
42+
| -------- | ----------- |
43+
| `multiline.parser` | Specify one or multiple [Multiline Parser definitions](../../administration/configuring-fluent-bit/multiline-parsing.md) to apply to the content. You can specify multiple multiline parsers to detect different formats by separating them with a comma. |
44+
| `multiline.key_content` | Key name that holds the content to process. A multiline parser definition can specify the `key_content` This option allows for overwriting that value for the purpose of the filter. |
45+
| `mode` | Mode can be `parser` for regular expression concatenation, or `partial_message` to concatenate split Docker logs. |
46+
| `buffer` | Enable buffered mode. In buffered mode, the filter can concatenate multiple lines from inputs that ingest records one by one (like Forward), rather than in chunks, re-emitting them into the beginning of the pipeline (with the same tag) using the `in_emitter` instance. With buffer off, this filter won't work with most inputs, except Tail. |
47+
| `flush_ms` | Flush time for pending multiline records. Default: `2000`. |
48+
| `emitter_name` | Name for the emitter input instance which re-emits the completed records at the beginning of the pipeline. |
49+
| `emitter_storage.type` | The storage type for the emitter input instance. This option supports the values `memory` (default) and `filesystem`. |
50+
| `emitter_mem_buf_limit` | Set a limit on the amount of memory the emitter can consume if the outputs provide backpressure. The default for this limit is `10M`. The pipeline will pause once the buffer exceeds the value of this setting. or example, if the value is set to `10M` then the pipeline pauses if the buffer exceeds `10M`. The pipeline will remain paused until the output drains the buffer below the `10M` limit. |
5251

52+
## Configuration example
5353

54-
## Configuration Example
54+
The following example aims to parse a log file called `test.log` that contains some full lines, a custom Java stack trace and a Go Stack Trace.
5555

56-
The following example aims to parse a log file called `test.log` that contains some full lines, a custom Java stacktrace and a Go stacktrace.
57-
58-
{% hint style="info" %}
59-
The following example files can be located at:\
60-
\
61-
[https://github.com/fluent/fluent-bit/tree/master/documentation/examples/multiline/filter_multiline](https://github.com/fluent/fluent-bit/tree/master/documentation/examples/multiline/filter_multiline)
62-
{% endhint %}
56+
The following example files can be located [in the Fluent Bit repository](https://github.com/fluent/fluent-bit/tree/master/documentation/examples/multiline/filter_multiline).
6357

6458
Example files content:
6559

6660
{% tabs %}
6761
{% tab title="fluent-bit.conf" %}
68-
This is the primary Fluent Bit configuration file. It includes the `parsers_multiline.conf` and tails the file `test.log` by applying the multiline parsers `multiline-regex-test` and `go`. Then it sends the processing to the standard output.
62+
This is the primary Fluent Bit configuration file. It includes the `parsers_multiline.conf` and tails the file `test.log` by applying the multiline parsers `multiline-regex-test` and `go`. Then it sends the processing to the standard output.
6963

70-
```
64+
```python
7165
[SERVICE]
7266
flush 1
7367
log_level info
@@ -87,14 +81,15 @@ This is the primary Fluent Bit configuration file. It includes the `parsers_mult
8781
[OUTPUT]
8882
name stdout
8983
match *
90-
84+
9185
```
86+
9287
{% endtab %}
9388

9489
{% tab title="parsers_multiline.conf" %}
95-
This second file defines a multiline parser for the example. Note that a second multiline parser called `go` is used in **fluent-bit.conf**, but this one is a built-in parser.
90+
This second file defines a multiline parser for the example. A second multiline parser called `go` is used in `fluent-bit.conf`, but this one is a built-in parser.
9691

97-
```
92+
```python
9893
[MULTILINE_PARSER]
9994
name multiline-regex-test
10095
type regex
@@ -112,14 +107,15 @@ This second file defines a multiline parser for the example. Note that a second
112107
# ------|---------------|--------------------------------------------
113108
rule "start_state" "/([A-Za-z]+ \d+ \d+\:\d+\:\d+)(.*)/" "cont"
114109
rule "cont" "/^\s+at.*/" "cont"
115-
110+
116111
```
112+
117113
{% endtab %}
118114

119115
{% tab title="test.log" %}
120-
An example file with multiline and multiformat content:
116+
An example file with multiline and multi-format content:
121117

122-
```
118+
```text
123119
single line...
124120
Dec 14 06:41:08 Exception in thread "main" java.lang.RuntimeException: Something has gone wrong, aborting!
125121
at com.myproject.module.MyProject.badMethod(MyProject.java:22)
@@ -182,14 +178,19 @@ created by runtime.gcenable
182178
one more line, no multiline
183179
184180
```
181+
185182
{% endtab %}
186183
{% endtabs %}
187184

188-
By running Fluent Bit with the given configuration file you will obtain:
185+
Running Fluent Bit with the given configuration file:
189186

187+
```shell
188+
fluent-bit -c fluent-bit.conf
190189
```
191-
$ fluent-bit -c fluent-bit.conf
192190

191+
Should return something like the following:
192+
193+
```text
193194
[0] tail.0: [1626736433.143567481, {"log"=>"single line..."}]
194195
[1] tail.0: [1626736433.143570538, {"log"=>"Dec 14 06:41:08 Exception in thread "main" java.lang.RuntimeException: Something has gone wrong, aborting!
195196
at com.myproject.module.MyProject.badMethod(MyProject.java:22)
@@ -253,25 +254,24 @@ created by runtime.gcenable
253254
254255
```
255256

256-
The lines that did not match a pattern are not considered as part of the multiline message, while the ones that matched the rules were concatenated properly.
257+
Lines that don't match a pattern aren't considered as part of the multiline message, while the ones that matched the rules were concatenated properly.
257258

259+
## Docker partial message use case
258260

259-
## Docker Partial Message Use Case
261+
When Fluent Bit is consuming logs from a container runtime, such as Docker, these logs will be split when larger than a certain limit, usually 16KB. If your application emits a 100K log line, it will be split into seven partial messages. If you are using the [Fluentd Docker Log Driver](https://docs.docker.com/config/containers/logging/fluentd/) to send the logs to Fluent Bit, they might look like this:
260262

261-
When Fluent Bit is consuming logs from a container runtime, such as docker, these logs will be split above a certain limit, usually 16KB. If your application emits a 100K log line, it will be split into 7 partial messages. If you are using the [Fluentd Docker Log Driver](https://docs.docker.com/config/containers/logging/fluentd/) to send the logs to Fluent Bit, they might look like this:
262-
263-
```
263+
```text
264264
{"source": "stdout", "log": "... omitted for brevity...", "partial_message": "true", "partial_id": "dc37eb08b4242c41757d4cd995d983d1cdda4589193755a22fcf47a638317da0", "partial_ordinal": "1", "partial_last": "false", "container_id": "a96998303938eab6087a7f8487ca40350f2c252559bc6047569a0b11b936f0f2", "container_name": "/hopeful_taussig"}]
265265
```
266266

267-
Fluent Bit can re-combine these logs that were split by the runtime and remove the partial message fields. The filter example below is for this use case.
267+
Fluent Bit can re-combine these logs that were split by the runtime and remove the partial message fields. The following filter example is for this use case.
268268

269-
```
269+
```python
270270
[FILTER]
271271
name multiline
272272
match *
273273
multiline.key_content log
274274
mode partial_message
275275
```
276276

277-
The two options for `mode` are mutually exclusive in the filter. If you set the `mode` to `partial_message` then the `multiline.parser` option is not allowed.
277+
The two options for `mode` are mutually exclusive in the filter. If you set the `mode` to `partial_message` then the `multiline.parser` option isn't allowed.

0 commit comments

Comments
 (0)