Debug 日志 | Qnbot Docs Center

先读：安装与环境要求 · 读完你能：开对模块的 Debug 日志，并在报告问题时交出可复查的日志

现场报告问题时，先按这一章打开 Debug 日志。日志是事后唯一能复查的数据。按症状定位问题见常见问题；设备状态与错误处理见诊断与错误。

打开 Debug 日志

创建 Sdk 时提供 DebugConfig 即可启用日志；省略时默认关闭。常见做法是先把配置写进 qnbot::SdkConfig，再创建 Sdk：

qnbot::DebugConfig debug_config{
    {qnbot::DebugModule::transport, qnbot::DebugModule::device,
     qnbot::DebugModule::capture, qnbot::DebugModule::calibration,
     qnbot::DebugModule::retargeting, qnbot::DebugModule::output},
    qnbot::DebugDetail::summary,
    10,
};

qnbot::SdkConfig config;
config.debug = debug_config;
qnbot::Sdk sdk(std::move(config));

日志位置见应用数据目录的 <QNBOT_HOME>/logs 下。每个启用 Debug 的 SDK 实例使用独立的 session 目录，便于按一次运行收集和分享诊断信息。

DebugDetail::summary 适合普通问题排查；DebugDetail::full 会记录更多数据，文件更大，也可能包含设备标识、路径、姿态和输出。生产环境建议优先使用 summary，根据数据量设置 sample_rate，并在分享日志前检查和处理敏感内容。

Debug 写入失败不会中止设备数据流。应用应根据 SDK 返回值、异常和健康状态判断运行结果，不要把日志文件是否生成作为业务成功条件。

复现问题后，把这次运行对应的 session 目录连同终端输出一起提供给我们的技术支持；日志里已经包含设备与运行状态，便于对照问题。

模块与详细程度

qnbot::DebugConfig 只有三个字段：modules、detail 和 sample_rate。排查某一类问题时只列相关模块即可；配置示例里传入全部六个模块。

`DebugModule`

值	类型	覆盖的子系统
`qnbot::DebugModule::transport`	`DebugModule`	串口传输
`qnbot::DebugModule::device`	`DebugModule`	设备发现、身份与连接
`qnbot::DebugModule::capture`	`DebugModule`	采集流程
`qnbot::DebugModule::calibration`	`DebugModule`	标定流程
`qnbot::DebugModule::retargeting`	`DebugModule`	retargeting 计算
`qnbot::DebugModule::output`	`DebugModule`	灵巧手输出通道

modules 的类型是 std::vector<DebugModule>：只接受枚举值，默认是空 vector。

`DebugDetail`

值	类型	含义
`qnbot::DebugDetail::summary`	`DebugDetail`	关键事件与结果；默认值，日志量小
`qnbot::DebugDetail::full`	`DebugDetail`	在 `summary` 基础上记录更多运行数据，日志量明显更大

detail 的类型是 DebugDetail，只接受这两个枚举值。

`sample_rate`

类型 std::optional<std::uint32_t>，默认空（普通事件不采样）。设置后必须为正整数，用于在 full 下按该频率抽样、控制日志量。

完整字段与约束见配置字段速查的 DebugConfig。