Run ECE diagnostics tooledit

ECE diagnostics is a command line tool that you can run on hosts where the ECE instance is installed. It collects logs and metrics, and stores everything into an archive file that can be provided to Elastic support for troubleshooting and investigation purposes.

This archive file is privacy-redacted as much as possible, but may still contain host identifying metadata (such as IP/domain info). We therefore recommend against uploading this output to public forums. Any uploads to the Elastic Support Portal are treated according to the Elastic Privacy Statement.


The ECE diagnostics tool comes bundled in ECE images for version 3.3 and onwards. For versions 3.3 and onward, you can export the diagnostic bundle within the ECE host’s image.

docker cp frc-runners-runner:/elastic_cloud_apps/ece-diagnostics/ece-diagnostics .

For versions before 3.3, please first manually install this diagnostic tool from the latest ECE version’s image:

  1. Confirm the latest ECE version

    curl -s | head | grep 'CLOUD_ENTERPRISE_VERSION'
  2. Download the bundled diagnostic from the latest ECE version’s image and copy out the bundled diagnostic. To run this command, replace $CLOUD_ENTERPRISE_VERSION with the latest version. To manually specify the ECE platform, which is default auto-detected, append either --platform linux/amd64 or --platform linux/arm64.

    docker run --rm -v $( pwd ):/export$CLOUD_ENTERPRISE_VERSION /bin/sh -c "cp /elastic_cloud_apps/ece-diagnostics/ece-diagnostics /export"
  3. Once the bundled diagnostic is exported, you can delete this latest version’s image, again replacing $CLOUD_ENTERPRISE_VERSION with the latest version.


How to useedit

To run the default diagnostic

./ece-diagnostics run

This tool supports various command line flags. You can also run it with -h or --help to print all available subcommands and options:

./ece-diagnostics --help

For example, Elastic Support frequently requests pulling the ECE diagnostic along with certain deployment diagnostics. You can pull these together via:

./ece-diagnostics run --deployments MY_DEPLOYMENT_ID_1,MY_DEPLOYMENT_ID_2

ECE deployment diagnostics are not the same as stack diagnostics, which Elastic support may also request. You can get stack diagnostics from Elastic Cloud Enterprise > Deployment > Operations > Prepare Bundle.

Example outputedit

When you run the ECE diagnostics tool on the host you want to troubleshoot, you might get an output similar to this one:

✓ collected information on certificates (took: 104ms)
✓ collected information on client-forwarder connectivity (took: 369ms)
✓ collected API information for ECE and Elasticsearch (took: 9.117s)
✓ collected ZooKeeper stats (took: 9.146s)
✓ collected ECE metricbeat data (took: 12.534s)
✓ collected system information (took: 12.992s)
✓ collected host logs for ECE (took: 29.222s)
✓ collected Docker info and logs (took: 29.246s)
Finished creating file: /tmp/ecediag- (total: 48.937s)

At that point, you’re ready to upload the .tar.gz file to Elastic Support.