influxdata / influxdata/telegraf

Enforce structured metric descriptions via spec, linter, and CI

Open
#19,003 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
17.8k
Forks
5.8k
Avg merge
1d 20h
Merged PRs (30d)
161

Description

## 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](https://github.com/influxdata/telegraf/pull/18957#issuecomment-4590203828).

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 #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 #18957 — [ci: warn when plugin metric field names are removed or renamed](https://github.com/influxdata/telegraf/pull/18957)
- Reviewer suggestion: @srebhan comment on PR #18957
- Existing linter: `tools/readme_linter`
- Spec directory: `docs/specs/`

Contributor guide

Open the contributing guide

Research direction

Start by reading the existing material in docs/specs/ and the implementation under tools/readme_linter, then review PR #18957 for the metric rename/removal warning context. Done means the spec is defined, all plugin READMEs pass the linter, the linter runs as a required CI step, and the metric warning works reliably.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
ci-cd, documentation, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.