How to Configure Dynamic Config Reloading with the `--watch-config` Flag in Telegraf

*Telegraf supports dynamic configuration reloading through the --watch-config flag, which offers two modes—notify for Linux/macOS/BSD using native file-system events, and poll for all platforms including Windows that checks files every 250ms by default.

The InfluxData Telegraf agent provides built-in support for hot-reloading configuration files without requiring a service restart. By leveraging the --watch-config command-line option, you can enable automatic reloading when changes are detected in files specified via --config or --config-directory. This guide explains how to configure dynamic config reloading with the --watch-config flag based on the actual Telegraf source code implementation.

Supported Watch Modes and Platform Compatibility

The --watch-config flag accepts two distinct values that determine how Telegraf detects configuration changes:

• notify: Uses native file-system notifications (inotify on Linux, kqueue on *BSD/macOS) for instant change detection. This mode is only supported on Linux, *BSD, and macOS.
• poll: Periodically checks configuration files for modifications, required on Windows and available on all platforms. The default polling interval is 250ms.

According to the source code in [cmd/telegraf/main.go](https://github.com/influxdata/telegraf/blob/master/cmd/telegraf/main.go#L321-L324), the flag is defined as:

&cli.StringFlag{
    Name: "watch-config",
    Usage: "monitoring config changes [notify, poll] of --config and --config-directory options. " +
           "Notify supports linux, *bsd, and macOS. Poll is required for Windows and checks every 250ms.",
}

Fine-Tuning Reload Behavior

Beyond selecting the watch mode, Telegraf provides additional flags to control the reloading frequency and sensitivity.

Adjusting the Polling Interval

When using poll mode, you can customize the check frequency with --watch-interval. By default, this is disabled, falling back to the internal 250ms interval. As defined in [cmd/telegraf/main.go](https://github.com/influxdata/telegraf/blob/master/cmd/telegraf/main.go#L382-L384):

&cli.DurationFlag{
    Name: "watch-interval",
    Usage: "Time duration to check for updates to config files specified by --config and " +
           "--config-directory options. Use with '--watch-config poll'",
    DefaultText: "disabled",
}

Debouncing Rapid Changes

To prevent multiple reloads during rapid file edits, use --watch-debounce-interval (default 0s). This setting delays the reload until the specified duration passes without further changes. The flag is declared at lines 262-269 in [cmd/telegraf/main.go](https://github.com/influxdata/telegraf/blob/master/cmd/telegraf/main.go#L262-L269).

Practical Configuration Examples

Native Notifications on Linux or macOS

For systems supporting file-system events, use notify mode for immediate reloads:

telegraf \
  --config /etc/telegraf/telegraf.conf \
  --watch-config notify

Telegraf reloads the configuration instantly when the file system reports a change to /etc/telegraf/telegraf.conf.

Polling on Windows

Since Windows lacks native support for the notify mode, use poll with a custom interval:

telegraf \
  --config "C:\Program Files\Telegraf\telegraf.conf" \
  --watch-config poll \
  --watch-interval 5s

This checks the configuration every 5 seconds and reloads upon detecting modifications.

Preventing Reload Storms with Debounce

When monitoring files that change frequently or in bursts, add a debounce interval:

telegraf \
  --config /etc/telegraf/telegraf.conf \
  --watch-config notify \
  --watch-debounce-interval 2s

If the configuration changes multiple times within 2 seconds, Telegraf performs only one reload after the burst completes.

Watching Configuration Directories

The --watch-config flag works with --config-directory to monitor multiple configuration fragments:

telegraf \
  --config-directory /etc/telegraf/conf.d \
  --watch-config poll \
  --watch-interval 10s

This monitors all *.conf files within /etc/telegraf/conf.d, reloading when any fragment is added, modified, or removed.

Internal Implementation Details

The dynamic reloading mechanism is implemented across several key source files:

• [cmd/telegraf/main.go](https://github.com/influxdata/telegraf/blob/master/cmd/telegraf/main.go): Defines the command-line flags including --watch-config, --watch-interval, and --watch-debounce-interval, and orchestrates the initialization of the file watcher.
• [cmd/telegraf/telegraf_windows.go](https://github.com/influxdata/telegraf/blob/master/cmd/telegraf/telegraf_windows.go): Handles Windows-specific argument processing at line 218, ensuring the watch-config value propagates to the core application.
• [internal/config/config.go](https://github.com/influxdata/telegraf/blob/master/internal/config/config.go): Implements the actual file-watching logic and configuration reload sequence.
• [docs/COMMANDS_AND_FLAGS.md](https://github.com/influxdata/telegraf/blob/master/docs/COMMANDS_AND_FLAGS.md): Documents all available flags and their usage.

When the --watch-config flag is active, Telegraf spawns a background watcher that compares file timestamps or listens for system events, then triggers the configuration loader to apply changes without restarting the process.

Summary

• Telegraf supports two dynamic reloading modes: native notifications (notify for Linux/macOS/*BSD) and periodic polling (poll for all platforms including Windows).
• Use --watch-interval to customize the polling frequency (default is 250ms when unspecified).
• Add --watch-debounce-interval to batch rapid changes and prevent excessive reloads.
• The feature works with both single --config files and entire --config-directory trees.
• Implementation resides primarily in cmd/telegraf/main.go with platform-specific handling in cmd/telegraf/telegraf_windows.go.

Frequently Asked Questions

Does --watch-config work on Windows?

Yes, but you must use poll mode. The notify mode relies on inotify and kqueue, which are unavailable on Windows. Use --watch-config poll and optionally set --watch-interval to control how frequently Telegraf checks for changes.

What happens if I edit the config file multiple times rapidly?

Without debouncing, Telegraf attempts to reload after each detected change. To prevent this, specify --watch-debounce-interval with a duration (e.g., 2s). This ensures only one reload occurs after changes settle.

Can I watch multiple configuration directories simultaneously?

Yes. When using --config-directory, Telegraf monitors all *.conf files within that directory tree. Combine --config-directory with --watch-config poll or --watch-config notify to reload when any included configuration fragment changes.

Is there a performance penalty for using poll mode on Linux?

The default 250ms interval in poll mode creates minimal overhead, but notify mode is generally preferred on Linux because it uses kernel-level file system events with zero polling overhead, providing immediate detection without CPU usage during idle periods.

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