elasticsearch/docs/reference/troubleshooting/diagnostic.asciidoc

[[diagnostic]]
== Capturing diagnostics
++++
<titleabbrev>Capture diagnostics</titleabbrev>
++++
:keywords: Elasticsearch diagnostic, diagnostics

The {es} https://github.com/elastic/support-diagnostics[Support Diagnostic] tool captures a point-in-time snapshot of cluster statistics and most settings. 
It works against all {es} versions. 

This information can be used to troubleshoot problems with your cluster. For examples of issues that you can troubleshoot using Support Diagnostic tool output, refer to https://www.elastic.co/blog/why-does-elastic-support-keep-asking-for-diagnostic-files[the Elastic blog].

You can generate diagnostic information using this tool before you contact https://support.elastic.co[Elastic Support] or 
https://discuss.elastic.co[Elastic Discuss] to minimize turnaround time. 

See this https://www.youtube.com/watch?v=Bb6SaqhqYHw[this video] for a walkthrough of capturing an {es} diagnostic.

[discrete]
[[diagnostic-tool-requirements]]
=== Requirements

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

[discrete]
[[diagnostic-tool-access]]
=== Access the tool

The Support Diagnostic tool is included as a sub-library in some Elastic deployments: 

* {ece}: Located under **{ece}** > **Deployment** > **Operations** > 
**Prepare Bundle** > **{es}**. 
* {eck}: Run as https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-take-eck-dump.html[`eck-diagnostics`].

You can also directly download the `diagnostics-X.X.X-dist.zip` file for the latest Support Diagnostic release
from https://github.com/elastic/support-diagnostics/releases/latest[the `support-diagnostic` repo].


[discrete]
[[diagnostic-capture]]
=== Capture diagnostic information

To capture an {es} diagnostic: 

. In a terminal, verify that your network and user permissions are sufficient to connect to your {es} 
cluster by polling the cluster's <<cluster-health,health>>.
+
For example, with the parameters `host:localhost`, `port:9200`, and `username:elastic`, you'd use the following curl request:
+
[source,sh]
----
curl -X GET -k -u elastic -p https://localhost:9200/_cluster/health
----
// NOTCONSOLE
+
If you receive a an HTTP 200 `OK` response, then you can proceed to the next step. If you receive a different 
response code, then <<diagnostic-non-200,diagnose the issue>> before proceeding.

. 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 https://github.com/elastic/support-diagnostics#standard-options[diagnostic 
parameter reference]. 
+
The following command options are recommended:
+
**Unix-based systems**
+
[source,sh]
----
sudo ./diagnostics.sh --type local --host localhost --port 9200 -u elastic -p --bypassDiagVerify --ssl --noVerify
----
+
**Windows**
+
[source,sh]
----
sudo .\diagnostics.bat --type local --host localhost --port 9200 -u elastic -p --bypassDiagVerify --ssl --noVerify
----
+
[TIP]
.Script execution modes
====
You can execute the script in three https://github.com/elastic/support-diagnostics#diagnostic-types[modes]: 

* `local` (default, recommended): Polls the <<rest-apis,{es} API>>, 
gathers operating system info, and captures cluster and GC logs. 

* `remote`: Establishes an ssh session 
to the applicable target server to pull the same information as `local`.

* `api`: Polls the <<rest-apis,{es} API>>. All other data must be 
collected manually.
====

. When the script has completed, verify that no errors were logged to `diagnostic.log`. 
If the log file contains errors, then refer to <<diagnostic-log-errors,Diagnose errors in `diagnostic.log`>>.

. If the script completed without errors, then 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.

[discrete]
[[diagnostic-non-200]]
=== Diagnose a non-200 cluster health response

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

HTTP 401 `UNAUTHENTICATED`::
Additional information in the error will usually indicate either 
that your `username:password` pair is invalid, or that your `.security` 
index is unavailable and you need to setup a temporary 
<<file-realm,file-based realm>> user with `role:superuser` to authenticate.

HTTP 403 `UNAUTHORIZED`::
Your `username` is recognized but 
has insufficient permissions to run the diagnostic. Either use a different 
username or elevate the user's privileges.

HTTP 429 `TOO_MANY_REQUESTS` (for example, `circuit_breaking_exception`)::
Your username authenticated and authorized, but the cluster is under 
sufficiently high strain that it's not responding to API calls. These 
responses are usually intermittent. You can proceed with running the diagnostic, 
but the diagnostic results might be incomplete.

HTTP 504 `BAD_GATEWAY`::
Your network is experiencing issues reaching the cluster. 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. 

HTTP 503 `SERVICE_UNAVAILABLE` (for example, `master_not_discovered_exception`)::
Your cluster does not currently have an elected master node, which is 
required for it to be API-responsive. This might be temporary while the master 
node rotates. If the issue persists, then <<cluster-fault-detection,investigate the cause>> 
before proceeding. 

[discrete]
[[diagnostic-log-errors]]
=== Diagnose errors in `diagnostic.log`

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 Elasticsearch version due to a system or network error - unable to continue.` 
+ 
This indicates that the diagnostic couldn't run commands against the cluster. 
Poll the cluster's health again, and ensure that you're using the same parameters 
when you run the dianostic batch or shell file.

* A `security_exception` that includes `is unauthorized for user`:
+
The provided user has insufficient admin permissions to run the diagnostic tool. Use another
user, or grant the user `role:superuser` privileges.