feat: add config example validation script and workflow by patrick-stephens · Pull Request #2627 · fluent/fluent-bit-docs

patrick-stephens · 2026-07-17T14:56:02Z

Resolves #2459 by providing a simple AWK based approach to validating configuration examples:

We extract config using AWK searching for the Gitbook specific tags
We use the container image to then --dry-run the configuration and report success/failure
We repeat this for every example in the same file as there may be multiple ones.

A local script is provided that can be run for any file in the repo or all of them:

find . -type f -iname "*.md" | while read -r file; do ./scripts/test-config.sh $file; done

A workflow is provided to run this for any files changed in a PR so if an update is made to documentation it should check it is valid.

There is a basic suppression approach by file as there are some valid reasons for this:

Windows-specific plugins will fail in the container image
Some plugins, e.g. exec are not part of the container image
Some examples show loading custom WASM, LUA, Golang, etc. which is not available or easy to do in CI

As part of these changes we also found failures in existing files that were resolved.
Some tweaks were also required, e.g. parser definition must be in a separate file for legacy TOML config so it was updated to be a comment for the examples (which would be rejected anyway otherwise).

There are options to use something more complex like markdown-tree or similar to build an AST from the Markdown file to then pull out the bits we need but this may not work with the specific Gitbook format anyway and requires a whole load of extra dependencies.

Currently there is an upstream failure with certain plugins triggering a segmentation fault for --dry-run: fluent/fluent-bit#12113

pipeline/outputs/azure_blob.md
pipeline/outputs/nats.md
pipeline/outputs/kafka-rest-proxy.md
This is resolved by plugins: fix dry-run segmentation faults fluent-bit#12114 so waiting on that to merge.

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

coderabbitai · 2026-07-17T14:56:14Z

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9daba772-fcd9-4d5d-81a8-95574c907bdb

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch 2459_auto_validate_config_examples

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

github-actions · 2026-07-19T15:28:49Z

+Validates all Fluent Bit configuration examples in Markdown files by running them through `fluent-bit --dry-run`.
+
+**Usage:**
+```bash


[markdownlint] _{reported by reviewdog 🐶}
error MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```bash"]

github-actions · 2026-07-19T15:28:49Z

+This approach ensures that extraction errors are always legitimate—never due to reaching the end of examples. Any extraction error indicates a genuine problem with the file structure.
+
+**Features:**
+- Supports multiple examples per Markdown file (processes all examples)


[markdownlint] _{reported by reviewdog 🐶}
error MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Supports multiple examples p..."]

github-actions · 2026-07-19T15:28:49Z

+- Only reports errors that are legitimate (malformed examples or configuration issues)
+
+**Example - validate a single file:**
+```bash


[markdownlint] _{reported by reviewdog 🐶}
error MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```bash"]

github-actions · 2026-07-19T15:28:49Z

+```
+
+**Example - validate all documentation files:**
+```bash


[markdownlint] _{reported by reviewdog 🐶}
error MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```bash"]

github-actions · 2026-07-19T15:28:49Z

+Extracts Fluent Bit configuration code blocks from Markdown files. This is used internally by `test-config.sh` but can also be called directly.
+
+**Usage:**
+```bash


[markdownlint] _{reported by reviewdog 🐶}
error MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```bash"]

github-actions · 2026-07-19T15:28:49Z

+```
+
+**Parameters:**
+- `markdown-file`: Path to the Markdown file


[markdownlint] _{reported by reviewdog 🐶}
error MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- markdown-file: Path to the..."]

github-actions · 2026-07-19T15:28:57Z

+Validates all Fluent Bit configuration examples in Markdown files by running them through `fluent-bit --dry-run`.
+
+**Usage:**
+```bash


[markdownlint-fix] _{reported by reviewdog 🐶}

Suggested change

```bash

```bash

github-actions · 2026-07-19T15:28:57Z

+This approach ensures that extraction errors are always legitimate—never due to reaching the end of examples. Any extraction error indicates a genuine problem with the file structure.
+
+**Features:**
+- Supports multiple examples per Markdown file (processes all examples)


[markdownlint-fix] _{reported by reviewdog 🐶}

Suggested change

- Supports multiple examples per Markdown file (processes all examples)

- Supports multiple examples per Markdown file (processes all examples)

github-actions · 2026-07-19T15:28:57Z

+- Only reports errors that are legitimate (malformed examples or configuration issues)
+
+**Example - validate a single file:**
+```bash


[markdownlint-fix] _{reported by reviewdog 🐶}

Suggested change

```bash

```bash

github-actions · 2026-07-19T15:28:57Z

+```
+
+**Example - validate all documentation files:**
+```bash


[markdownlint-fix] _{reported by reviewdog 🐶}

Suggested change

```bash

```bash

github-actions · 2026-07-19T15:28:57Z

+Extracts Fluent Bit configuration code blocks from Markdown files. This is used internally by `test-config.sh` but can also be called directly.
+
+**Usage:**
+```bash


[markdownlint-fix] _{reported by reviewdog 🐶}

Suggested change

```bash

```bash

github-actions · 2026-07-19T15:28:57Z

+```
+
+**Parameters:**
+- `markdown-file`: Path to the Markdown file


[markdownlint-fix] _{reported by reviewdog 🐶}

Suggested change

- `markdown-file`: Path to the Markdown file

- `markdown-file`: Path to the Markdown file

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

…in TOML format Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

github-actions · 2026-07-19T15:53:11Z

+- `index|count` (Optional): Extract a specific example by index, or use `count` to get the total number of examples. Defaults to 1 (first example)
+
+**Features:**
+- Automatically removes common leading indentation from extracted examples


[markdownlint] _{reported by reviewdog 🐶}
error MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Automatically removes common..."]

github-actions · 2026-07-19T15:53:11Z

+- Preserves relative indentation within the configuration
+
+**Examples:**
+```bash


[markdownlint] _{reported by reviewdog 🐶}
error MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```bash"]

github-actions · 2026-07-19T15:53:11Z

+**Count mode:**
+
+The `count` parameter returns the total number of matching code fences for the specified language in the given tab. This is used by `test-config.sh` to:
+1. Determine how many examples to validate


[markdownlint] _{reported by reviewdog 🐶}
error MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "1. Determine how many examples..."]

github-actions · 2026-07-19T15:53:11Z

+3. Ensure all extraction errors are legitimate
+
+Example output:
+```bash


[markdownlint] _{reported by reviewdog 🐶}
error MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```bash"]

github-actions · 2026-07-19T15:53:11Z

+```yaml
+service:
+  flush: 1
+```


[markdownlint] _{reported by reviewdog 🐶}
error MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```"]

github-actions · 2026-07-19T15:53:12Z

+{% tab title="fluent-bit.yaml" %}
+```yaml
+# First example YAML
+```


[markdownlint] _{reported by reviewdog 🐶}
error MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```"]

github-actions · 2026-07-19T15:53:12Z

+
+{% tabs %}
+{% tab title="fluent-bit.yaml" %}
+```yaml


[markdownlint] _{reported by reviewdog 🐶}
error MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```yaml"]

github-actions · 2026-07-19T15:53:12Z

+{% tab title="fluent-bit.yaml" %}
+```yaml
+# Second example YAML
+```


[markdownlint] _{reported by reviewdog 🐶}
error MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```"]

github-actions · 2026-07-19T15:53:12Z

+```
+{% endtab %}
+{% endtabs %}
+```


[markdownlint] _{reported by reviewdog 🐶}
error MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```"]

github-actions · 2026-07-19T15:53:12Z

+```
+{% endtab %}
+{% endtabs %}
+```


[markdownlint] _{reported by reviewdog 🐶}
error MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]

github-actions · 2026-07-19T15:53:27Z

+- `index|count` (Optional): Extract a specific example by index, or use `count` to get the total number of examples. Defaults to 1 (first example)
+
+**Features:**
+- Automatically removes common leading indentation from extracted examples


[markdownlint-fix] _{reported by reviewdog 🐶}

Suggested change

- Automatically removes common leading indentation from extracted examples

- Automatically removes common leading indentation from extracted examples

github-actions · 2026-07-19T15:53:27Z

+- Preserves relative indentation within the configuration
+
+**Examples:**
+```bash


[markdownlint-fix] _{reported by reviewdog 🐶}

Suggested change

```bash

```bash

github-actions · 2026-07-19T15:53:27Z

+**Count mode:**
+
+The `count` parameter returns the total number of matching code fences for the specified language in the given tab. This is used by `test-config.sh` to:
+1. Determine how many examples to validate


[markdownlint-fix] _{reported by reviewdog 🐶}

Suggested change

1. Determine how many examples to validate

1. Determine how many examples to validate

github-actions · 2026-07-19T15:53:27Z

+3. Ensure all extraction errors are legitimate
+
+Example output:
+```bash


[markdownlint-fix] _{reported by reviewdog 🐶}

Suggested change

```bash

```bash

github-actions · 2026-07-19T15:53:27Z

+service:
+  flush: 1
+```
+{% endtab %}


[markdownlint-fix] _{reported by reviewdog 🐶}

Suggested change

{% endtab %}

{% endtab %}

github-actions · 2026-07-19T15:53:28Z

+```
+{% endtab %}
+{% endtabs %}
+```


[markdownlint-fix] _{reported by reviewdog 🐶}

Suggested change

```

```

github-actions · 2026-07-19T15:53:28Z

+```yaml
+# First example YAML
+```
+{% endtab %}


[markdownlint-fix] _{reported by reviewdog 🐶}

Suggested change

{% endtab %}

{% endtab %}

github-actions · 2026-07-19T15:53:28Z

+
+{% tabs %}
+{% tab title="fluent-bit.yaml" %}
+```yaml


[markdownlint-fix] _{reported by reviewdog 🐶}

Suggested change

```yaml

```yaml

github-actions · 2026-07-19T15:53:28Z

+```yaml
+# Second example YAML
+```
+{% endtab %}


[markdownlint-fix] _{reported by reviewdog 🐶}

Suggested change

{% endtab %}

{% endtab %}

github-actions · 2026-07-19T15:53:28Z

+```
+{% endtab %}
+{% endtabs %}
+```


[markdownlint-fix] _{reported by reviewdog 🐶}

Suggested change

```

```

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

feat: add config example validation script and workflow

f84fcb0

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

patrick-stephens added 13 commits July 19, 2026 15:40

fix: suppress known failures due to unrelated Fluent Bit issue 12113

d7e030b

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

fix: resolve incorrect syntax in parsers configuration

a59ef51

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

fix: missing quote for dummy config in geoip filter

e9c40c5

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

fix: incorrect comment format used in buffering examples

f8fa2d4

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

fix: naming of parser files

8123602

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

fix: incorrect format and quoting for dynatrace

e509bf9

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

fix: remove redundant and incorrect parser definition for gelf output

06cf0c6

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

fix: rename tab titles to match usage for containers

cdfbefe

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

fix: use correct language block for legacy config in cpu-metrics input

0f4b0ca

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

fix: remove tab for conditional processing YAML definition block

68c4681

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

fix: suppress known failures due to Windows kubelet config

55ff47d

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

feat: add multi-example validation

b8c6b37

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

fix: additional failures in tail examples

fb03366

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

github-actions Bot reviewed Jul 19, 2026

View reviewed changes

patrick-stephens mentioned this pull request Jul 19, 2026

alias: handle input, output, filter, and processor plugin aliases fluent/fluent-bit#11656

Open

7 tasks

patrick-stephens added 4 commits July 19, 2026 16:41

fix: incorrect elasticsearch output name used in routing

c5fa192

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

fix: resolve routing examples

988fe3a

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

fix: resolve loki examples

d58da9f

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

feat: remove common leading indentation to prevent spurious failures …

e3e9faf

…in TOML format Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

github-actions Bot reviewed Jul 19, 2026

View reviewed changes

feat: support configurable image

56630f1

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

patrick-stephens force-pushed the 2459_auto_validate_config_examples branch from ba1f42c to 56630f1 Compare July 19, 2026 15:58

fix: resolve sql indentiation issue

ef5f2fc

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

patrick-stephens added 5 commits July 19, 2026 17:03

fix: resolve missing AVRO support in release FB for Kafka

05b8b5d

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

fix: resolve s3 examples

7d51e3b

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

fix: resolve lua in kafka examples

cab9c94

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

fix: resolve quoting for blob input

d5268dc

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

fix: resolve examples for K8S filter

8d1ea3b

Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

	- Supports multiple examples per Markdown file (processes all examples)

	- Supports multiple examples per Markdown file (processes all examples)

	- `markdown-file`: Path to the Markdown file

	- `markdown-file`: Path to the Markdown file

	- Automatically removes common leading indentation from extracted examples

	- Automatically removes common leading indentation from extracted examples

	1. Determine how many examples to validate

	1. Determine how many examples to validate

Uh oh!

Conversation

patrick-stephens commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 19, 2026

Choose a reason for hiding this comment

patrick-stephens commented Jul 17, 2026 •

edited

Loading

coderabbitai Bot commented Jul 17, 2026 •

edited

Loading