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));
``` Logs are written under `<QNBOT_HOME>/logs` in the
[application data directory](./configuration-reference#application-data-directory). Each SDK
instance with Debug enabled uses its own session directory, which makes it easy to collect and
share diagnostic information for one run.

`DebugDetail::summary` suits ordinary troubleshooting; `DebugDetail::full` records more data,
produces larger files, and may also contain device identifiers, paths, poses, and output. In
production, prefer `summary`, set `sample_rate` according to the data volume, and check and
handle sensitive content before sharing logs.

A Debug write failure does not stop the device data stream. Applications should judge the run
result from SDK return values, exceptions, and health status, and must not treat whether a log
file was generated as a business success condition.

After reproducing the problem, provide the session directory of that run together with the terminal output to our technical support; the logs already contain the device and runtime state, which makes the report easy to follow up.

## Modules and detail levels

`qnbot::DebugConfig` has only three fields: `modules`, `detail` and `sample_rate`. When troubleshooting a particular class of problem, list only the relevant modules; the configuration example passes all six modules.

### `DebugModule`

| Value | Type | Subsystems covered |
| --- | --- | --- |
| `qnbot::DebugModule::transport` | `DebugModule` | Serial transport |
| `qnbot::DebugModule::device` | `DebugModule` | Device discovery, identity and connection |
| `qnbot::DebugModule::capture` | `DebugModule` | Capture flow |
| `qnbot::DebugModule::calibration` | `DebugModule` | Calibration flow |
| `qnbot::DebugModule::retargeting` | `DebugModule` | Retargeting computation |
| `qnbot::DebugModule::output` | `DebugModule` | Dexterous hand output channels |

`modules` is typed `std::vector<DebugModule>`: it accepts only enum values and defaults to an empty vector.

### `DebugDetail`

| Value | Type | Meaning |
| --- | --- | --- |
| `qnbot::DebugDetail::summary` | `DebugDetail` | Key events and results; the default, with a small log volume |
| `qnbot::DebugDetail::full` | `DebugDetail` | Records more runtime data on top of `summary`, with a noticeably larger log volume |

`detail` is typed `DebugDetail` and only accepts these two enum values.

### `sample_rate`

Type `std::optional<std::uint32_t>`, empty by default (ordinary events are not sampled). When set, it must be a positive integer, used to sample at that frequency under `full` to control the log volume.

For complete fields and constraints, see [`DebugConfig` in the configuration reference](./configuration-reference#debugconfig).