elastic-agent-variable-substitution.asciidoc

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.

Refer to [providers] for more detail.

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

inputs:
 - id: unique-logfile-id
   type: logfile
   streams:
    - paths: /var/log/${foo}/another.log

providers:
  local:
    vars:
      foo: bar

The policy generated by this configuration looks like this:

inputs:
 - id: unique-logfile-id
   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:

inputs:
  - id: logfile-foo
    type: logfile
    path: "/var/log/foo"
  - id: logfile-unknown
    type: logfile
    path: "${ unknown.key }"

The policy generated by this configuration looks like this:

inputs:
  - id: logfile-foo
    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:

inputs:
  - id: logfile-foo
    type: logfile
    path: "/var/log/foo"
  - id: logfile-container
    type: logfile
    path: "${docker.paths.log|kubernetes.container.paths.log|'/var/log/other'}"

Escaping variables

In some cases the ${var} syntax causes an issue with using a value where the actually wanted variable is ${var}. In this case double $$ can be provided for the variable.

The double $$ causes the variable to be ignored and the extra $ is removed from the beginning.

For example, the following agent policy uses the escaped variable so the actual value is used instead.

inputs:
  - id: logfile-foo
    type: logfile
    path: "/var/log/foo"
    processors:
      - add_tags:
          tags: [$${development}]
          target: "environment"

The policy generated by this configuration looks like this:

inputs:
  - id: logfile-foo
    type: logfile
    path: "/var/log/foo"
    processors:
      - add_tags:
          tags: [${development}]
          target: "environment"