Enforce structured metric descriptions via spec, linter, and CI

[yaseen-vm]

Overview

This issue tracks the work to establish a sustainable, structured approach to metric description formatting across all Telegraf plugins — as discussed in PR #18957.

Currently, the CI check for detecting renamed or removed metric fields relies on parsing free-form README content, which is fragile due to inconsistent formatting across plugins. The goal of this issue is to eliminate that fragility by enforcing a well-defined structure at the spec and tooling level.

Motivation

• Plugin READMEs have no enforced structure for metric field descriptions
• CI scripts that parse READMEs are brittle and require edge-case handling per format variant
• A spec + linter approach gives a single source of truth and makes future CI checks simple and reliable

Scope of Work

• 1. Define a metric description spec — Write a formal spec under docs/specs/ describing the required structure for metric fields in plugin READMEs (field name, type, description, units, tags, etc.)
• 2. Extend the README linter — Add enforcement rules to tools/readme_linter that validate plugin READMEs against the new spec
• 3. Fix all linter violations — Run the extended linter across all plugins and bring every README into compliance
• 4. Enable the linter in CI — Add the README linter as a required CI step so no future PR can introduce non-conforming metric descriptions
• 5. Add CI warning for renamed/removed metrics — With the structure now guaranteed, land a clean, reliable CI job (from PR ci: warn when plugin metric field names are removed or renamed #18957) that warns when metric field names are removed or renamed between commits

Expected Outcome

• All plugin READMEs follow a consistent, machine-readable metric description format
• The README linter enforces this structure on every PR
• The CI metric rename/removal warning works reliably without edge-case parsing hacks

References

• PR ci: warn when plugin metric field names are removed or renamed #18957 — ci: warn when plugin metric field names are removed or renamed
• Reviewer suggestion: @srebhan comment on PR ci: warn when plugin metric field names are removed or renamed #18957
• Existing linter: tools/readme_linter
• Spec directory: docs/specs/