How to Use Telegraf's --test and --once Modes for Debugging

Telegraf's --test flag runs only input plugins once and prints raw metrics to stdout, while --once executes the complete pipeline—including processors, aggregators, and outputs—for a single collection cycle before exiting.

When troubleshooting configuration issues or developing new plugins in the influxdata/telegraf repository, you need a safe way to inspect metric collection without deploying a long-lived daemon. Telegraf's --test and --once modes provide lightweight, single-execution debugging capabilities derived from the agent core in agent/agent.go.

Understanding Telegraf --test and --once Modes

Both flags bypass the normal scheduling loop to execute exactly one gather cycle, but they differ in which pipeline components they activate.

The --test Flag

The --test flag starts only input plugins, runs a single gather cycle, prints the collected metrics directly to stdout, and then exits. Processors, aggregators, and output plugins are not executed—instead, the agent substitutes outputs with a built-in "print" output handler. Use this mode for quick sanity checks to verify that inputs load correctly, establish connections, and parse data as expected.

The --once Flag

The --once flag starts inputs exactly as in normal production mode, including service inputs, processors, and aggregators. It runs a single gather cycle, flushes any pending data to configured outputs, and then exits. This mode provides a full pipeline test, allowing you to observe how processors transform data and confirm that outputs receive metrics before you commit to a continuous deployment.

Implementation Details in the Agent

The implementation for both flags resides in the agent core. In cmd/telegraf/main.go (lines 66-68), the runApp function parses command-line arguments and stores flag values in GlobalFlags. When either --test or --once is true, the agent creates an input unit using specialized test functions.

Starting Inputs with testStartInputs

The testStartInputs function (defined in agent/agent.go, lines 53-78) initializes each input with nanosecond precision and starts service inputs if configured:

func (*Agent) testStartInputs(dst chan<- telegraf.Metric, inputs []*models.RunningInput) *inputUnit {
    // ... create an accumulator with nanosecond precision ...
    if err := input.Start(acc); err != nil {
        log.Printf("E! [agent] Starting input %s: %v", input.LogName(), err)
        continue
    }
    unit.inputs = append(unit.inputs, input)
}

Errors during startup are logged rather than fatal, allowing you to identify which specific plugin fails without aborting the entire test run.

Executing a Single Gather with testRunInputs

The testRunInputs function (lines 81-132 in agent/agent.go) drives the single-gather behavior:

func (a *Agent) testRunInputs(ctx context.Context, wait time.Duration, unit *inputUnit) {
    // ... create a dummy channel for rate-based metrics ...
    if input.Config.Name == "cpu" { /* ... */ }
    
    if err := input.Input.Gather(acc); err != nil {
        acc.AddError(err)
    }
}

This function deliberately does not start a ticker. It calls each input's Gather method exactly once. For rate-based inputs like cpu, mongodb, or procstat, the code performs a temporary second gather on a null accumulator to ensure correct delta calculations without emitting duplicate metrics.

Debugging with --test Mode

Use --test to inspect raw input data and verify parsing logic without side effects.

Basic Input Inspection

Run a specific input and view its output immediately:

telegraf --config telegraf.conf --input-filter cpu --test

This command loads only the cpu input, gathers metrics once, and prints them to the console.

Debugging Service Inputs with Delays

Service inputs (such as docker) may require initialization time before they can collect metrics. Use the --test-wait flag (defined at line 302 of cmd/telegraf/main.go) to specify a startup delay:

telegraf --config telegraf.conf --input-filter docker --test-wait 10 --test

This gives the Docker input up to 10 seconds to become ready before attempting collection.

Validating the Full Pipeline with --once Mode

When you need to verify processor transformations or aggregator behavior, use --once to run the complete data pipeline.

Standard Single Execution

Run all configured plugins exactly once, including flushing data to outputs:

telegraf --config telegraf.conf --once

Filtering Specific Components

Combine --once with filter flags to isolate specific pipeline stages:

telegraf --config telegraf.conf \
    --input-filter http \
    --processor-filter json \
    --once

This executes only the http input and json processor, running one collection cycle and flushing results before exiting.

Key Differences Between --test and --once

• Pipeline Scope: --test runs only inputs; --once runs inputs, processors, aggregators, and outputs.
• Output Destination: --test prints to stdout via a builtin output; --once uses your configured outputs (InfluxDB, file, etc.).
• Error Handling: Both modes log plugin errors and continue, but --once will attempt to flush to outputs even if processors encounter errors.
• Use Case: Use --test for input debugging and configuration validation; use --once for integration testing and CI/CD pipelines.

Summary

• --test isolates input plugins, prints metrics to stdout, and skips processors and outputs—ideal for verifying input configuration.
• --once executes the full Telegraf pipeline once, including flushing to outputs—useful for testing transformations and integrations.
• Both modes rely on testStartInputs and testRunInputs in agent/agent.go (lines 53-132).
• Use --test-wait when debugging service inputs that require initialization time.
• Reference docs/COMMANDS_AND_FLAGS.md (lines 27-29) for official flag documentation.

Frequently Asked Questions

Does --test mode execute processors and aggregators?

No. The --test flag explicitly skips processors, aggregators, and external outputs. It replaces the output layer with a builtin print handler that writes directly to stdout, allowing you to inspect raw input metrics without side effects.

How do I debug service inputs that need time to initialize?

Use the --test-wait flag followed by a duration in seconds. For example, telegraf --config telegraf.conf --input-filter docker --test-wait 10 --test waits up to 10 seconds for the Docker daemon to respond before attempting the gather cycle. This flag is defined in cmd/telegraf/main.go at line 302.

Can I use --once with specific input or processor filters?

Yes. Combine --once with --input-filter, --processor-filter, or --aggregator-filter to run a targeted subset of your configuration. For example: telegraf --config telegraf.conf --input-filter http --once runs only the HTTP input through the full pipeline once.

Where are these flags defined in the Telegraf source code?

The flag definitions reside in cmd/telegraf/main.go (lines 66-68) where runApp parses command-line arguments into GlobalFlags. The underlying implementation for single-gather execution lives in agent/agent.go, specifically in the testStartInputs (lines 53-78) and testRunInputs (lines 81-132) functions. User-facing documentation appears in docs/COMMANDS_AND_FLAGS.md (lines 27-29).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}