How to enable Logstash persistent queues

Persistent queues in Logstash buffer events on disk to survive restarts and to bridge temporary downstream outages, reducing data loss when ingestion spikes or outputs slow down.

When queue.type is set to persisted, events are written to disk-backed queue segments under path.queue before being processed by filters and outputs. Checkpointing tracks what has been safely consumed so the pipeline can resume cleanly after a service restart.

Persistent queues trade durability for disk I/O and capacity planning. An undersized queue can still backpressure inputs during outages, while an oversized queue can fill the filesystem and stall ingestion until space is freed. Queue settings live in /etc/logstash/logstash.yml and take effect only after restarting the logstash service.

1. Enable the persistent queue in /etc/logstash/logstash.yml.

   queue.type: persisted
   queue.max_bytes: 1gb
   path.queue: /var/lib/logstash/queue

   queue.max_bytes caps the on-disk backlog; size it to cover peak downstream outages within available disk space.

   A persistent queue can fill the filesystem under path.queue, stalling ingestion and potentially impacting other services on the host.

2. Create the persistent queue directory with secure ownership and permissions for the logstash service account.

   $ sudo install -o logstash -g logstash -m 0750 -d /var/lib/logstash/queue
   $ sudo ls -ld /var/lib/logstash/queue
   drwxr-x--- 2 logstash logstash 6 Jan  5 12:34 /var/lib/logstash/queue

3. Test the pipeline configuration for syntax errors.

   $ sudo -u logstash /usr/share/logstash/bin/logstash --path.settings /etc/logstash --path.data /tmp/logstash-configtest --config.test_and_exit
   Configuration OK

   Related: How to test a Logstash pipeline configuration

4. Restart the Logstash service to apply queue settings.

   $ sudo systemctl restart logstash

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

5. Confirm the Logstash service is running.

   $ sudo systemctl status logstash --no-pager
   ● logstash.service - logstash
        Loaded: loaded (/usr/lib/systemd/system/logstash.service; enabled; preset: enabled)
        Active: active (running) since Wed 2026-01-07 12:41:59 UTC; 8s ago
   ##### snipped #####

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

6. Verify queue settings through the monitoring API.

   $ curl -s http://localhost:9600/_node/stats/pipelines/main?pretty=true
   {
   ##### snipped #####
         "queue" : {
           "data" : {
             "storage_type" : "overlay",
             "path" : "/var/lib/logstash/queue/main",
             "free_space_in_bytes" : 1933968424960
           },
           "capacity" : {
             "queue_size_in_bytes" : 1073741826,
             "max_unread_events" : 0,
             "max_queue_size_in_bytes" : 1073741824,
             "page_capacity_in_bytes" : 67108864
           },
           "events" : 1475830,
           "type" : "persisted",
           "events_count" : 1475830,
           "queue_size_in_bytes" : 1073741826,
           "max_queue_size_in_bytes" : 1073741824
         }
   ##### snipped #####
   }

   The monitoring API binds to http.host and http.port (default 127.0.0.1:9600); inspect /var/log/logstash/logstash-plain.log when the endpoint is unreachable.