ESP-IDF IDF Diag 诊断工具指南一键收集环境信息、脱敏并打包分享【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idfIDF Diag 是 ESP-IDF 官方集成在idf.py中的故障排查辅助工具用于一键收集已安装的 IDF 工具、Python 环境、项目构建产物、日志等诊断数据并生成报告目录。本文基于 docs/en/api-guides/tools/idf-diag.rst 整理并结合仓库中 diag_ext.py 的插件实现与 test_idf_diag.py 的端到端测试讲解报告目录的创建、recipes 与 purge 配置机制、敏感信息脱敏以及 zip 归档分享的完整工作流。IDF Diag 是什么当 ESP-IDF 环境或项目出现问题时排查过程往往需要先弄清机器上到底装了什么、项目是怎么构建的、日志里有什么。IDF Diag 正是为加速这一过程而生的工具它将独立的esp-idf-diagPython 包集成进 idf.py对应源码位于 diag_ext.py自动收集已安装的 IDF 工具及其版本信息Python 环境信息项目构建产物build artifacts日志及其他与问题相关的数据。所有数据被汇总到一个报告目录report directory中你可以直接查看、补充手动收集的相关文件最终压缩为 zip 归档并分享——例如作为附件提交到 GitHub Issue帮助维护者快速定位环境层面的问题。从源码结构看diag_ext.py将diag命令以 action 插件形式注册到idf.pyaction_extensions()返回的actions字典中定义了diag动作及其全部参数选项并最终调用python -m esp_idf_diag command来执行实际工作见 diag_ext.py。也就是说idf.py diag是esp-idf-diag包的薄封装命令实际包含create默认、list、check、zip四个子命令。创建报告目录使用默认配置生成诊断报告目录非常简单$ idf.py diag该命令会在当前目录下创建一个名为idf-diag-UUID的目录其中UUID是随机生成的通用唯一标识符例如idf-diag-5aaa949b-40dc-4d53-96f1-1280c801585a指定输出目录与覆盖行为通过--output简写-o选项可指定不同的输出目录路径$ idf.py diag --output my_report如果指定的输出目录已经存在命令默认不会继续执行只有加上--force简写-f选项才会删除已存在的目标文件或目录后重新创建源码中该选项说明为 Delete the target file or directory if it already exists before creating it.。在 diag_ext.py 中可以看到未指定--output时默认输出名由uuid.uuid4()生成格式正是idf-diag-{UUID}。串口端口自动检测值得留意的是执行create时若未通过--port指定目标串口IDF Diag 会给出提示并采用自动检测日志会输出类似下面的提示见 diag_ext.pyThe target serial port is not specified, so autodetection will be used. To set it manually, use the --port option. Example: idf.py --port /dev/ttyUSB0 diag.也就是说--port需写在子命令之前idf.py --port /dev/ttyUSB0 diag。Recipes诊断数据的收集配置诊断数据不是硬编码收集的而是由一组称为recipes的 YAML 配置文件驱动。每个 recipe 定义了哪些命令的输出应被纳入报告哪些文件需要被复制进报告。查看可用 recipes$ idf.py diag --list对应底层list子命令源码中简写为-l帮助信息为 Show information about available recipes.该命令会列出可用的 recipe 及其标签tags是挑选 recipe 前的第一步。你也可以用--check简写-c来校验 recipe 配置是否合法Validate recipes.。选择 recipe 与标签默认情况下所有builtin内置recipes 都会被使用。使用--recipe简写-r可指定使用的 recipe该选项可多次指定参数可以是 recipe 文件路径也可以是内置 recipe 的文件名主干file name stem。使用--tag简写-t可按标签筛选 recipe同样支持多次指定仅选择包含对应 TAG 的 recipe各 recipe 的 TAG 信息可通过-l/--list查看。--append简写-a选项用于将-r指定的 recipe 与内置 recipes组合使用而不是替换默认集合。从实现看--recipe与--tag都会被透传为esp_idf_diag的对应参数并始终携带--project-dir与--build-dir取自idf.py的项目目录与构建目录上下文确保诊断收集针对当前项目进行见 diag_ext.py。Purge敏感信息脱敏报告目录中可能包含 URL 中的密码、令牌等敏感信息。因此 IDF Diag 默认会对收集到的诊断数据进行**脱敏redaction**处理。脱敏规则由名为purge的 YAML 配置文件定义其中包含若干由正则表达式 替换字符串组成的清理规则。相关行为在测试中可以得到验证tools/test_idf_diag/test_idf_diag.py中测试向idf_component.yml写入带凭据的 URLhttps://username:passwordgithub.com/username/repository.git重新生成报告后报告内对应文件的内容变为https://[XXX]github.com/username/repository.git即密码部分被[XXX]替换完成脱敏见 test_idf_diag.py。使用自定义 purge 文件默认 purge 规则由esp-idf-diag包内置但你也可以通过--purge简写-p选项指定自定义的 purge YAML 文件从而按自己的合规要求调整脱敏规则帮助信息Use a custom purge file to remove sensitive information from the report.。分享前的必做检查请在共享报告目录之前仔细检查其中是否仍含敏感信息删除任何你不想分享的文件同时如果有未被自动收集但你认为与问题相关的文件请一并手动补充到报告目录中。这也是create命令完成后控制台日志会再次强调的建议见 diag_ext.py。创建 Zip 归档报告目录检查、补充完毕且确认无误后即可归档为 zip 文件$ idf.py diag --zip REPORT_DIRECTORY其中REPORT_DIRECTORY是之前由idf.py diag创建的报告目录。默认情况下zip 归档文件的名称与报告目录同名并追加.zip扩展名例如idf-diag-5aaa949b-40dc-4d53-96f1-1280c801585a.zip可通过--output选项为 zip 文件指定不同的文件名或路径。若目标 zip 文件已存在同样需要--force才会覆盖。归档完成后这个 zip 文件就可以分享出去了——例如作为附件附加到 GitHub Issue其中包含的项目环境关键信息能显著加速问题诊断。底层zip子命令同样支持--debug、--no-color等通用选项见 diag_ext.py。完整工作流与端到端验证结合仓库中的测试用例 test_idf_diag.py一个典型的 IDF Diag 使用闭环如下构建目标工程测试中以hello_world示例为例先fullclean再build在工程目录下生成报告目录$ idf.py diag --output report_path归档报告$ idf.py diag --zip report_path查看可用 recipes 并校验配置$ idf.py diag --list $ idf.py diag --check验证脱敏效果写入含凭据 URL 后重新生成报告配合--force覆盖检查脱敏结果是否符合预期。这套流程覆盖了收集 → 检查/补充 → 脱敏 → 归档 → 分享的全部环节可以直接作为日常故障上报的标准操作流程。常用选项速查下表汇总了idf.py diag在 diag_ext.py 中注册的全部命令行选项选项简写说明--debug-d打印调试信息包括异常回溯traceback--no-color—不输出 ANSI 颜色码--log-prefix—在日志消息开头添加严重级别字符--zip PATH-z将 PATH 指定的报告目录创建为 zip 归档--list-l显示可用 recipes 的信息--check-c校验 recipes 配置--recipe RECIPE-r指定使用的 recipe可多次指定参数为 recipe 文件路径或内置 recipe 文件名主干--tag TAG-t仅考虑包含 TAG 的 recipe可多次指定--append-a将-r指定的 recipe 与内置 recipes 组合使用--force-f目标文件或目录已存在时先删除再创建--output PATH-o指定报告目录路径或 zip 归档路径--purge PATH-p使用自定义 purge 文件移除报告中的敏感信息--port PORT—指定目标串口位于diag之前如idf.py --port /dev/ttyUSB0 diag更多细节可随时通过idf.py diag --help查看底层子命令create/list/check/zip的帮助信息也可在安装esp-idf-diag包后查阅。小结IDF Diag 把环境取证这一琐碎环节标准化、可复现化通过 recipes 灵活控制采集范围通过 purge 规则自动脱敏通过 zip 归档便捷分享全程由idf.py diag一条命令驱动。无论是提交 Issue 前自检还是协助维护者远程排查它都能提供结构清晰、脱敏安全、信息完整的项目环境快照。文档正文可参考 idf-diag.rst中文版见 idf-diag.rst该页面已收录于 工具文档目录。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ESP-IDF IDF Diag 诊断工具指南一键收集环境信息、脱敏并打包分享【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idfIDF Diag 是 ESP-IDF 官方集成在idf.py中的故障排查辅助工具用于一键收集已安装的 IDF 工具、Python 环境、项目构建产物、日志等诊断数据并生成报告目录。本文基于 docs/en/api-guides/tools/idf-diag.rst 整理并结合仓库中 diag_ext.py 的插件实现与 test_idf_diag.py 的端到端测试讲解报告目录的创建、recipes 与 purge 配置机制、敏感信息脱敏以及 zip 归档分享的完整工作流。IDF Diag 是什么当 ESP-IDF 环境或项目出现问题时排查过程往往需要先弄清机器上到底装了什么、项目是怎么构建的、日志里有什么。IDF Diag 正是为加速这一过程而生的工具它将独立的esp-idf-diagPython 包集成进 idf.py对应源码位于 diag_ext.py自动收集已安装的 IDF 工具及其版本信息Python 环境信息项目构建产物build artifacts日志及其他与问题相关的数据。所有数据被汇总到一个报告目录report directory中你可以直接查看、补充手动收集的相关文件最终压缩为 zip 归档并分享——例如作为附件提交到 GitHub Issue帮助维护者快速定位环境层面的问题。从源码结构看diag_ext.py将diag命令以 action 插件形式注册到idf.pyaction_extensions()返回的actions字典中定义了diag动作及其全部参数选项并最终调用python -m esp_idf_diag command来执行实际工作见 diag_ext.py。也就是说idf.py diag是esp-idf-diag包的薄封装命令实际包含create默认、list、check、zip四个子命令。创建报告目录使用默认配置生成诊断报告目录非常简单$ idf.py diag该命令会在当前目录下创建一个名为idf-diag-UUID的目录其中UUID是随机生成的通用唯一标识符例如idf-diag-5aaa949b-40dc-4d53-96f1-1280c801585a指定输出目录与覆盖行为通过--output简写-o选项可指定不同的输出目录路径$ idf.py diag --output my_report如果指定的输出目录已经存在命令默认不会继续执行只有加上--force简写-f选项才会删除已存在的目标文件或目录后重新创建源码中该选项说明为 Delete the target file or directory if it already exists before creating it.。在 diag_ext.py 中可以看到未指定--output时默认输出名由uuid.uuid4()生成格式正是idf-diag-{UUID}。串口端口自动检测值得留意的是执行create时若未通过--port指定目标串口IDF Diag 会给出提示并采用自动检测日志会输出类似下面的提示见 diag_ext.pyThe target serial port is not specified, so autodetection will be used. To set it manually, use the --port option. Example: idf.py --port /dev/ttyUSB0 diag.也就是说--port需写在子命令之前idf.py --port /dev/ttyUSB0 diag。Recipes诊断数据的收集配置诊断数据不是硬编码收集的而是由一组称为recipes的 YAML 配置文件驱动。每个 recipe 定义了哪些命令的输出应被纳入报告哪些文件需要被复制进报告。查看可用 recipes$ idf.py diag --list对应底层list子命令源码中简写为-l帮助信息为 Show information about available recipes.该命令会列出可用的 recipe 及其标签tags是挑选 recipe 前的第一步。你也可以用--check简写-c来校验 recipe 配置是否合法Validate recipes.。选择 recipe 与标签默认情况下所有builtin内置recipes 都会被使用。使用--recipe简写-r可指定使用的 recipe该选项可多次指定参数可以是 recipe 文件路径也可以是内置 recipe 的文件名主干file name stem。使用--tag简写-t可按标签筛选 recipe同样支持多次指定仅选择包含对应 TAG 的 recipe各 recipe 的 TAG 信息可通过-l/--list查看。--append简写-a选项用于将-r指定的 recipe 与内置 recipes组合使用而不是替换默认集合。从实现看--recipe与--tag都会被透传为esp_idf_diag的对应参数并始终携带--project-dir与--build-dir取自idf.py的项目目录与构建目录上下文确保诊断收集针对当前项目进行见 diag_ext.py。Purge敏感信息脱敏报告目录中可能包含 URL 中的密码、令牌等敏感信息。因此 IDF Diag 默认会对收集到的诊断数据进行**脱敏redaction**处理。脱敏规则由名为purge的 YAML 配置文件定义其中包含若干由正则表达式 替换字符串组成的清理规则。相关行为在测试中可以得到验证tools/test_idf_diag/test_idf_diag.py中测试向idf_component.yml写入带凭据的 URLhttps://username:passwordgithub.com/username/repository.git重新生成报告后报告内对应文件的内容变为https://[XXX]github.com/username/repository.git即密码部分被[XXX]替换完成脱敏见 test_idf_diag.py。使用自定义 purge 文件默认 purge 规则由esp-idf-diag包内置但你也可以通过--purge简写-p选项指定自定义的 purge YAML 文件从而按自己的合规要求调整脱敏规则帮助信息Use a custom purge file to remove sensitive information from the report.。分享前的必做检查请在共享报告目录之前仔细检查其中是否仍含敏感信息删除任何你不想分享的文件同时如果有未被自动收集但你认为与问题相关的文件请一并手动补充到报告目录中。这也是create命令完成后控制台日志会再次强调的建议见 diag_ext.py。创建 Zip 归档报告目录检查、补充完毕且确认无误后即可归档为 zip 文件$ idf.py diag --zip REPORT_DIRECTORY其中REPORT_DIRECTORY是之前由idf.py diag创建的报告目录。默认情况下zip 归档文件的名称与报告目录同名并追加.zip扩展名例如idf-diag-5aaa949b-40dc-4d53-96f1-1280c801585a.zip可通过--output选项为 zip 文件指定不同的文件名或路径。若目标 zip 文件已存在同样需要--force才会覆盖。归档完成后这个 zip 文件就可以分享出去了——例如作为附件附加到 GitHub Issue其中包含的项目环境关键信息能显著加速问题诊断。底层zip子命令同样支持--debug、--no-color等通用选项见 diag_ext.py。完整工作流与端到端验证结合仓库中的测试用例 test_idf_diag.py一个典型的 IDF Diag 使用闭环如下构建目标工程测试中以hello_world示例为例先fullclean再build在工程目录下生成报告目录$ idf.py diag --output report_path归档报告$ idf.py diag --zip report_path查看可用 recipes 并校验配置$ idf.py diag --list $ idf.py diag --check验证脱敏效果写入含凭据 URL 后重新生成报告配合--force覆盖检查脱敏结果是否符合预期。这套流程覆盖了收集 → 检查/补充 → 脱敏 → 归档 → 分享的全部环节可以直接作为日常故障上报的标准操作流程。常用选项速查下表汇总了idf.py diag在 diag_ext.py 中注册的全部命令行选项选项简写说明--debug-d打印调试信息包括异常回溯traceback--no-color—不输出 ANSI 颜色码--log-prefix—在日志消息开头添加严重级别字符--zip PATH-z将 PATH 指定的报告目录创建为 zip 归档--list-l显示可用 recipes 的信息--check-c校验 recipes 配置--recipe RECIPE-r指定使用的 recipe可多次指定参数为 recipe 文件路径或内置 recipe 文件名主干--tag TAG-t仅考虑包含 TAG 的 recipe可多次指定--append-a将-r指定的 recipe 与内置 recipes 组合使用--force-f目标文件或目录已存在时先删除再创建--output PATH-o指定报告目录路径或 zip 归档路径--purge PATH-p使用自定义 purge 文件移除报告中的敏感信息--port PORT—指定目标串口位于diag之前如idf.py --port /dev/ttyUSB0 diag更多细节可随时通过idf.py diag --help查看底层子命令create/list/check/zip的帮助信息也可在安装esp-idf-diag包后查阅。小结IDF Diag 把环境取证这一琐碎环节标准化、可复现化通过 recipes 灵活控制采集范围通过 purge 规则自动脱敏通过 zip 归档便捷分享全程由idf.py diag一条命令驱动。无论是提交 Issue 前自检还是协助维护者远程排查它都能提供结构清晰、脱敏安全、信息完整的项目环境快照。文档正文可参考 idf-diag.rst中文版见 idf-diag.rst该页面已收录于 工具文档目录。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
