Replace the original diag implementation in idf.py with the new one in a
separate esp-idf-diag python package. The interface is kept the same as
it was. The simple idf.py diag test is also preserved.
Signed-off-by: Frantisek Hrbata <frantisek.hrbata@espressif.com>
At present, the diag tool uses its default purge file. However, users
may find it beneficial to specify and reuse their own purge file. A new
command line option, --purge, has been introduced to allow users to
provide their own purge file to diag. When this option is used, the
default purge file is ignored.
Signed-off-by: Frantisek Hrbata <frantisek.hrbata@espressif.com>
At present, the steps are executed unconditionally. With this
modification, we can restrict each step individually to determine if it
should run on a particular system. For instance, we can execute
different commands on different systems. This is achieved by adding a
new key, "system," to the step dictionary, with possible values being
Linux, Windows, and Darwin.
Signed-off-by: Frantisek Hrbata <frantisek.hrbata@espressif.com>
Currently, if a command run by the exec command returns an error
code, its stdout and stderr are not saved. It could be beneficial to
store at least the stderr if requested. Additionally, avoid creating
output files when there is no content and also store the stderr
of the failed command to diag.log.
Signed-off-by: Frantisek Hrbata <frantisek.hrbata@espressif.com>
The initial implementation of a diagnostic tool that collects valuable
information about esp-idf and failed build to assist in investigating
reported issues.
The gathered information includes environmental variables, details about
the python virtual environment, installed tools, platform information,
project_description.json, sdkconfig, build logs, map file, linker
scripts, and others.
usage:
1) create the default report
# allow diag to create the report directory name
$ idf.py diag
# explicitly specify the report directory
$ idf.py diag --output <report directory>
2) examine the contents of the generated <report directory> for
sensitive information and add additional content to the
<report directory>
3) create report archive zip file that can be shared or attached to
the reported issue
$ idf.py diag --zip <report directory>
The tool collects information as described in what are known as recipe
files. A recipe file is a YAML file, similar to an Ansible playbook or a
GitHub action, but much more simplified. Each recipe outlines how to
gather a set of related information. For instance, the manager.yml
recipe gathers data related to the component manager. Each recipe
includes metadata such as its description, tags, and steps. Tags are
used to determine which recipes to use; by default, all built-in recipes
located in tools/idf_py_actions/diag/recipes are used. Steps consist of
a list of commands to be executed. Currently, there are four commands:
file, exec, env, and glob. For more detailed information about recipes,
their format, and commands, please refer to
tools/idf_py_actions/diag/recipes/README.md.
Recipe example for component manager:
description: IDF Component Manager information
tags: [manager, base, project]
output: manager
steps:
- name: 'IDF Component Manager'
cmds:
- exec:
cmd: 'python -m idf_component_manager version'
output: manager.ver
- file:
path: '${PROJECT_DIR}/dependencies.lock'
- glob:
# Gather all idf_component.yml files from the project directory and
# save them in directories relative to the project directory within
# the idf_component directory.
pattern: 'idf_component.yml'
recursive: true
relative: true
path: '${PROJECT_DIR}'
output: 'idf_component/'
Create report for manager
1) all recipes with manager tag
$ idf.py diag --tag manager
2) use only the manager recipe explicitly; built-in recipes can be
referenced simply by their name, but all recipes can be referenced
by their path
$ idf.py diag --recipe manager
or
$ idf.py diag --recipe <full path>
To display available recipes, use
$ idf.py diag --list
and to verify recipes, use
$ idf.py diag --check
Both --list and --check honers the --tag and --recipe options.
Signed-off-by: Frantisek Hrbata <frantisek.hrbata@espressif.com>
