[[variable-substitution]]
== Variable substitution

The syntax for variable substitution is `${var}`, where `var` is the name of a
variable defined by a provider. A _provider_ defines key/value pairs that are
used for variable substitution and conditions. 

{agent} supports a variety of providers, such as `host` and `local`, that
supply variables to {agent}. For example, earlier you saw `${host.name}` used to
resolve the path to the host's log file based on the `{host.platform}` value. Both of these values
were provided by the `host` provider. 

All providers are enabled by default when {agent} starts. If a provider cannot
be configured, its variables are ignored.

See <<providers>> for more detail.

The following agent policy uses a custom key named `foo` to resolve a value
defined by a local provider:

[source,yaml]
----
inputs:
 - type: logfile
   streams:
    - paths: /var/log/${foo}/another.log

providers:
  local:
    vars:
      foo: bar

----

The policy generated by this configuration looks like this:

[source,yaml]
----
inputs:
 - type: logfile
   streams:
    - paths: /var/log/bar/another.log
----

When an input uses a variable substitution that is not present in the current
key/value mappings being evaluated, the input is removed in the result.

For example, this agent policy uses an unknown key:

[source,yaml]
----
inputs:
  - type: logfile
    path: "/var/log/foo"
  - type: logfile
    path: "${ unknown.key }"
----


The policy generated by this configuration looks like this:

[source,yaml]
----
inputs:
  - type: logfile
    path: "/var/log/foo"
----

=== Alternative variables and constants

Variable substitution can also define alternative variables or a constant.

To define a constant, use either `'` or `"`. When a constant is reached during
variable evaluation, any remaining variables are ignored, so a constant should
be the last entry in the substitution.

To define  alternatives, use `|` followed by the next variable or constant.
The power comes from allowing the input to define the preference order of the
substitution by chaining multiple variables together.

For example, the following agent policy chains together multiple variables to
set the log path based on information provided by the running container
environment. The constant `/var/log/other` is used to end of the path, which is
common to both providers:

[source,yaml]
----
inputs:
  - type: logfile
    path: "/var/log/foo"
  - type: logfile
    path: "${docker.paths.log|kubernetes.container.paths.log|'/var/log/other'}"
----
