docs(telegraf): Telegraf documentation overhaul - #7655
Open
sanderson wants to merge 35 commits into
Open
Conversation
Defines the new structure for the Telegraf v1 docs, per-page content descriptions, URL/alias strategy, and the PR parceling for the work based on docs/telegraf-revamp. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Adds a manage-at-scale signpost page under Administer, Controller pointers on the landing and get-started pages, and a light enterprise.md refresh to the PR parceling. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Adds Telegraf Controller heartbeat monitoring to the monitor page scope, a shared agent-status how-to under Administer, and a shared CEL agent-status-eval reference section. Controller pages become canonical source: consumers of content/shared/telegraf/ (PR 12). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Captures existing frontmatter and assets that rewrites must carry forward: the v1 cascade block, dual menu memberships, legacy aliases, landing-page education assets, related links, and menu-rename mechanics. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Implements PR 1 of the Telegraf v1 docs revamp plan: - Add How Telegraf works (concepts/), Configuration examples (examples/), and Administer Telegraf (administer/) section indexes. - Move metrics, troubleshoot, and template-patterns to their new homes with aliases; fix the invalid Parent key that left troubleshoot un-nested. - Adopt level-based nav weights across both menus. - Relabel Configure plugins to Use plugins and reparent its children. - Revamp the landing page, preserving the cascade block, dual menu entries, and education assets. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Frontmatter-only weight change (60 to 1). Hooks bypassed because Vale flags pre-existing Google.Spacing false positives in the release notes body, which are fixed in a separate open PR. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
docs(telegraf): restructure v1 nav and add section skeletons
Implements PR 2 of the Telegraf v1 docs revamp plan: - Expand How Telegraf works into an architecture overview: plugin types, polling vs. service inputs, and parsers and serializers. - Rewrite Telegraf metrics: metric model with line protocol example, tags vs. fields guidance, serialization across many destinations, and tracking metrics with delivery acknowledgment. - Add The Telegraf data pipeline: per-stage flow with diagram, processor ordering and skip_processors settings, output batching, memory vs. disk buffering, and where filtering applies. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
docs(telegraf): add concepts content for metrics and data pipeline
Implements PR 3 of the Telegraf v1 docs revamp plan: - Convert configuration.md to configuration/_index.md, preserving the URL and anchors, and move it from the reference nav to the main nav as Configure Telegraf. - Add topic pages: configuration file (structure, generation, locations, multi-file merging, URL loading including Telegraf Controller as a config source), TOML syntax, agent settings, and common plugin options. - Settings pages use per-setting headings with Type and Default metadata and in-page tables of contents; types and defaults verified against the Telegraf source. - Document that a valid config requires at least one input and one output plugin. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Lets docs opt individual code blocks out of lint-codeblocks validation for examples that are intentionally invalid. Skipped blocks still appear in linter output with the skip reason. Apply it to the intentionally invalid TOML example on the TOML syntax page, and split the string-escaping example into two blocks (defining the same key twice was itself invalid TOML). Document the attribute in DOCS-TESTING.md. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Two latent in-page TOC typos surfaced by the link checker after the file moved: the specific-plugins link omitted "file" from the heading anchor, and the filtering examples link pointed to #filter-examples instead of #filtering-examples. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
docs(telegraf): convert configuration to a section with topic pages
Implements PR 4 of the Telegraf v1 docs revamp plan: - Add Filter metrics: selectors (namepass/namedrop with separators, tagpass/tagdrop, metricpass with CEL caveats) and modifiers (fieldinclude/fieldexclude, taginclude/tagexclude) with per-setting anchors, order of operations, and worked examples including output routing. - Add Labels and selectors: plugin labels, --select matching semantics, behavior matrix, and the Telegraf Controller shared-config use case. - Link both pages from the corresponding configuration index sections. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
docs(telegraf): add metric filtering and labels-selectors pages
Implements PR 5 of the Telegraf v1 docs revamp plan, completing the
Configure Telegraf section:
- Environment variables: substitution syntax, quoting by TOML type,
shell parameter expansion forms, and a before/after example.
- Secrets: the @{store:name} reference syntax, configuring secret
stores, secret-capable option caveat, the telegraf secrets CLI, and
memory locking requirements including the FreeBSD jail parameter.
- TLS: client, server, and advanced settings with per-setting anchors;
the default minimum TLS version documented as TLS12 per the Telegraf
source.
- Link all three from the corresponding configuration index sections.
- Record the periods-over-semicolons prose principle in PLAN.md and add
the sweep to the cleanup parcel.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The reference-nav weight sentence drifted into the prose-punctuation principle during successive edits. Move it back under the weights principle and split its semicolon join. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…-tls docs(telegraf): add environment variables, secrets, and TLS pages
Implements PR 6 of the Telegraf v1 docs revamp plan: - Rewrite Get started: generate a cpu/mem config, start Telegraf, read line protocol output, then write to InfluxDB 3 with the influxdb_v3 output plugin. Replaces outdated $VAR env-var syntax and the legacy --sample-config flag. - Revamp Install: add Docker tab, verify-the-installation section, and next-steps funnel; remove the duplicated configuration-generation section and service run/manage content (inventoried in the plan for the administer parcel); fix the Windows config path contradiction, stale SHA checksum examples, and the RedHat gpgkey reference; merge the Linux binary tabs; modernize callouts and punctuation. - Record in the plan that run-as-service.md must restore the launchd and Windows service-management content removed here. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
docs(telegraf): rewrite get started and revamp install
Implements PR 10 of the Telegraf v1 docs revamp plan: - Add Run Telegraf as a service: systemd unit management verified against the packaged unit file, Homebrew launchd, and the Windows service subcommand including multiple services, auto-restart, Event Viewer logging, and the shutdown-timeout registry note. Restores the service content removed from install.md in PR 6. - Add Monitor Telegraf: the internal input plugin with verified measurement names, buffer backpressure guidance, log reading, and fleet monitoring with Telegraf Controller heartbeats. - Add Manage agents at scale: the Telegraf Controller signpost with reciprocal related links on the Telegraf Enterprise page. - Expand Troubleshoot: pprof profiling, AppArmor denials, and common errors from the upstream FAQ; examples modernized to influxdb_v3. - Record the examples-use-InfluxDB-3 principle in the plan and add the v2-example sweep to the cleanup parcel. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
docs(telegraf): build out the Administer Telegraf section
- Rewrite the input and output plugin section indexes: polling versus service inputs, testing with --test/--test-wait/--once, batching, buffering, and write-failure and partial-write behavior - Add parse-data and serialize-data guides with worked examples - Expand the processors and aggregators page: data-flow diagram showing both processor passes, common processor and aggregator examples, and in-depth second-pass behavior verified against the Telegraf agent source - Refresh the external plugins pages against upstream EXTERNAL_PLUGINS.md - Tidy the Citi Bike HTTP example and remove its stale Flux screenshot - Fix troubleshoot.md: --test runs processors and aggregators, not only inputs - Document the skip_processors_after_aggregators default change coming in Telegraf 1.40 in agent.md and data-pipeline.md - PLAN.md: move using_http.md to the examples section in PR 9 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
docs(telegraf): build out the Use plugins guides
- Add missing input format pages: prometheus (v1.17), xpath_cbor (v1.28), and openmetrics and parquet (v1.31) - Deep-rewrite the JSON parser pages (json, json_v2, xpath_json) with complete option references, worked examples, and a JSON parser comparison on the input index; xpath_json behavior and examples verified against Telegraf 1.39 - Document JSONata transformations and remaining options in the JSON serializer page - Fix the broken [[inputs.file.xml]] config example (the section is named xpath for all formats) and restructure the XPath family pages around xpath_json as the shared reference - Refresh all format pages against upstream READMEs: renamed and missing options (binary_encoding, endianness, xpath_protobuf_files, cloudevents_event_time, dropwizard_tag_paths_map, influx_timestamp_precision, value auto types, carbon2, nowmetric, splunkmetric, graphite, and prometheus serializer options), stale links, and the Issue #2360 placeholder on the data formats landing page - Normalize data_formats page weights to page level so children listings sort alphabetically Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
docs(telegraf): revamp the data formats reference
- Twelve scenario pages, each with a complete configuration, a walkthrough, and sample output: system metrics, Docker containers, HTTP APIs, CSV files, log parsing, Kafka, MQTT, OPC UA, SNMP, Prometheus scraping, downsampling, and output routing - The OPC UA page covers browse-based node discovery (Telegraf 1.39+) and explicit node definitions, and recommends the upgrade - Move the Citi Bike HTTP walkthrough into the section as collect-json-http-api with an alias from the old URL - Grok parser output verified against Telegraf 1.39 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
docs(telegraf): add Telegraf configuration examples section
- Extract the agent status page and the agent-status-eval CEL reference bodies to content/shared/telegraf/; Telegraf Controller pages keep their URLs and frontmatter and consume the shared files via source:, remaining the canonical versions - Add Telegraf v1 consuming pages: administer/agent-status.md and the agent-status-eval reference section, each with canonical: pointing at the Controller counterpart - Product-neutralize shared prose (explicit "Telegraf Controller" instead of product-name) and make sibling links relative so they stay in-product for both consumers - Cross-link metricpass and the CEL reference both ways, and document the metricpass CEL variables in filtering.md (verified in models/filter.go; both CEL environments share the same functions and extensions) - Point monitor.md status links at the in-product v1 page - Fix spaced em-dashes inherited from the original Controller prose Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…hared docs(telegraf): share agent status content between v1 and Controller
- Rebuild the commands global-flags reference from telegraf --help (1.39), grouped by purpose, and add the Windows-only service command page with PowerShell examples and a Command Prompt note - Add the supported platforms reference page - Add glossary terms: label, parser, secret store, selector, serializer, and tracking metric - Add a release cadence and versioning intro to the release notes with a nightly-builds pointer - Slim configuration/_index.md from the full legacy reference to an overview and quick reference; every previously resolving anchor survives, and new plugins, secret-store-secrets, and intervals anchors fix fragment links from the generated plugin pages - Sweep earlier parcels: convert remaining outputs.influxdb_v2 examples to influxdb_v3, move menu-level weights to page level, and split 31 semicolon clause joins into sentences - Modernize install.md's Windows service steps to the service subcommand form and correct its --test description - Fix dash punctuation in enterprise.md - Remove the legacy InfluxData Platform block from the Telegraf v1 sidebar Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
docs(telegraf): reference cleanup and cross-parcel sweeps
All parcels of the Telegraf v1 documentation revamp plan are merged. Remove PLAN.md so the required check allows merging docs/telegraf-revamp into master. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
Vale Style Check Results
✅ Check passed |
github-actions
Bot
added
product:shared
Contributor
Release version check
💡 Badge new features with the versionDocumenting a new feature? Add a version badge in the page frontmatter — the
For inline version text, use |
Contributor
🔗 Link Check Results — Link Check Bot✅ All links are valid
|
| Source File | URL | Issue |
|---|---|---|
content/telegraf/controller/agents/status/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/telegraf/controller/reference/agent-status-eval/examples/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/telegraf/controller/reference/agent-status-eval/functions/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/telegraf/controller/reference/agent-status-eval/functions/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/telegraf/controller/reference/agent-status-eval/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/telegraf/controller/reference/agent-status-eval/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/telegraf/controller/reference/agent-status-eval/variables/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/telegraf/controller/reference/agent-status-eval/variables/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/telegraf/v1/administer/agent-status/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/telegraf/v1/administer/agent-status/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/telegraf/v1/administer/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/telegraf/v1/administer/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/telegraf/v1/administer/manage-at-scale/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/telegraf/v1/administer/manage-at-scale/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/telegraf/v1/administer/monitor/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/telegraf/v1/administer/monitor/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/telegraf/v1/administer/run-as-service/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/telegraf/v1/administer/run-as-service/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/telegraf/v1/administer/troubleshoot/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/telegraf/v1/administer/troubleshoot/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
Showing first 20 of 39 warnings. See the workflow run for full results.
Full details: workflow run summary and artifact. Last updated: 2026-08-14 19:16:07 UTC
Contributor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Overhauls the Telegraf v1 documentation for structure, depth, and accuracy.
What changed
Two reading paths: the main nav tells the learning story (Install → Get started → How Telegraf works → Configure → Use plugins → Examples → Administer) while the reference nav stays terse (Plugin directory, Commands, Data formats, Glossary, and new Agent status evaluation and Supported platforms sections).
New sections:
Configuration reference decomposed: the old single-page reference is now nine topic pages with a slim overview index. All inbound anchors keep resolving, and new anchor targets fix ~400 fragment links from the generated plugin pages that were silently broken.
Data formats refreshed: four missing format pages added (
prometheus,openmetrics,parquet,xpath_cbor), the JSON parser and serializer pages rewritten in depth, and every format page checked against upstream.Accuracy: content verified against the Telegraf source and the 1.39 binary rather than READMEs alone; example output was produced by running real configurations where practical.
Shared content: agent status pages are now shared with Telegraf Controller (
content/shared/telegraf/); the Controller pages remain canonical.What didn't change
The auto-generated plugin reference directories are untouched, every moved page carries a Hugo alias, and high-traffic URLs are unchanged.