feat: add config example validation script and workflow

.github/workflows/pr-example-validation.yaml

@@ -0,0 +1,76 @@
+name: Validate example configurations in PRs
+
+on:
+  pull_request:
+    paths:
+      - '**/*.md'
+
+permissions: {}
+
+# Avoid multiple commits on the same PR racing to update the comment.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  validate-configs:
+    name: Validate example configurations in changed Markdown files
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Get changed Markdown files
+        # We do not use the usual changed files action because of previous security issues.
+        id: changed_files
+        # This complex command finds files changed in the PR, filtering for `.md` and also ensuring they are in the `docs` directory.
+        # It ensures we only process files that are part of the PR and match our pattern.
+        # Note: The `github.event.pull_request.base.sha` is used to get the base commit of the PR, which is important for accurate diffing.
+        #
+        # On pull requests, HEAD refers to the merge commit.
+        # We want to compare against the base of the PR.
+        # Use git diff to get files changed between the PR base and the current commit.
+        # --name-only lists only the names of the files.
+        # --diff-filter=AMCR will only show Added, Modified, Copied, Renamed files.
+        # We grep for *.md files you are interested in.
+        # The 'docs/' prefix is a common convention but adjust as necessary.
+        run: |
+          changed_md=$(git diff --name-only --diff-filter=AMCR ${{ github.event.pull_request.base.sha }}...HEAD | grep '\.md$' || true)
+          echo "Changed Markdown files: $changed_md"
+          # The value is newline-separated, so it needs the multiline output delimiter syntax.
+          # A random delimiter avoids any chance of the value terminating the block early.
+          delimiter=$(openssl rand -hex 16)
+          {
+            echo "list<<${delimiter}"
+            echo "${changed_md}"
+            echo "${delimiter}"
+          } >> "$GITHUB_OUTPUT"
+        shell: bash
+
+      - name: Validate example configurations provided in any changed files
+        run: |
+          if [ -z "${CHANGED_MD_FILES:-}" ]; then
+            echo "No Markdown files changed in this PR. Skipping validation."
+            exit 0
+          fi
+
+          error_count=0
+
+          # Loop through each changed file
+          for FILE in $CHANGED_MD_FILES; do
+            echo "Processing changed file: $FILE"
+            ./scripts/test-config.sh "$FILE" || error_count=$((error_count + 1))
+          done
+
+          if [ $error_count -ne 0 ]; then
+            echo "ERROR: Validation failed for $error_count file(s)."
+            exit 1
+          fi
+        shell: bash
+        env:
+          CHANGED_MD_FILES: ${{ steps.changed_files.outputs.list }}

installation/downloads/docker.md

@@ -15,7 +15,7 @@ docker run -ti cr.fluentbit.io/fluent/fluent-bit
 Use the following command to start Fluent Bit while using a configuration file:
 
 {% tabs %}
-{% tab title="fluent-bit.conf" %}
+{% tab title="Legacy Configuration: fluent-bit.conf" %}
 
 ```shell
 docker run -ti -v ./fluent-bit.conf:/fluent-bit/etc/fluent-bit.conf \
@@ -24,7 +24,7 @@ docker run -ti -v ./fluent-bit.conf:/fluent-bit/etc/fluent-bit.conf \
 
 {% endtab %}
 
-{% tab title="fluent-bit.yaml" %}
+{% tab title="YAML configuration: fluent-bit.yaml" %}
 
 ```shell
 docker run -ti -v ./fluent-bit.yaml:/fluent-bit/etc/fluent-bit.yaml \
@@ -303,7 +303,7 @@ The reasons for using distroless are well covered in
 - Reduces false positives on scans (and reduces resources required for scanning).
 - Reduces supply chain security requirements to only what you need.
 - Helps prevent unauthorised processes or users interacting with the container.
-- Less need to harden the container (and container runtime, K8s, and so on).
+- Less need to harden the container (and container runtime, Kubernetes, and so on).
 - Faster CI/CD processes.
 
 With any choice, there are downsides:

pipeline/buffering.md

@@ -102,7 +102,8 @@ pipeline:
       # Inherits storage.type: filesystem from service
 
     - name: mem
-      storage.type: memory  # Overrides the inherited default
+      # Overrides the inherited default
+      storage.type: memory
 ```
 
 {% endtab %}
@@ -124,7 +125,8 @@ pipeline:
 
 [INPUT]
   Name          mem
-  Storage.Type  memory  # Overrides the inherited default
+  # Overrides the inherited default
+  Storage.Type  memory
 ```
 
 {% endtab %}

pipeline/filters/geoip2-filter.md

@@ -33,7 +33,7 @@ The following configuration processes the incoming `remote_addr` and appends cou
 pipeline:
   inputs:
     - name: dummy
-      dummy: {"remote_addr": "8.8.8.8"}
+      dummy: '{"remote_addr": "8.8.8.8"}'
 
   filters:
     - name: geoip2

pipeline/filters/kubernetes.md

@@ -360,10 +360,11 @@ pipeline:
 {% tab title="fluent-bit.conf" %}
 
 ```text
-[PARSER]
-  Name    custom-tag
-  Format  regex
-  Regex   ^(?<namespace_name>[^_]+)\.(?<pod_name>[a-z0-9](?:[-a-z0-9]*[a-z0-9])?(?:\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*)\.(?<container_name>.+)\.(?<container_id>[a-z0-9]{64})
+# Ensure this is added to parsers_file loaded in the SERVICE section
+# [PARSER]
+#   Name    custom-tag
+#   Format  regex
+#   Regex   ^(?<namespace_name>[^_]+)\.(?<pod_name>[a-z0-9](?:[-a-z0-9]*[a-z0-9])?(?:\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*)\.(?<container_name>.+)\.(?<container_id>[a-z0-9]{64})
 
 [INPUT]
   Name              tail
@@ -488,7 +489,7 @@ pipeline:
       parser: docker
       docker_mode: on
       mem_buf_limit: 50MB
-      skip_login_lines: on
+      skip_long_lines: on
       refresh_interval: 10
 
   filters:

pipeline/filters/parser.md

@@ -16,7 +16,7 @@ The plugin supports the following configuration parameters:
 | `parser` | Specify the parser name to interpret the field. Multiple parser entries are allowed (one per line). | _none_ |
 | `preserve_key` | Keep the original `key_name` field in the parsed result. If false, the field will be removed. | `false` |
 | `reserve_data` | Keep all other original fields in the parsed result. If false, all other original fields will be removed. | `false` |
-| `Unescape_key` | Deprecated. This option is retained only for backward compatibility and should not be used in new configurations. | _deprecated_ |
+| `Unescape_key` | Deprecated. This option is retained only for backward compatibility and shouldn't be used in new configurations. | _deprecated_ |
 
 ## Get started
 
@@ -27,7 +27,7 @@ The plugin needs a parser file which defines how to parse each field.
 This is an example of parsing a record `{"data":"100 0.5 true This is example"}`.
 
 {% tabs %}
-{% tab title="fluent-bit.yaml" %}
+{% tab title="parser.yaml" %}
 
 ```yaml
 parsers:
@@ -37,7 +37,7 @@ parsers:
 ```
 
 {% endtab %}
-{% tab title="fluent-bit.conf" %}
+{% tab title="parser.conf" %}
 
 ```text
 [PARSER]

pipeline/inputs/blob.md

@@ -177,8 +177,8 @@ This example excludes certain file patterns and uses filesystem storage for bett
 pipeline:
   inputs:
     - name: blob
-      path: /data/artifacts/**/*
-      exclude_pattern: *.tmp,*.bak,*.old
+      path: '/data/artifacts/**/*'
+      exclude_pattern: '*.tmp,*.bak,*.old'
       storage.type: filesystem
       storage.pause_on_chunks_overlimit: true
       mem_buf_limit: 50M

pipeline/inputs/cpu-metrics.md

@@ -82,7 +82,7 @@ pipeline:
 {% endtab %}
 {% tab title="fluent-bit.conf" %}
 
-```shell
+```text
 [INPUT]
   Name cpu
   Tag  my_cpu

pipeline/inputs/kafka.md

@@ -95,8 +95,16 @@ pipeline:
   filters:
     - name: lua
       match: '*'
-      script: kafka.lua
       call: modify_kafka_message
+      code: |
+        local count = 0
+        function modify_kafka_message(tag, timestamp, record)
+            count = count + 1
+            local payload = record.payload
+            payload.topic = record.topic
+            payload.status = 'processed by fluent-bit, total records: '..tostring(count)
+            return 1, timestamp, payload
+        end
 
   outputs:
     - name: kafka
@@ -118,8 +126,8 @@ pipeline:
 [FILTER]
   Name    lua
   Match   *
-  Script  kafka.lua
   Call    modify_kafka_message
+  Code    local count = 0 function modify_kafka_message(tag, timestamp, record) count = count + 1 local payload = record.payload payload.topic = record.topic payload.status = 'processed by fluent-bit, total records: '..tostring(count) return 1, timestamp, payload end
 
 [OUTPUT]
   Name    kafka
@@ -134,7 +142,18 @@ The previous example will connect to the broker listening on `kafka-broker:9092`
 
 Since the payload will be in JSON format, the plugin is configured to parse the payload with `format json`.
 
-Every message received is then processed with `kafka.lua` and sent back to the `fb-sink` topic of the same broker.
+Every message received is then processed with `kafka.lua` and sent back to the `fb-sink` topic of the same broker, this is shown inline for each configuration but is as follows:
+
+```lua
+local count = 0
+function modify_kafka_message(tag, timestamp, record)
+    count = count + 1
+    local payload = record.payload
+    payload.topic = record.topic
+    payload.status = 'processed by fluent-bit, total records: '..tostring(count)
+    return 1, timestamp, payload
+end
+```
 
 The example can be executed locally with `make start` in the `examples/kafka_filter` directory (`docker/compose` is used).
 

pipeline/inputs/tail.md

@@ -167,7 +167,7 @@ systemctl edit fluent-bit.service
 
 When the Linux inotify event queue overflows (indicated by an `IN_Q_OVERFLOW` event), Fluent Bit automatically reconciles all monitored files. During reconciliation it:
 
-- Detects rotated files by comparing inodes and file names and re-registers watches as needed.
+- Detects rotated files by comparing `inode` numbers and file names and re-registers watches as needed.
 - Resets offset tracking for files that have been truncated.
 - Retries watch registration for files that previously failed, for example due to `ENOSPC` when `fs.inotify.max_user_watches` is exhausted.
 
@@ -272,8 +272,8 @@ pipeline:
       path: /var/log/syslog
 
   outputs:
-    - stdout:
-      match: *
+    - name: stdout
+      match: '*'
 ```
 
 {% endtab %}
@@ -368,13 +368,13 @@ pipeline:
 {% tab title="fluent-bit.conf" %}
 
 ```text
-# Note this is generally added to parsers.conf and referenced in [SERVICE]
-[PARSER]
-  Name multiline
-  Format regex
-  Regex /(?<time>[A-Za-z]+ \d+ \d+\:\d+\:\d+)(?<message>.*)/
-  Time_Key  time
-  Time_Format %b %d %H:%M:%S
+# Note this is added to parsers.conf and referenced in [SERVICE]
+# [PARSER]
+#   Name multiline
+#   Format regex
+#   Regex /(?<time>[A-Za-z]+ \d+ \d+\:\d+\:\d+)(?<message>.*)/
+#   Time_Key  time
+#   Time_Format %b %d %H:%M:%S
 
 [INPUT]
   Name             tail

pipeline/outputs/dynatrace.md

@@ -33,45 +33,48 @@ To get started with sending logs to Dynatrace:
 {% tabs %}
 {% tab title="fluent-bit.yaml" %}
 
-   ```yaml
-   pipeline:
-
-     outputs:
-       - name: http
-         match: '*'
-         header:
-           - 'Content-Type application/json; charset=utf-8'
-           - 'Authorization Api-Token {your-API-token-here}'
-         allow_duplicated_headers: false
-         host: {your-environment-id}.live.dynatrace.com
-         port: 443
-         uri: /api/v2/logs/ingest
-         format: json
-         json_date_format: iso8601
-         json_date_key: timestamp
-         tls: on
-         tls.verify: on
-   ```
+```yaml
+pipeline:
+  inputs:
+    - name: dummy
+      tag: test
+
+  outputs:
+    - name: http
+      match: '*'
+      header:
+        - 'Content-Type application/json; charset=utf-8'
+        - 'Authorization Api-Token {your-API-token-here}'
+      allow_duplicated_headers: false
+      host: '{your-environment-id}.live.dynatrace.com'
+      port: 443
+      uri: /api/v2/logs/ingest
+      format: json
+      json_date_format: iso8601
+      json_date_key: timestamp
+      tls: on
+      tls.verify: on
+```
 
 {% endtab %}
 {% tab title="fluent-bit.conf" %}
 
-   ```text
-   [OUTPUT]
-     Name                     http
-     Match                    *
-     Header                   Content-Type application/json; charset=utf-8
-     Header                   Authorization Api-Token {your-API-token-here}
-     Allow_Duplicated_Headers false
-     Host                     {your-environment-id}.live.dynatrace.com
-     Port                     443
-     Uri                      /api/v2/logs/ingest
-     Format                   json
-     Json_Date_Format         iso8601
-     Json_Date_Key            timestamp
-     Tls                      On
-     Tls.verify               On
-   ```
+```text
+[OUTPUT]
+  Name                     http
+  Match                    *
+  Header                   Content-Type application/json; charset=utf-8
+  Header                   Authorization Api-Token {your-API-token-here}
+  Allow_Duplicated_Headers false
+  Host                     {your-environment-id}.live.dynatrace.com
+  Port                     443
+  Uri                      /api/v2/logs/ingest
+  Format                   json
+  Json_Date_Format         iso8601
+  Json_Date_Key            timestamp
+  Tls                      On
+  Tls.verify               On
+```
 
 {% endtab %}
 {% endtabs %}