The esp-idf-diag tool gathers information about the ESP-IDF environment, the system information, and the ESP-IDF project into a report directory to help with troubleshooting problems.
You can install the esp-idf-diag tool from the Python Package Index (PyPI) using:
$ pip install esp-idf-diag
In an activated ESP-IDF environment, execute the following in your ESP-IDF project:
$ esp-idf-diag create
By default, this will create a report directory named diag-UUID, where UUID
is a randomly generated Universally Unique Identifier. For example
diag-5aaa949b-40dc-4d53-96f1-1280c801585a. You can change the output
directory using the --output option. This directory will contain files that
were collected and generated by esp-idf-diag. You can review the contents and
add or remove files as necessary.
Once the report directory is prepared, it can be compressed into a zip archive with:
$ esp-idf-diag zip diag-5aaa949b-40dc-4d53-96f1-1280c801585a
Please be aware that the report directory name is taken from the create example
mentioned earlier. This name will vary with each create run unless the
--output option is specified.
The zip archive can be attached to a GitHub issue to provide more context for a problem you are experiencing.
The data collected by esp-idf-diag is managed through recipes, which are straightforward YAML files containing commands whose outputs are saved in the report directory. For further details, please refer to the Recipe format description.
When a report directory is created, its contents are scanned for sensitive
information, such as passwords or tokens in URLs. This process is guided by a
purge file, in YAML format, that specifies which matching regular expressions
should be replaced. For further details, refer to the Purge format
description. A default purge file is
available, but you can provide a custom one using the --purge option. It is
recommended to review the generated report directory for sensitive data before
sharing it.