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

> Learn how to configure dynamic config reloading in Telegraf using the --watch-config flag to automatically apply configuration changes without restarting the agent.

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

---

**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/main/cmd/telegraf/main.go)](https://github.com/influxdata/telegraf/blob/master/cmd/telegraf/main.go#L321-L324), the flag is defined as:

```go
&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/main/cmd/telegraf/main.go)](https://github.com/influxdata/telegraf/blob/master/cmd/telegraf/main.go#L382-L384):

```go
&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/main/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:

```bash
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`](https://github.com/influxdata/telegraf/blob/main//etc/telegraf/telegraf.conf).

### Polling on Windows

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

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

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

```bash
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/main/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/main/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/main/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/main/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`](https://github.com/influxdata/telegraf/blob/main/cmd/telegraf/main.go) with platform-specific handling in [`cmd/telegraf/telegraf_windows.go`](https://github.com/influxdata/telegraf/blob/main/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.