github.com/influxdata/telegraf@v1.30.3/docs/TOML.md (about) 1 # TOML 2 3 Telegraf uses TOML as the configuration language. The following outlines a few 4 common questions and issues that cause questions or confusion. 5 6 ## Reference and Validator 7 8 For all things TOML related, please consult the [TOML Spec][] and consider 9 using a TOML validator. In VSCode the [Even Better TOML][] extension or use the 10 [TOML Lint][] website to validate your TOML config. 11 12 [TOML Spec]: https://toml.io/en/v1.0.0 13 [Even Better TOML]: https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml 14 [TOML Lint]: https://www.toml-lint.com/ 15 16 ## Multiple TOML Files 17 18 TOML technically does not support multiple files, this is done as a convenience for 19 users. 20 21 Users should be aware that when Telegraf reads a user's config, if multiple 22 files or directories are read in, each file at a time and all 23 settings are combined as if it were one big file. 24 25 ## Single Table vs Array of Tables 26 27 Telegraf uses a single agent table (e.g. `[agent]`) to control high-level agent 28 specific configurations. This section can only be defined once for all config 29 files and should be in the first file read in to take effect. This cannot be 30 defined per-config file. 31 32 Telegraf also uses array of tables (e.g. `[[inputs.file]]`) to define multiple 33 plugins. These can be specified as many times as a user wishes. 34 35 ## In-line Table vs Table 36 37 In some cases, a configuration option for a plugin may define a table of 38 configuration options. Take for example, the ability to add arbitrary tags to 39 an input plugin: 40 41 ```toml 42 [[inputs.cpu]] 43 percpu = false 44 totalcpu = true 45 [inputs.cpu.tags] 46 tag1 = "foo" 47 tag2 = "bar" 48 ``` 49 50 User's should understand that these tables *must* be at the end of the plugin 51 definition, because any key-value pair is assumed to be part of that table. The 52 following demonstrates how this can cause confusion: 53 54 ```toml 55 [[inputs.cpu]] 56 totalcpu = true 57 [inputs.cpu.tags] 58 tag1 = "foo" 59 tag2 = "bar" 60 percpu = false # this is treated as a tag to add, not a config option 61 ``` 62 63 Note TOML does not care about how a user indents the config or whitespace, so 64 the `percpu` option is considered a tag. 65 66 A far better approach to avoid this situation is to use inline table syntax: 67 68 ```toml 69 [[inputs.cpu]] 70 tags = {tag1 = "foo", tag2 = "bar"} 71 percpu = false 72 totalcpu = true 73 ``` 74 75 This way the tags value can go anywhere in the config and avoids possible 76 confusion. 77 78 ## Basic String vs String Literal 79 80 In basic strings, signified by double-quotes, certain characters like the 81 backslash and double quote contained in a basic string need to be escaped for 82 the string to be valid. 83 84 For example the following invalid TOML, includes a Windows path with 85 unescaped backslashes: 86 87 ```toml 88 path = "C:\Program Files\" # this is invalid TOML 89 ``` 90 91 User's can either escape the backslashes or use a literal string, which is 92 signified by single-quotes: 93 94 ```toml 95 path = "C:\\Program Files\\" 96 path = 'C:\Program Files\' 97 ``` 98 99 Literal strings return exactly what you type. As there is no escaping in literal 100 strings you cannot have an apostrophe in a literal string.