public/kaptan
1
Fork 0
Code Issues 24 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(diagnostics): split error and shutdown messages

Browse Source
This commit is contained in:
Onur Özkan committed 2026-08-09 22:20:59 +03:00
1 parent 9646451645
commit afafd126d7
25 files changed
+608 -225
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/src/logs.md
+22 -15
View File
@@ -18,28 +18,35 @@ messages later.
## Receiver contract
`definitions/kaptan/log.xml` separates ordinary logs from errors:
`definitions/kaptan/log.xml`, `definitions/kaptan/error.xml`, and
`definitions/kaptan/shutdown.xml` separate ordinary logs, errors, and
orderly-shutdown observations:
```text
KAPTAN_LOG { level, flags, message_length, message[160] }
KAPTAN_ERROR { flags, message_length, message[160] }
KAPTAN_ERROR {
flags, path_length, additional_information_length,
path[96], additional_information[64]
}
KAPTAN_SHUTDOWN { reason }
```
A receiver generated from the same `kaptan.xml` revision validates
`message_length <= 160` and decodes exactly that UTF-8 prefix. `KAPTAN_LOG`
displays its text at the MAVLink severity in `level`; `TRACE` is encoded as
`DEBUG` plus the `TRACE` flag. `KAPTAN_ERROR` is error-only and accepts only
`TRUNCATED` and `COALESCED`; a `TRACE` bit is never emitted there. Unknown
future flag bits must be ignored.
A GCS decoder generated from the same `kaptan.xml` revision must validate
`message_length <= 160` for `KAPTAN_LOG`, and `path_length <= 96` plus
`additional_information_length <= 64` for `KAPTAN_ERROR`, before slicing the
fixed arrays into UTF-8 prefixes. Generated MAVLink framing alone does not
enforce these semantic length fields. `KAPTAN_LOG` displays its text at the
MAVLink severity in `level`; `TRACE` is encoded as `DEBUG` plus the `TRACE`
flag.
`KAPTAN_ERROR` is error-only and accepts only `TRUNCATED` and `COALESCED`; a
`TRACE` bit is never emitted there. Unknown future flag bits must be ignored.
The derived error display text is intentionally not a numeric error catalog;
renaming its Rust module/type/variant changes the display identity. Error
details requiring machine action stay in their owning protocol, notably
`KAPTAN_CONFIG_RESULT`. `KAPTAN_SHUTDOWN` has only its typed reason and is
valid only after an orderly output-inhibited completion. Delivery is bounded
and lossy under link pressure; heartbeat and safety telemetry use separate
paths.
The derived error path is intentionally not a numeric error catalog; renaming
its Rust module/type/variant changes that identity. Error details requiring
machine action stay in their owning protocol, notably `KAPTAN_CONFIG_RESULT`.
`KAPTAN_SHUTDOWN` has only its typed reason and is valid only after an orderly
output-inhibited completion. Delivery is bounded and lossy under link pressure;
heartbeat and safety telemetry use separate paths.
## Filtering