Type to search.

Capture Logstash diagnostics

Stack 9.0+

The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats.

Availability

  • Generally available since 9.0

    This functionality is generally available and ready for production usage.

Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments.

This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

The Logstash Support Diagnostic tool captures a point-in-time snapshot of its statistics and most settings. It works against all Logstash versions.

This information can be used to troubleshoot problems with your data pipeline. For examples of issues that you can troubleshoot using Support Diagnostic tool output, refer to the Elastic blog.

You can generate diagnostic information using this tool before you contact Elastic Support or Elastic Discuss to minimize turnaround time.

See this video for a walkthrough of capturing a Logstash diagnostic.

Note

This archive file is redacted for privacy as much as possible, but might still contain host-identifying metadata such as IP addresses or domain information. You should not upload this output to public forums. Uploads to the Elastic Support Portal are handled in accordance with the Elastic Privacy Statement.

  • Java Runtime Environment or Java Development Kit v1.8 or higher

You can directly download the diagnostics-X.X.X-dist.zip file for the latest Support Diagnostic release from the support-diagnostic repo.

To capture a Logstash diagnostic:

  1. In a terminal, verify that your network access is sufficient to connect to your Logstash node by polling its root endpoint.

    For example, with the parameters api.http.host: 127.0.0.1 and api.http.port: 9600 without authentication (default), you’d use the following curl request:

    Shell 
    curl -X GET http://127.0.0.1:9600?pretty

    If you receive a an HTTP 200 OK response, you can proceed to the next step. If you receive a different response code, diagnose the issue before proceeding.

  2. Using the same environment parameters, run the diagnostic tool script.

    For information about the parameters that you can pass to the tool, refer to the diagnostic parameter reference.

    The following command options are recommended:

    • Unix-based systems

      Shell 
      sudo ./diagnostics.sh --type logstash-local --host 127.0.0.1 --port 9600 --bypassDiagVerify

    • Windows

      Shell 
      .\diagnostics.bat --type logstash-local --host 127.0.0.1 --port 9600 --bypassDiagVerify
    Tip

    You can run the script in three modes:

    • local (default, recommended): Polls the Logstash API, gathers operating system info, and captures node logs.
    • remote: Establishes an ssh session to the applicable target server to pull the same information as local.
    • api: Polls the Logstash API. All other data must be collected manually.

  3. When the script has completed, verify that no errors were logged to diagnostic.log. If the log file contains errors, refer to Diagnose errors in diagnostic.log.

  4. If the script completed without errors, an archive with the format <diagnostic type>-diagnostics-<DateTimeStamp>.zip is created in the working directory, or an output directory you have specified. You can review or share the diagnostic archive as needed.

When you poll your node, if you receive any response other than 200 0K, the diagnostic tool might not work as intended. The following are possible error codes and their resolutions:

HTTP 401 UNAUTHENTICATED
Your team has setup Logstash API Security and one/both of your api.auth.basic.username or api.auth.basic.password pair is invalid.
HTTP 504 BAD_GATEWAY
Your network is experiencing issues reaching the node. You might be using a proxy or firewall. Consider running the diagnostic tool from a different location, confirming your port, or using an IP instead of a URL domain.

The following are common errors that you might encounter when running the diagnostic tool:

  • Error: Could not find or load main class com.elastic.support.diagnostics.DiagnosticApp

    This indicates that you accidentally downloaded the source code file instead of diagnostics-X.X.X-dist.zip from the releases page.

  • Could not retrieve the {{ls}} version due to a system or network error - unable to continue.

    This indicates that the diagnostic couldn’t run commands against the node. Poll the root endpoint again, and ensure that you’re using the same parameters when you run the diagnostic batch or shell file.