How to configure a Filebeat file output

Writing Filebeat events to local disk is useful for troubleshooting pipelines, capturing a reproducible sample for offline parsing, and inspecting the exact JSON that would otherwise be shipped to a remote output.

In Filebeat, the active output determines where published events are delivered. The output.file backend writes each event as newline-delimited JSON (.ndjson) and rotates files when they reach the configured size limit, keeping only a fixed number of historical files.

File output is primarily intended for testing and can fill storage quickly when rotation limits are large or events are high-volume. Keeping the dump directory separate from /var/log/filebeat avoids mixing event dumps with Filebeat self-logs, and the permissions setting controls who can read the generated files. YAML indentation and invalid keys prevent startup, so configuration validation should happen before restarting the service.

1. Open the Filebeat configuration file.

   $ sudo nano /etc/filebeat/filebeat.yml

   YAML nesting is indentation-based, so whitespace changes can alter meaning.

2. Create a directory for the output files.

   $ sudo install -d -o root -g root -m 0750 /var/lib/filebeat/file-output

   The directory must be writable by the account running the Filebeat service.

3. Configure the file output.

   #output.elasticsearch:
   #  hosts: ["http://localhost:9200"]
   
   output.file:
     path: "/var/lib/filebeat/file-output"
     filename: "filebeat-events"
     rotate_every_kb: 10240
     number_of_files: 7
     permissions: 0600
     rotate_on_startup: true

   Filebeat supports a single enabled output; comment out other output.* sections.

   Large rotate_every_kb or number_of_files values can consume disk space quickly under path.

4. Test the configuration for errors.

   $ sudo filebeat test config -c /etc/filebeat/filebeat.yml
   Config OK

   Related: How to test a Filebeat configuration

5. Restart the Filebeat service.

   $ sudo systemctl restart filebeat

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

6. Verify output files are created.

   $ sudo ls -1 /var/lib/filebeat/file-output
   filebeat-events-20260106.ndjson

   Filebeat appends a date/time suffix and .ndjson extension to the configured filename.

7. View a sample event from the output file.

   $ sudo head -n 1 /var/lib/filebeat/file-output/filebeat-events-*.ndjson
   {"@timestamp":"2026-01-06T22:45:31.038Z","@metadata":{"beat":"filebeat","type":"_doc","version":"8.19.9"},"log":{"offset":0,"file":{"path":"/var/log/app.log"}},"message":"file output sample line","input":{"type":"log"},"ecs":{"version":"8.0.0"},"host":{"name":"host"},"agent":{"id":"6115baa0-9dbc-4fd1-96b2-05cb49f81b9b","name":"host","type":"filebeat","version":"8.19.9","ephemeral_id":"1af4af51-800c-41fd-b472-1e83fef9e818"}}