influxdata / influxdata/telegraf
docs: clarify partial configuration behaviour
- 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
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