If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/influxdata/telegraf shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 14 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 59% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live influxdata/telegraf repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/influxdata/telegraf.

What it runs against: a local clone of influxdata/telegraf — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in influxdata/telegraf | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of influxdata/telegraf. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/influxdata/telegraf.git
#   cd telegraf
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of influxdata/telegraf and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "influxdata/telegraf(\\.git)?\\b" \\
  && ok "origin remote is influxdata/telegraf" \\
  || miss "origin remote is not influxdata/telegraf (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "cmd/telegraf/main.go" \\
  && ok "cmd/telegraf/main.go" \\
  || miss "missing critical file: cmd/telegraf/main.go"
test -f "agent/agent.go" \\
  && ok "agent/agent.go" \\
  || miss "missing critical file: agent/agent.go"
test -f "config/config.go" \\
  && ok "config/config.go" \\
  || miss "missing critical file: config/config.go"
test -f "accumulator.go" \\
  && ok "accumulator.go" \\
  || miss "missing critical file: accumulator.go"
test -f "agent/accumulator.go" \\
  && ok "agent/accumulator.go" \\
  || miss "missing critical file: agent/accumulator.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/influxdata/telegraf"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Telegraf is a standalone Go agent that collects metrics, logs, and arbitrary data from 300+ plugins (inputs, processors, aggregators, outputs) and writes them to various backends. It reads a TOML configuration, polls inputs at fixed intervals, processes the data through a pipeline, aggregates results, and flushes to outputs — designed as a single static binary with zero external runtime dependencies. Monorepo organized as: agent/ (core agent loop, accumulator, POSIX/Windows platform specifics), plugins/ (300+ input/output/processor/aggregator plugins each in subdirectories), TOML config parsing via BurntSushi/toml, and agent/testcases/ with full end-to-end pipeline test scenarios (aggregators-rerun-processors, processor-order-explicit, etc). The agent runs a main loop that calls Input.Gather(), feeds metrics to the Accumulator, runs Processors, then Aggregators, then Outputs.

DevOps engineers and SREs deploying observability infrastructure who need to collect system metrics, application telemetry, and logs from diverse sources (Prometheus, CloudWatch, databases, APIs) and route them to time-series databases like InfluxDB, Datadog, or Honeycomb without writing custom collection code.

Production-ready and actively maintained. The codebase is substantial (13.6M LOC in Go, 1200+ contributors), has comprehensive CI/CD via CircleCI and GitHub Actions (.circleci/config.yml, .github/workflows/), test coverage in agent/agent_test.go and accumulator_test.go, and follows semantic versioning (CHANGELOG.md, RELEASES.md). Recent active development evident from .github/workflows structure supporting linting, milestones, and PR automation.

Moderate dependency risk due to extensive cloud SDK integrations (Azure SDK, Google Cloud, AWS) visible in go.mod — security patches for these SDKs require timely updates. The monolithic plugin architecture means a broken plugin can affect the entire agent; the agent/accumulator.go pipeline is a critical path with high test expectations. Single namespace for all plugins increases naming collision risk, though plugin registry pattern mitigates this.

Active development visible in: semantic versioning PR checks (.github/workflows/semantic.yml), dependabot configuration (.github/dependabot.yml) for automated dependency updates, milestones workflow automation, and linter/readme enforcement. The testcases directory shows recent focus on processor ordering and aggregator behavior (aggregators-skip-processors, processor-order-mixed), indicating ongoing refinement of the metric pipeline execution model.

git clone https://github.com/influxdata/telegraf.git
cd telegraf
make
./telegraf -config telegraf.conf

Or for development with the Makefile: make test runs unit tests, make build creates the binary. Requires Go 1.26.0+ (from go.mod).

Daily commands: Development: make test for tests, make build to compile, ./telegraf -config <path> -debug to run with debug output. Production: download pre-built binary or make package for RPM/DEB. See Makefile for targets; docs/QUICK_START.md has full configuration examples.

• cmd/telegraf/main.go — Entry point for the Telegraf agent; initializes the CLI and orchestrates startup.
• agent/agent.go — Core agent loop that manages plugins, collectors, processors, aggregators, and outputs; the heart of metric collection.
• config/config.go — Configuration parser and validator; converts TOML config to plugin instances and runtime settings.
• accumulator.go — Defines the Accumulator interface that all plugins use to emit metrics; critical abstraction for the plugin ecosystem.
• agent/accumulator.go — Implementation of Accumulator interface; handles metric collection, filtering, and routing to processors and outputs.
• aggregator.go — Defines the Aggregator interface for time-windowed metric aggregation plugins.

• Agent (agent/agent.go) (Go goroutines, time.Ticker, context.Context) — Central orchestrator; manages plugin lifecycle, timing, metric routing, and error handling.
  • Failure mode: If agent panics, all collection stops; process would restart via systemd/supervisord.
• Accumulator (agent/accumulator.go) (metric.Metric, filters, tag maps) — Collects metrics emitted by input plugins; applies filtering and global tags before forwarding to processors.
  • Failure mode: Silently drops metrics if filter rules are misconfigured; no error propagation to inputs.
• Config Parser (config/config.go) (TOML unmarshaling, reflect package, plugin registry) — Parses TOML, instantiates plugins via registry, and validates configuration schema.
  • Failure mode: Startup failure with clear error message if config is malformed or unknown plugin is referenced.
• Input Plugins (plugins/inputs/*) (HTTP clients, system) — Periodically collect metrics from systems/APIs and emit to accumulator.

Add a New Input Plugin

1. Create a new plugin package under plugins/inputs/ with a struct implementing the Input interface (Start, Stop, Gather methods). (plugins/inputs/YOUR_PLUGIN/YOUR_PLUGIN.go)
2. Register the plugin in the plugin registry by adding an init() function that calls registry.Register(). (plugins/inputs/YOUR_PLUGIN/YOUR_PLUGIN.go)
3. Call accumulator.AddMetrics() in your Gather() method to emit collected metrics. (accumulator.go (reference))
4. Add configuration struct tags (toml) for user-configurable parameters. (plugins/inputs/YOUR_PLUGIN/YOUR_PLUGIN.go)
5. Write unit and integration tests demonstrating metric collection. (plugins/inputs/YOUR_PLUGIN/YOUR_PLUGIN_test.go)

Add a New Processor Plugin

1. Create a processor package under plugins/processors/ with a struct implementing the Processor interface (Apply method). (plugins/processors/YOUR_PROCESSOR/YOUR_PROCESSOR.go)
2. Register the processor in the plugin registry so it can be loaded by config. (plugins/processors/YOUR_PROCESSOR/YOUR_PROCESSOR.go)
3. Implement Apply() to transform the metric.Batch in-place and return errors. (plugins/processors/YOUR_PROCESSOR/YOUR_PROCESSOR.go)
4. Reference your processor in a telegraf.conf using [[processors.YOUR_PROCESSOR]] block. (cmd/telegraf/agent.conf (example))

Add a New Output Plugin

1. Create an output plugin package under plugins/outputs/ with a struct implementing Output interface (Connect, Write, Close). (plugins/outputs/YOUR_OUTPUT/YOUR_OUTPUT.go)
2. Implement Connect() to establish connection to the output backend. (plugins/outputs/YOUR_OUTPUT/YOUR_OUTPUT.go)
3. Implement Write() to serialize and transmit metrics to the backend. (plugins/outputs/YOUR_OUTPUT/YOUR_OUTPUT.go)
4. Register the plugin and add it to agent config under [[outputs.YOUR_OUTPUT]]. (plugins/outputs/YOUR_OUTPUT/YOUR_OUTPUT.go)

• Go — Compiles to a static binary with no runtime dependencies; enables lightweight deployment across diverse platforms and architectures.
• TOML configuration — Human-readable syntax provides an intuitive interface for operators to configure plugins and routing rules.
• Plugin interface abstraction — Decouples input/processor/aggregator/output implementations; allows community contributors to extend Telegraf without modifying core.
• Goroutines for concurrent collection — Lightweight concurrency model allows simultaneous polling of hundreds of input sources without blocking.

• Single-threaded main agent loop with concurrent input plugins

  • Why: Simplifies metric ordering and global state management while allowing parallelism in collection.
  • Consequence: Processor ordering is deterministic by configuration appearance order, but input collection delays don't block other inputs.

• Accumulator interface for metric emission instead of direct channel writes

  • Why: Provides a centralized point for filtering, tagging, and routing metrics before outputs see them.
  • Consequence: Adds abstraction layer complexity but prevents plugins from bypassing filters and logging.

• Plugin registry with string-keyed lookup

  • Why: Allows dynamic loading of plugins at runtime via TOML config without hard-coded imports.
  • Consequence: Requires each plugin to register itself via init(), but enables modular builds and third-party plugins.

• Does not provide real-time metric query API; designed as a unidirectional collector and forwarder.
• Not a metrics storage or timeseries database; only collects and transmits to external backends.
• Does not enforce metric schema validation; relies on output plugins to validate schema compatibility.
• Does not provide authentication or encryption at the agent level; delegates to individual plugins and the transport layer.

Plugin registration: plugins must be imported in plugins//all/all.go or they won't load—missing import is a silent failure. Metric timestamps: Telegraf expects RFC3339 or Unix nanoseconds; conversion errors silently drop metrics. Configuration hotloading is NOT supported—agent restart required for config changes. Windows Event Log plugin (plugins/inputs/eventlog/) requires Windows-specific dependencies absent on Linux; build may fail if cross-compiling. The accumulator is NOT thread-safe—plugins must serialize access or use its AddFields() API properly. Processor ordering matters: order of [[processors.]] in TOML determines execution sequence, no automatic dependency resolution. Large go.mod (60+ cloud/database SDKs) means go mod tidy can fail if a transitive dependency breaks compatibility.

• Plugin architecture with interface contracts — Telegraf's entire extensibility model relies on plugins implementing simple interfaces (telegraf.Input, telegraf.Output, etc.); understanding the contract-based design pattern is essential for adding custom collectors or outputs
• Metric accumulator and pipeline ordering — The agent/accumulator.go pattern ensures metrics flow through Input → Processor → Aggregator → Output in strict order; misunderstanding this ordering causes data loss or unexpected transformations
• Interval-based polling vs event-driven collection — Telegraf's default behavior polls inputs at regular intervals (e.g., every 10s); some plugins (listeners like http_listener) are event-driven—mixing these patterns requires careful aggregation and flush interval tuning
• InfluxDB line protocol serialization — Most Telegraf outputs use InfluxDB's line protocol format (measurement,tag1=val1 field1=1.0 1234567890); understanding timestamp precision (nanoseconds), field types (int/float/bool/string), and tag ordering is critical for debugging metric routing
• Starlark scripting for metric transformation — The Starlark processor (plugins/processors/starlark/) allows Python-like metric manipulation without Go compilation; referenced in testcases but requires understanding sandboxed execution model and performance implications
• Field vs Tag distinction in time-series data — Telegraf enforces InfluxDB semantics: tags are indexed metadata (hostname, region), fields are values queried; incorrectly placing high-cardinality data in tags causes database cardinality explosions and performance degradation
• Graceful shutdown and metric flushing — Agent lifecycle (agent/agent.go) must flush buffered metrics on SIGINT/SIGTERM; plugins failing to handle shutdown properly cause data loss; platform-specific code (agent_posix.go vs agent_windows.go) adds complexity

• prometheus/node_exporter — Alternative single-purpose metrics collector focused on system/hardware monitoring; shares input plugin patterns but lacks Telegraf's plugin ecosystem breadth and output flexibility
• fluent/fluentd — Log collection and processing agent with similar plugin architecture and TOML/config-driven approach; complements Telegraf for log pipelines while Telegraf focuses on metrics
• influxdata/influxdb — Primary time-series database backend for Telegraf; tight integration via influxdb output plugin, shared metric protocol (line protocol), and vendor-provided container images
• grafana/loki — Log aggregation system; works with Telegraf's tail input plugin for log collection pipelines as alternative to Elasticsearch/Splunk backends
• open-telemetry/opentelemetry-collector — Cloud-native metrics/traces/logs collector with similar multi-backend output support; CNCF alternative to Telegraf with stronger Kubernetes integration and gRPC protocol support

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for agent/testcases/ integration scenarios

The repo has test case directories (processor-order-appearance, aggregators-rerun-processors, etc.) with input/expected output pairs, but there's likely no automated test runner validating these scenarios. Creating a Go test harness in agent/testcases_test.go that loads and validates each test case would catch regressions and ensure configuration behavior matches expected output. This is high-value since these represent critical agent pipeline behaviors.

• [ ] Create agent/testcases_test.go with a parameterized test function
• [ ] Parse each telegraf.conf in agent/testcases/*/
• [ ] Load corresponding input.influx and expected.out files
• [ ] Run agent pipeline and compare actual vs expected output
• [ ] Add test documentation in agent/README.md explaining the test case structure
• [ ] Integrate test into CI pipeline via .circleci/config.yml or existing GitHub Actions workflows

Add missing plugin documentation and examples to cmd/telegraf/agent.conf template

The cmd/telegraf/agent.conf is the reference configuration template for users. With 300+ plugins available (per README), many advanced features likely lack example configurations. This impacts new contributor onboarding and user adoption. Systematically adding documented examples for commonly-used plugin combinations (especially those with complex options like aggregators, processors, and outputs) would be directly valuable.

• [ ] Audit current cmd/telegraf/agent.conf for coverage of input/processor/aggregator/output plugin categories
• [ ] Identify 5-10 plugin combinations not documented (e.g., Starlark processor with specific transformations)
• [ ] Add commented example sections with realistic use cases for each
• [ ] Reference the corresponding plugin subdirectories in plugins/ (not shown but implied)
• [ ] Update cmd/telegraf/README.md with guidance on using the template
• [ ] Validate configuration syntax with telegraf --config-directory cmd/telegraf/

Create GitHub Action workflow for plugin compatibility matrix testing

With go 1.26.0 and 300+ plugins, plugin compatibility across Go versions and plugin combinations is a blind spot. The .github/workflows/ directory exists but lacks a matrix test. Adding a workflow that tests plugin build/unit-tests across supported Go versions would catch compatibility issues early, especially important given the large dependency footprint in go.mod.

• [ ] Create .github/workflows/plugin-matrix.yml
• [ ] Define matrix for: Go versions (1.23, 1.24, 1.25, 1.26), key plugin categories (cloud, database, monitoring)
• [ ] For each combo: run 'go build ./plugins/...' and 'go test ./plugins/...'
• [ ] Run on pull requests touching plugins/ or go.mod
• [ ] Configure alerts for failures and add job summary reporting
• [ ] Document in CONTRIBUTING.md how plugin authors can run these checks locally

• Add unit tests for agent/agent_windows.go service lifecycle methods (InstallAsService, StartAsService, StopAsService) which currently have no corresponding *_test.go file—tests should mock Windows service APIs and verify registry/event log interactions
• Document the processor execution order semantics in docs/CONFIGURATION.md with a concrete example showing how [[processors.regex]] and [[processors.rename]] order affects the output pipeline when both match the same metric—include the testcases/processor-order-* scenarios
• Implement missing accumulator test coverage for edge cases: verify AddMetric() with nil tags, AddFields() with NaN/Inf float values, and AddError() persistence across multiple Gather() cycles in agent/accumulator_test.go

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.