How to add custom fields in Filebeat

Custom fields in Filebeat attach consistent metadata—such as environment, ownership, or workload tier—to every exported event, improving filtering, routing, and dashboard segmentation across shared log pipelines.

The fields setting adds a YAML map during event publishing. By default the map is stored under the fields object (for example fields.env), while fields_under_root merges the keys into the event root so they appear alongside other top-level fields.

Promoting fields to the root can overwrite existing keys when names collide with Elastic Common Schema fields or module-generated fields. Package installs typically use /etc/filebeat/filebeat.yml and run as filebeat.service under systemd, so configuration changes should be validated before applying them to the service.

Steps to add custom fields in Filebeat:

Open the Filebeat configuration file at /etc/filebeat/filebeat.yml.
```
$ sudo nano /etc/filebeat/filebeat.yml
```
Add the custom fields to the global configuration.
```
fields:
  env: production
  team: platform
fields_under_root: true
```
Setting fields_under_root to true can overwrite existing event fields with the same name.

Omit fields_under_root (or set it to false) to keep the values under fields in the event, for example fields.env and fields.team.
Test the configuration for errors.
```
$ sudo filebeat test config -c /etc/filebeat/filebeat.yml
Config OK
```
Related: How to test a Filebeat configuration
Restart the Filebeat service to apply the fields.
```
$ sudo systemctl restart filebeat
```
Related: How to manage the Filebeat service with systemctl in Linux

Check the service status for a clean start after the restart.

$ sudo systemctl status filebeat --no-pager
● filebeat.service - Filebeat sends log files to Logstash or directly to Elasticsearch.
     Loaded: loaded (/usr/lib/systemd/system/filebeat.service; enabled; preset: enabled)
    Drop-In: /etc/systemd/system/filebeat.service.d
             └─env.conf
     Active: active (running) since Tue 2026-01-06 22:30:48 UTC; 5s ago
       Docs: https://www.elastic.co/beats/filebeat
##### snipped #####

Confirm the fields appear in the exported configuration.

$ 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: true

Author: Mohd Shakir Zakaria
Mohd Shakir Zakaria is a cloud architect with deep roots in software development and open-source advocacy. Certified in AWS, Red Hat, VMware, ITIL, and Linux, he specializes in designing and managing robust cloud and on-premises infrastructures.