Document dollar-sign interpolation of configuration settings in config file

So, most interpolation you want to do in a filebeat config file is done with a percent sign and curly brackets, %{like.this}. However, you can also interpolate environment variables with a dollar sign, ${LIKE_THIS}. I've discovered that this dollar-sign interpolation also allows you to reference Filebeat configuration settings from other settings. For example, if you need to prospect logs at paths relative to Filebeat's home directory, you can do paths: ['${path.home}/../some/relative/path']. The odd thing is, this doesn't actually seem to be documented anywhere. Should this be added to the documentation?

Sigh. So it is documented, sort of. It's never actually described or explained in the documentation (certainly not in any of the sections with the word "variable" in their name), but a few sections do incidentally show this usage (without explaining it) in example blocks, such as "Load external configuration files" showing use of ${path.config}. It's likewise used in filebeat.reference.yml in several examples.

I'd still venture that this should be explicitly explained in a relevant section of the documentation, though.

The Beats configuration file format is documented under "Beats Platform". As the configuration file format, parsing and processing is shared between all beats.

See Config File Format.

String interpolation is a special 'type' supported by a few settings. See sprintf type. This one is the %{....} kind of setting.

Furthermore see Reference Variables and Environment Variables documentation for dollar sign setting like ${abc}.

The difference is, reference variables are applied only once, when the configuration file is parsed and unpacked. The String interpolation one is normally used per event (dynamic).

Any setting is can be used as a variable. At times people create phony settings for use as references only.

The paths settings are indeed the only ones pre-defined always. You can overwrite them from command line or even from within the configuration file. This indeed need to be documented better.

I'd suggest that when looking at the documentation for a given Beat such as Filebeat, the Beats Platform Documentation should be prominently included in the main documentation sidebar, perhaps between "Overview" and "Getting Started with ". Yes, the Beats Platform is mentioned at the bottom of the 'Overview' section underneath the diagram, but I think it needs be a bit more prominent than that. The platform documentation is necessary to understanding any individual beat in a way that the e.g. Logstash or Kibana documentation is not.

That said, once you do find it, the documentation itself is very helpful. So thanks for that. :grinning:

Thanks for your feedback about the docs! My plan is to make the content about the config file structure available in the docs for each Beat. It's on my to-do list. I'll bump the priority because it's been sitting on my pile for too long. I apologize for any confusion or churn this has caused you.

This topic was automatically closed 28 days after the last reply. New replies are no longer allowed.