How to add custom fields in Filebeat

Custom fields in Filebeat attach stable metadata to every shipped event, which makes it easier to split dashboards, routing rules, and searches by environment, team, or workload without reparsing the original log message.

The top-level fields option in /etc/filebeat/filebeat.yml adds the same values to every published event. By default Filebeat keeps those values inside the fields object, while fields_under_root promotes them to top-level document keys when downstream queries or pipelines expect them there.

Leaving custom keys nested under fields is safer because it avoids collisions with existing Elastic Common Schema (ECS) fields or module-generated fields. Package installs usually run Filebeat as the filebeat.service unit, so the configuration should be validated with filebeat test config before restarting the service.

Steps to add custom fields in Filebeat:

Create a backup of the current Filebeat configuration before editing it.
```
$ sudo cp /etc/filebeat/filebeat.yml /etc/filebeat/filebeat.yml.bak
```
Restore the previous file quickly with sudo cp /etc/filebeat/filebeat.yml.bak /etc/filebeat/filebeat.yml if the updated config does not validate.
Open the Filebeat configuration file.
```
$ sudoedit /etc/filebeat/filebeat.yml
```
Add the custom fields in the global configuration.
```
fields:
  env: production
  team: platform
fields_under_root: false
```
With fields_under_root set to false, the exported events keep the values under fields.env and fields.team.

Switch fields_under_root to true only when downstream consumers need top-level keys, because a name collision can overwrite an existing event field.
Test the configuration for syntax and permission errors.
```
$ sudo filebeat test config -c /etc/filebeat/filebeat.yml
Config OK
```
Related: How to test a Filebeat configuration
Inspect the resolved configuration to confirm the fields are loaded as expected.
```
$ sudo filebeat export config -c /etc/filebeat/filebeat.yml | grep -nE '^(fields:|fields_under_root:|  env:|  team:)'
1:fields:
2:  env: production
3:  team: platform
4:fields_under_root: false
```
Use this check after later edits to confirm whether the fields stay nested under fields or are promoted to the document root.
Restart the Filebeat service to apply the updated fields.
```
$ sudo systemctl restart filebeat
```
Related: How to manage the Filebeat service with systemctl in Linux
Confirm the Filebeat service is active after the restart.
```
$ sudo systemctl is-active filebeat
active
```
When the unit does not return active, inspect sudo journalctl --unit=filebeat --no-pager --lines=80 for YAML, permission, or output connection errors.

Related: How to manage the Filebeat service with systemctl in Linux