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.