Loading

Capture diagnostics

Stack ECE ECK ECH Self-Managed

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.

  • 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:

    curl -X GET -k 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

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

    • Windows

      .\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 dianostic batch or shell file.