From ab48a5db27f9fc72fc7912d2d04748eea98c4ce4 Mon Sep 17 00:00:00 2001 From: Yaseen V M Date: Thu, 21 May 2026 15:57:52 +0530 Subject: [PATCH 1/5] test: simulate metric rename for CI check validation --- plugins/inputs/system/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/inputs/system/README.md b/plugins/inputs/system/README.md index 1e55d8adb066b..aacc090233adf 100644 --- a/plugins/inputs/system/README.md +++ b/plugins/inputs/system/README.md @@ -98,7 +98,7 @@ separate `system_os` measurement. | `n_users` | `users` | integer | Number of logged-in user sessions | | `n_unique_users` | `users` | integer | Number of unique logged-in usernames | | `n_virtual_cpus` | `cpus` | integer | Number of logical CPUs | -| `n_cpus` | `legacy_cpus` | integer | Number of logical CPUs (legacy name) | +| `n_cpus_RENAMED` | `legacy_cpus` | integer | Number of logical CPUs (legacy name) | | `n_physical_cpus` | `cpus` / `legacy_cpus` | integer | Number of physical CPUs | | `uptime` | `uptime` | integer | System uptime in seconds (gauge field) | | `uptime` | `legacy_uptime` | integer | System uptime in seconds (separate counter) | From 7f86f245f5bf1ffcb0b81d5ce16dab3b38c76f26 Mon Sep 17 00:00:00 2001 From: Yaseen V M Date: Thu, 21 May 2026 15:58:42 +0530 Subject: [PATCH 2/5] Revert "test: simulate metric rename for CI check validation" This reverts commit ab48a5db27f9fc72fc7912d2d04748eea98c4ce4. --- plugins/inputs/system/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/inputs/system/README.md b/plugins/inputs/system/README.md index aacc090233adf..1e55d8adb066b 100644 --- a/plugins/inputs/system/README.md +++ b/plugins/inputs/system/README.md @@ -98,7 +98,7 @@ separate `system_os` measurement. | `n_users` | `users` | integer | Number of logged-in user sessions | | `n_unique_users` | `users` | integer | Number of unique logged-in usernames | | `n_virtual_cpus` | `cpus` | integer | Number of logical CPUs | -| `n_cpus_RENAMED` | `legacy_cpus` | integer | Number of logical CPUs (legacy name) | +| `n_cpus` | `legacy_cpus` | integer | Number of logical CPUs (legacy name) | | `n_physical_cpus` | `cpus` / `legacy_cpus` | integer | Number of physical CPUs | | `uptime` | `uptime` | integer | System uptime in seconds (gauge field) | | `uptime` | `legacy_uptime` | integer | System uptime in seconds (separate counter) | From bb10b48330b82fb87db2d430e2be228cd50a429b Mon Sep 17 00:00:00 2001 From: Yaseen V M Date: Thu, 21 May 2026 15:59:01 +0530 Subject: [PATCH 3/5] ci: warn when plugin metric field names are removed or renamed Adds scripts/check-metric-names.sh and a GitHub Actions workflow that runs on every PR targeting master. When a plugin README's metric table loses a field name that was present on master, the check emits a ::warning annotation and explains the backward-compatibility impact, helping contributors acknowledge breaking changes before they merge. Closes #18955 --- .github/workflows/metric-names.yml | 22 +++++++++ scripts/check-metric-names.sh | 74 ++++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+) create mode 100644 .github/workflows/metric-names.yml create mode 100644 scripts/check-metric-names.sh diff --git a/.github/workflows/metric-names.yml b/.github/workflows/metric-names.yml new file mode 100644 index 0000000000000..453ff1ce43208 --- /dev/null +++ b/.github/workflows/metric-names.yml @@ -0,0 +1,22 @@ +name: Check metric name backward compatibility +on: + pull_request: + branches: + - master + +jobs: + check-metric-names: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + with: + fetch-depth: 0 + - name: Get changed plugin READMEs + id: changed-files + uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6 + with: + base_sha: ${{ github.event.pull_request.base.sha }} + files: ./plugins/**/README.md + - name: Check for removed metric fields + if: steps.changed-files.outputs.any_changed == 'true' + run: bash scripts/check-metric-names.sh diff --git a/scripts/check-metric-names.sh b/scripts/check-metric-names.sh new file mode 100644 index 0000000000000..c1fe744f700b6 --- /dev/null +++ b/scripts/check-metric-names.sh @@ -0,0 +1,74 @@ +#!/bin/bash +# Warns when metric field names are removed or renamed in plugin READMEs. +# Metric removals break user dashboards and alerting rules; this check +# surfaces the impact so contributors can acknowledge it before merging. +# +# Always exits 0 — this is an informational warning, not a hard gate. + +set -euo pipefail + +BASE_REF="${GITHUB_BASE_REF:-master}" +BASE="origin/${BASE_REF}" + +# Extract backtick-quoted field names from the first column of markdown tables. +# Matches lines like: | `field_name` | ... +extract_fields() { + grep -oE '^\s*\|\s*`[a-zA-Z0-9_]+`' "$1" 2>/dev/null \ + | awk -F'`' '{print $2}' \ + || true +} + +extract_fields_from_stdin() { + grep -oE '^\s*\|\s*`[a-zA-Z0-9_]+`' 2>/dev/null \ + | awk -F'`' '{print $2}' \ + || true +} + +CHANGED_READMES=$(git diff --name-only "${BASE}...HEAD" -- 'plugins/*/*/README.md' 2>/dev/null || true) + +if [[ -z "${CHANGED_READMES}" ]]; then + echo "No plugin READMEs changed — nothing to check." + exit 0 +fi + +WARNED=0 + +while IFS= read -r readme; do + [[ -z "$readme" ]] && continue + + if ! git show "${BASE}:${readme}" &>/dev/null; then + # New plugin README — no baseline to compare against. + continue + fi + + old_fields=$(git show "${BASE}:${readme}" | extract_fields_from_stdin | sort -u) + new_fields=$(extract_fields "$readme" | sort -u) + + removed=$(comm -23 <(echo "$old_fields") <(echo "$new_fields")) + + if [[ -n "$removed" ]]; then + echo "::warning file=${readme}::Metric fields removed or renamed in ${readme}" + echo "" + echo " Plugin: ${readme}" + echo " Removed fields:" + while IFS= read -r field; do + [[ -z "$field" ]] && continue + echo " - ${field}" + done <<< "$removed" + echo "" + echo " Removing or renaming existing metric fields is a breaking change." + echo " Users relying on these names in dashboards, alerts, or pipelines" + echo " will see data gaps after upgrading. If this change is intentional:" + echo " 1. Add a deprecation notice in the README alongside the old name." + echo " 2. Keep the old name available (e.g. via a 'legacy_*' include option)." + echo " 3. Document the migration path in your PR description." + echo "" + WARNED=1 + fi +done <<< "$CHANGED_READMES" + +if [[ $WARNED -eq 0 ]]; then + echo "No metric fields removed — backward compatibility preserved." +fi + +exit 0 From 946a7b44e5f0abbe7abb64bdce6b7dbbc8c126d7 Mon Sep 17 00:00:00 2001 From: Yaseen V M Date: Thu, 21 May 2026 16:05:36 +0530 Subject: [PATCH 4/5] ci: fix shellcheck SC2016 false positive on backtick regex patterns --- scripts/check-metric-names.sh | 2 ++ 1 file changed, 2 insertions(+) diff --git a/scripts/check-metric-names.sh b/scripts/check-metric-names.sh index c1fe744f700b6..1b8cf215fe80f 100644 --- a/scripts/check-metric-names.sh +++ b/scripts/check-metric-names.sh @@ -13,12 +13,14 @@ BASE="origin/${BASE_REF}" # Extract backtick-quoted field names from the first column of markdown tables. # Matches lines like: | `field_name` | ... extract_fields() { + # shellcheck disable=SC2016 -- backtick is a literal regex character, not a command substitution grep -oE '^\s*\|\s*`[a-zA-Z0-9_]+`' "$1" 2>/dev/null \ | awk -F'`' '{print $2}' \ || true } extract_fields_from_stdin() { + # shellcheck disable=SC2016 -- backtick is a literal regex character, not a command substitution grep -oE '^\s*\|\s*`[a-zA-Z0-9_]+`' 2>/dev/null \ | awk -F'`' '{print $2}' \ || true From 2e7294aa8c8b238db5f3e06ef87ad3fd56525a11 Mon Sep 17 00:00:00 2001 From: Yaseen V M Date: Thu, 21 May 2026 16:08:26 +0530 Subject: [PATCH 5/5] ci: fix shellcheck directive syntax, remove inline comment after disable rule --- scripts/check-metric-names.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/check-metric-names.sh b/scripts/check-metric-names.sh index 1b8cf215fe80f..62baf7fc6065a 100644 --- a/scripts/check-metric-names.sh +++ b/scripts/check-metric-names.sh @@ -13,14 +13,14 @@ BASE="origin/${BASE_REF}" # Extract backtick-quoted field names from the first column of markdown tables. # Matches lines like: | `field_name` | ... extract_fields() { - # shellcheck disable=SC2016 -- backtick is a literal regex character, not a command substitution + # shellcheck disable=SC2016 grep -oE '^\s*\|\s*`[a-zA-Z0-9_]+`' "$1" 2>/dev/null \ | awk -F'`' '{print $2}' \ || true } extract_fields_from_stdin() { - # shellcheck disable=SC2016 -- backtick is a literal regex character, not a command substitution + # shellcheck disable=SC2016 grep -oE '^\s*\|\s*`[a-zA-Z0-9_]+`' 2>/dev/null \ | awk -F'`' '{print $2}' \ || true