How to enable Logstash persistent queues

Persistent queues in Logstash write in-flight events to local disk so short restarts and downstream output slowdowns do not leave events only in process memory. They are useful when a pipeline needs more durability than the default memory queue and the host has local disk capacity reserved for queued events.

The package settings file controls the default queue mode for the Logstash service. Setting queue.type to persisted applies to every pipeline unless a pipeline-specific entry overrides it, and each pipeline gets its own queue directory named from the pipeline.id value.

Packaged installs store queue files under the service data directory unless path.queue points to another local filesystem. Keep queue files on local storage, budget queue.max_bytes across all pipelines, and use queue.drain: true only when shutdowns can wait for the backlog to empty.

1. Open the packaged Logstash settings file.

   $ sudoedit /etc/logstash/logstash.yml

2. Enable the persisted queue and set the queue size.

   queue.type: persisted
   queue.max_bytes: 1gb

   queue.max_bytes is applied per pipeline. Leave path.queue unset when the default /var/lib/logstash/queue is on the intended local disk; set path.queue only when queue pages must live on another local filesystem.

   Elastic does not support storing persistent queue data on NFS. Reserve enough local disk for queue pages, checkpoints, logs, JVM temp files, and normal host operations.

3. Create the default queue directory with logstash ownership.

   $ sudo install -o logstash -g logstash -m 0750 -d /var/lib/logstash/queue

   Logstash can create the default queue directory at startup, but creating it explicitly confirms the filesystem and permissions before the restart.

4. Confirm the default queue directory ownership.

   $ sudo ls -ld /var/lib/logstash/queue
   drwxr-x--- 2 logstash logstash 4096 Jun 18 20:54 /var/lib/logstash/queue

   The owner and group should both be logstash before the service writes queue files under this path.

5. Validate the packaged configuration before restarting the service.

   $ sudo -u logstash /usr/share/logstash/bin/logstash --path.settings /etc/logstash --path.data /tmp/logstash-configtest-pq --config.test_and_exit
   Using bundled JDK: /usr/share/logstash/jdk
   ##### snipped #####
   Configuration OK
   [2026-06-18T20:54:44,136][INFO ][logstash.runner          ] Using config.test_and_exit mode. Config Validation Result: OK. Exiting Logstash

   The temporary --path.data directory keeps default queue and dead-letter-queue validation data under /tmp. If path.queue is set to an absolute path, the test must be able to write that path too.

   Logstash defaults allow_superuser to false, so package-based validation should run as the logstash service account unless that setting was intentionally changed.
   Related: How to test a Logstash pipeline configuration

6. Restart the Logstash service so the queue settings take effect.

   $ sudo systemctl restart logstash.service

   Restarting Logstash pauses every active pipeline while inputs reopen, filters recompile, and outputs reconnect. Changes in /etc/logstash/logstash.yml are not applied by automatic pipeline reload.
   Related: How to manage the Logstash service with systemctl in Linux

7. Confirm that the service and API endpoint came back after the restart.

   $ sudo journalctl -u logstash.service --since "5 minutes ago" --no-pager --lines=20
   Jun 18 20:55:02 logstash-01 systemd[1]: Started logstash.service - logstash.
   Jun 18 20:55:03 logstash-01 logstash[2147]: [2026-06-18T20:55:03,184][INFO ][logstash.agent           ] Successfully started Logstash API endpoint {:port=>9600, :ssl_enabled=>false}
   Jun 18 20:55:03 logstash-01 logstash[2147]: [2026-06-18T20:55:03,413][INFO ][logstash.agent           ] Pipelines running {:count=>1, :running_pipelines=>[:main], :non_running_pipelines=>[]}

   If the API line does not appear, inspect /var/log/logstash/logstash-plain.log or rerun the configuration test before retrying the restart.

8. Query the pipeline stats API and confirm that the queue type is persisted.

   $ curl --silent 'http://localhost:9600/_node/stats/pipelines/main?pretty'
   {
     "pipelines" : {
       "main" : {
         "queue" : {
           "type" : "persisted",
           "capacity" : {
             "max_queue_size_in_bytes" : 1073741824,
             "page_capacity_in_bytes" : 67108864,
             "queue_size_in_bytes" : 1,
             "max_unread_events" : 0
           },
           "data" : {
             "path" : "/var/lib/logstash/queue/main"
           }
         }
       }
     }
   ##### snipped #####
   }

   Replace main when /etc/logstash/pipelines.yml uses a different pipeline.id. Packaged installs normally expose the node API on localhost within the 9600-9700 port range unless api.http.host or api.http.port changes that listener.

9. Confirm that Logstash created persistent-queue checkpoint and page files.

   $ sudo ls -lh /var/lib/logstash/queue/main
   total 8.0K
   -rw-r--r-- 1 logstash logstash  34 Jun 18 20:55 checkpoint.head
   -rw-r--r-- 1 logstash logstash 64M Jun 18 20:55 page.0

   The main directory name matches the pipeline ID. Additional pipelines create separate queue directories under the same path.queue root.

   Positive queue_persisted_growth_bytes or queue_persisted_growth_events in the stats API output means inputs are writing faster than outputs are draining.
   Related: How to check Logstash pipeline metrics

10. Remove the temporary validation data directory.

    $ sudo rm --recursive --force /tmp/logstash-configtest-pq