influxdata / influxdata/telegraf

docs: clarify partial configuration behaviour

Open
#18,306 2 comments 0 reactions 0 assignees View on GitHub
feature request
Dominant language
Go
Stars
17.8k
Forks
5.8k
Avg merge
1d 20h
Merged PRs (30d)
161

Description

### Use Case

We run telegraf passing multiple `--config` params. One config contains `[agent]` and `[output]` and another one (dynamically generated) contains multiple `[input]` entries.

Current [documentation](https://docs.influxdata.com/telegraf/v1/configuration/#configuration-file-locations) has following warning:

> Telegraf doesn’t concatenate configuration files before processing them. Each configuration file that you provide must be a valid configuration.
> If you want to use separate files to manage a configuration, you can use your own custom code to concatenate and pre-process the files, and then provide the complete configuration to Telegraf

Clearly our setup doesn't match it: dynamic config is not self-contained, yet this setup seems to work as if files are concatenated.

Also if files are truly not concatenated, then how multiple `--config` or `--config-directory` are even supported?

### Expected behavior

Clarify how telegraf processes multiple configuration files:

- does it internally concatenate them? If so, then in what order? If directory is taken, does it sort files lexicographically (default `ls` command) or takes them in whatever order filesystem stores them (`ls -f` on macOS)?
- if same section, for example `[agent]`, appears in multiple files, how is it handled? Does the whole section definition from one of them used (which? first? last?) or individual config params within section are merged? (if they are, how maps and lists are merged?)

### Actual behavior

Documentation seems inaccurate

### Additional info

_No response_

Contributor guide

Open the contributing guide

Research direction

Start with the linked configuration-file-locations documentation and trace how multiple --config and --config-directory inputs are processed. Document the processing order and how repeated sections, parameters, maps, and lists are merged or replaced; done means the warning and examples accurately describe the observed behavior.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.