Validate a Logstash configuration before starting it

Run Logstash with --config.test_and_exit to validate its pipeline configuration and exit without starting normal event processing:

# Check one configuration file.
bin/logstash --config.test_and_exit -f logstash.conf

# Check the combined configuration loaded from a directory.
bin/logstash --config.test_and_exit -f /etc/logstash/conf.d/

For a packaged installation, specify the settings directory used by the service when necessary:

/usr/share/logstash/bin/logstash \
  --path.settings /etc/logstash \
  --config.test_and_exit \
  -f /etc/logstash/conf.d/

Use the command's exit status in CI: zero means the configuration check succeeded; a nonzero status should block rollout. Successful logs normally include Configuration OK, but do not rely only on a text match.

Know what the check does not prove

This mode does not validate grok pattern correctness or prove that a pattern matches your records. It also does not prove that Elasticsearch is reachable, an output can authenticate, or the service account can read the intended log files.

Follow it with a small input-to-output test using known records, expected fields and types, failure cases, and the intended destination. Keep the plugin versions, settings, and environment variables aligned with production.

Files loaded from one configuration directory are combined in lexical order into one pipeline. Splitting inputs and filters into different files does not isolate them. If production uses pipelines.yml, validate the intended pipeline definitions rather than accidentally testing a different combined layout.

Test a containerized deployment

Use the same versioned image as the deployment:

export LOGSTASH_IMAGE='docker.elastic.co/logstash/logstash:8.19.0'
docker run --rm \
  -v "$PWD/conf.d:/usr/share/logstash/pipeline:ro" \
  "$LOGSTASH_IMAGE" \
  --config.test_and_exit -f /usr/share/logstash/pipeline/

The version here is an example, not a recommendation to change your deployed release. Include required custom plugins and settings in the test image.

Older instructions may refer to --configtest; use the flag documented by your installed release instead of assuming every 5.x installation uses the old spelling. Automatic reload can apply an accepted change without restarting the JVM, but inspect reload logs and actual event delivery after each change.

References

• Elastic: running logstash command line
• Elastic: logstash settings file
• Elastic: reloading config