Debug logs
Turning on Debug logs, choosing modules and detail level, and how logs are delivered.
Debug logs
Read first: Installation & requirements · What you get: Debug logs turned on for the right modules, and logs you can revisit when reporting a problem
When someone reports a problem, turn on Debug logs with this chapter first. The log is the only record you can revisit afterwards. To locate a symptom, see Common questions; for device status and error handling, see Diagnostics & errors.
Turn on Debug logs
from qnbot_sdk import DebugConfig, DebugDetail, DebugModule, Sdk
from qnbot_sdk.glove import GloveConfig
debug = DebugConfig(
modules=tuple(DebugModule),
detail=DebugDetail.SUMMARY,
sample_rate=10,
)
sdk = Sdk(devices=(GloveConfig(),), debug=debug)
glove = sdk.glove()
try:
glove.start()
glove.run_forever()
finally:
glove.close()modules: optionally selectstransport,device,capture,calibration,retargetingandoutput.detail:SUMMARYorFULL.sample_rate: an optional positive integer sample rate.
Debug logs are saved under <QNBOT_HOME>/logs in the application data directory, and each diagnostic run uses an independent session directory.
Omitting DebugConfig or setting debug to None does not create debug logs. FULL records more runtime data and increases log volume; for everyday diagnostics, SUMMARY is recommended, and use FULL when detailed troubleshooting is needed, and set sample_rate as required.
Pass the configuration through debug when creating the Sdk, then just run it through the normal flow; there is no need to start the Debug module separately.
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
DebugConfig has only three fields: modules, detail and sample_rate. When troubleshooting a particular class of problem, list only the relevant modules; the example code passes all six modules.
DebugModule
| Value | Type | Subsystems covered |
|---|---|---|
TRANSPORT | DebugModule | Serial transport (string form transport) |
DEVICE | DebugModule | Device discovery, identity and connection (device) |
CAPTURE | DebugModule | Capture flow (capture) |
CALIBRATION | DebugModule | Calibration flow (calibration) |
RETARGETING | DebugModule | Retargeting computation (retargeting) |
OUTPUT | DebugModule | Dexterous hand output channels (output) |
modules is typed Sequence[DebugModule | str]: it accepts both DebugModule enum members and their string values (for example "device"). Any other value raises ValueError and lists the supported values in the message; the default is an empty sequence.
DebugDetail
| Value | Type | Meaning |
|---|---|---|
SUMMARY | DebugDetail | Key events and results; the default, with a small log volume |
FULL | DebugDetail | Records more runtime data on top of SUMMARY, with a noticeably larger log volume |
detail is typed DebugDetail and only accepts enum members: DebugDetail.FULL works, while the string "full" raises TypeError.
sample_rate
Type int | None, defaulting to None (ordinary events are not sampled). When set, it must be an integer between 1 and 4294967295 (bool is not accepted), used to sample at that frequency under FULL and to control the log volume.
For complete fields and constraints, see DebugConfig in the configuration reference.