Specify general settingsedit

You can specify settings in the filebeat.yml config file to control the general behavior of Filebeat. This includes:

  • Global options that control things like publisher behavior and the location of some files.
  • General options that are supported by all Elastic Beats.

Global Filebeat configuration optionsedit

These options are in the filebeat namespace.


The name of the registry file. If a relative path is used, it is considered relative to the data path. See the Directory layout section for details. The default is ${path.data}/registry.

filebeat.registry_file: registry

It is not possible to use a symlink as registry file.

The registry file is only updated when new events are flushed and not on a predefined period. That means in case there are some states where the TTL expired, these are only removed when new event are processed.


The full path to the directory that contains additional prospector configuration files. Each configuration file must end with .yml. Each config file must also specify the full Filebeat config hierarchy even though only the prospector part of the file is processed. All global options, such as registry_file, are ignored.

The config_dir option MUST point to a directory other than the directory where the main Filebeat config file resides.

If the specified path is not absolute, it is considered relative to the configuration path. See the Directory layout section for details.

filebeat.config_dir: path/to/configs


How long Filebeat waits on shutdown for the publisher to finish sending events before Filebeat shuts down.

By default, this option is disabled, and Filebeat does not wait for the publisher to finish sending events before shutting down. This means that any events sent to the output, but not acknowledged before Filebeat shuts down, are sent again when you restart Filebeat. For more details about how this works, see How does Filebeat ensure at-least-once delivery?.

You can configure the shutdown_timeout option to specify the maximum amount of time that Filebeat waits for the publisher to finish sending events before shutting down. If all events are acknowledged before shutdown_timeout is reached, Filebeat will shut down.

There is no recommended setting for this option because determining the correct value for shutdown_timeout depends heavily on the environment in which Filebeat is running and the current state of the output.

Example configuration:

filebeat.shutdown_timeout: 5s

General configuration optionsedit

These options are supported by all Elastic Beats. Because they are common options, they are not namespaced.

Here is an example configuration:

name: "my-shipper"
tags: ["service-X", "web-tier"]


The name of the Beat. If this option is empty, the hostname of the server is used. The name is included as the beat.name field in each published transaction. You can use the name to group all transactions sent by a single Beat.


name: "my-shipper"


A list of tags that the Beat includes in the tags field of each published transaction. Tags make it easy to group servers by different logical properties. For example, if you have a cluster of web servers, you can add the "webservers" tag to the Beat on each server, and then use filters and queries in the Kibana web interface to get visualisations for the whole group of servers.


tags: ["my-service", "hardware", "test"]


Optional fields that you can specify to add additional information to the output. Fields can be scalar values, arrays, dictionaries, or any nested combination of these. By default, the fields that you specify here will be grouped under a fields sub-dictionary in the output document. To store the custom fields as top-level fields, set the fields_under_root option to true.


fields: {project: "myproject", instance-id: "574734885120952459"}


If this option is set to true, the custom fields are stored as top-level fields in the output document instead of being grouped under a fields sub-dictionary. If the custom field names conflict with other field names, then the custom fields overwrite the other fields.


fields_under_root: true
  instance_id: i-10a64379
  region: us-east-1


A list of processors to apply to the data generated by the beat.

See Filter and enhance the exported data for information about specifying processors in your config.


Sets the maximum number of CPUs that can be executing simultaneously. The default is the number of logical CPUs available in the system.