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

> Debug Telegraf effectively using --test and --once modes. Learn how these options simplify troubleshooting by running plugins once and viewing raw metrics or the full pipeline output.

- Repository: [InfluxData/telegraf](https://github.com/influxdata/telegraf)
- Tags: how-to-guide
- Published: 2026-05-14

---

**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`](https://github.com/influxdata/telegraf/blob/main/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`](https://github.com/influxdata/telegraf/blob/main/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`](https://github.com/influxdata/telegraf/blob/main/agent/agent.go), lines 53-78) initializes each input with nanosecond precision and starts service inputs if configured:

```go
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`](https://github.com/influxdata/telegraf/blob/main/agent/agent.go)) drives the single-gather behavior:

```go
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:

```bash
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`](https://github.com/influxdata/telegraf/blob/main/cmd/telegraf/main.go)) to specify a startup delay:

```bash
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:

```bash
telegraf --config telegraf.conf --once

```

### Filtering Specific Components

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

```bash
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`](https://github.com/influxdata/telegraf/blob/main/agent/agent.go) (lines 53-132).
- Use **`--test-wait`** when debugging service inputs that require initialization time.
- Reference [`docs/COMMANDS_AND_FLAGS.md`](https://github.com/influxdata/telegraf/blob/main/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`](https://github.com/influxdata/telegraf/blob/main/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`](https://github.com/influxdata/telegraf/blob/main/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`](https://github.com/influxdata/telegraf/blob/main/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`](https://github.com/influxdata/telegraf/blob/main/docs/COMMANDS_AND_FLAGS.md) (lines 27-29).