mirror of
https://github.com/espressif/esp-idf.git
synced 2025-08-04 21:24:32 +02:00
docs: Add translation for api-guides/tools/diag_tool
This commit is contained in:
renpeiying
@@ -2,6 +2,8 @@
|
||||
IDF Diag
|
||||
********
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
IDF Diag is a tool intended to speed up and assist in troubleshooting problems associated with the ESP-IDF environment and projects. It integrates the esp-idf-diag_ Python package into :ref:`idf.py`. IDF Diag gathers information about installed IDF tools, the Python environment, project artifacts, logs and other relevant data, storing them in a report directory. The report directory can be easily reviewed and supplemented with files that were not automatically collected but are considered pertinent to the reported issue. Once the report directory is complete, it can be compressed into a zip file and shared, such as by attaching it to a GitHub issue.
|
||||
|
||||
Creating Report Directory
|
||||
@@ -21,7 +23,7 @@ By default, the diagnostic data in the report directory is redacted to remove po
|
||||
|
||||
.. note::
|
||||
|
||||
Please make sure to thoroughly check the report directory for any sensitive information before sharing and remove files you do not want to share. Kindly include any additional files you find relevant that were not automatically added.
|
||||
Please make sure to thoroughly check the report directory for any sensitive information before sharing, and remove files you do not want to share. Kindly include any additional files you find relevant that were not automatically added.
|
||||
|
||||
Creating Zip Archive
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
@@ -32,9 +34,9 @@ After the report directory has been checked and is ready, it can be archived int
|
||||
|
||||
$ idf.py diag --zip <REPORT_DIRECTORY>
|
||||
|
||||
The ``REPORT_DIRECTORY`` refers to the directory created by the ``idf.py diag`` command. By default, the zip archive is named after the ``REPORT_DIRECTORY`` with a .zip extension. For instance, it might be named ``idf-diag-5aaa949b-40dc-4d53-96f1-1280c801585a.zip``. You can specify a different name for the output zip archive using the ``--output`` option.
|
||||
The ``REPORT_DIRECTORY`` refers to the directory created by the ``idf.py diag`` command. By default, the zip archive is named after the ``REPORT_DIRECTORY`` with a ``.zip`` extension. For instance, it might be named ``idf-diag-5aaa949b-40dc-4d53-96f1-1280c801585a.zip``. You can use the ``--output`` option to specify a different filename.
|
||||
|
||||
The report archive can now be shared, for example, by attaching it to a GitHub issue. It might offer useful insights into your project environment that could assist in resolving any problems you are facing.
|
||||
The report archive can now be shared, for example, by attaching it to a GitHub issue. It might provide key insights into the project environment, helping with issue diagnosis.
|
||||
|
||||
|
||||
Additional Information
|
||||
|
||||
@@ -1 +1,49 @@
|
||||
.. include:: ../../../en/api-guides/tools/idf-diag.rst
|
||||
*****************
|
||||
IDF Diag 诊断工具
|
||||
*****************
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
IDF Diag 是一个诊断工具，用于加速和辅助排查与 ESP-IDF 环境及项目相关的问题。它将 esp-idf-diag_ Python 包集成到了 :ref:`idf.py` 中，能够收集已安装的 IDF 工具、Python 环境、项目构建产物、日志及其他相关数据，并将其存储到一个报告目录下。可以轻松查看该报告目录的内容，并可在其中补充未被自动收集但与问题相关的文件。报告目录整理完成后，可以将其压缩为 zip 文件并进行分享，例如，将其添加到 GitHub Issue 的附件中。
|
||||
|
||||
创建报告目录
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
可使用默认配置生成诊断信息报告目录：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ idf.py diag
|
||||
|
||||
报告目录将创建在在当前目录下，命名为 ``idf-diag-UUID``。其中， ``UUID`` 是随机生成的全局唯一标识符 (Universally Unique Identifier)，类似 ``idf-diag-5aaa949b-40dc-4d53-96f1-1280c801585a``。使用 ``--output`` 选项可以指定不同的输出目录。如果指定的输出目录已存在，则 ``idf.py diag`` 命令不会执行，除非提供 ``--force`` 选项。
|
||||
|
||||
诊断数据通过 YAML 配置文件（名为 ``recipes``）收集。该文件定义了需包含在报告中的命令输出及需要复制的文件。可通过 ``idf.py --list`` 命令查看可用的 recipes 文件。默认情况下，所有 ``builtin`` recipes 均会使用，但可以通过 ``--recipe`` 选项修改，或使用 ``--tag`` 选项选择带有特定 ``tags`` 的 recipes 文件。更多信息，请参考 ``idf.py diag --help`` 以及 recipes_ 的详细描述。
|
||||
|
||||
默认情况下，报告目录中的诊断数据会进行脱敏处理，以移除可能包含的敏感信息，例如 URL 中的密码和令牌。此处理过程基于名为 ``purge`` 的 YAML 配置文件，其中包含由正则表达式和替换字符串组成的清理规则。可以使用 ``--purge`` 选项指定自定义的 purge 文件。详细信息请参考 purge_ 文件描述。
|
||||
|
||||
.. note::
|
||||
|
||||
在共享报告目录前，务必仔细检查目录中是否包含敏感信息，删除不希望共享的文件。此外，请手动添加未自动收集但与问题相关的其他文件。
|
||||
|
||||
创建 Zip 归档文件
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
检查并确认报告目录无误后，可将其归档为 zip 文件：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ idf.py diag --zip <REPORT_DIRECTORY>
|
||||
|
||||
其中，``REPORT_DIRECTORY`` 是由 ``idf.py diag`` 命令创建的报告目录。默认情况下，zip 归档文件的名称与 ``REPORT_DIRECTORY`` 相同，并添加 ``.zip`` 扩展名，如 ``idf-diag-5aaa949b-40dc-4d53-96f1-1280c801585a.zip``。可以使用 ``--output`` 选项为其指定不同的文件名。
|
||||
|
||||
报告归档文件可用于分享，例如，将其附加到 GitHub issue，提供有关项目环境的重要信息，协助问题排查。
|
||||
|
||||
|
||||
其他信息
|
||||
^^^^^^^^
|
||||
|
||||
更多信息请参考 esp-idf-diag_ 项目，或通过 ``idf.py diag --help`` 查看帮助信息。
|
||||
|
||||
.. _esp-idf-diag: https://github.com/espressif/esp-idf-diag
|
||||
.. _recipes: https://github.com/espressif/esp-idf-diag/blob/master/esp_idf_diag/data/recipes/README.md
|
||||
.. _purge: https://github.com/espressif/esp-idf-diag/tree/master/esp_idf_diag/data/purge
|
||||
|
||||
Reference in New Issue
Block a user