From c0da2e440b10e692bd46eaa815da7272eda1c8d4 Mon Sep 17 00:00:00 2001 From: OpenAI Date: Sat, 13 Jun 2026 05:26:48 +0000 Subject: [PATCH] 0448 docs: define normalized logging config format --- AI.md | 2 +- REDESIGN.md | 60 ++++++++++++++++++++++++++++++++++++++++++ TODO.md | 4 +++ doc/LOG_LEVEL_AUDIT.md | 26 +++++++++++++++--- include/nwlog.h | 4 ++- 5 files changed, 90 insertions(+), 6 deletions(-) diff --git a/AI.md b/AI.md index 8706336..dd0e0e1 100644 --- a/AI.md +++ b/AI.md @@ -68,7 +68,7 @@ Before namespace code changes, keep the legacy logging audit in mind: old MARS accepts numeric debug thresholds from `0` to `99`, but the actual source mostly uses `1..5`. The future `nwlog` facade should give those normal levels clear semantic names instead of preserving the old overloaded buckets: `1=error`, -`2=warn`, `3=info`, `4=debug` and `5=trace`. `debug` is local diagnostic detail; `trace` is packet/message/handoff path following across process or provider boundaries. Useful legacy `6..99` traces should +`2=warn`, `3=info`, `4=debug` and `5=trace`. `debug` is local diagnostic detail; `trace` is packet/message/handoff path following across process or provider boundaries. New config should treat the numbers and words as synonyms and use one global `[logging] level` plus optional `[logging.process.] level` overrides; the old numeric `100..106` process entries stay accepted for compatibility. Useful legacy `6..99` traces should map to `nwlog_detail()` later. `nwlog_detail()` is not part of the normal `1..5` threshold ladder: normal builds return `0`, while `MAINTAINER_BUILD` builds may emit detail whenever such a call site is reached. No INI option may diff --git a/REDESIGN.md b/REDESIGN.md index 6f042ed..89e5448 100644 --- a/REDESIGN.md +++ b/REDESIGN.md @@ -3538,6 +3538,66 @@ connection, process, provider or transport boundaries. Trace is not a synonym for raw sensitive dumps; those belong to `nwlog_detail()` when they are still useful. +The normalized configuration should use one global default plus optional +process-level overrides. The old numeric entries `100` through `106` remain +accepted for compatibility, but new documentation and tools should prefer the +semantic form: + +```ini +[logging] +level = info ; off|0, error|1, warn|2, info|3, debug|4, trace|5 +backend = simple ; simple|syslog|zlog later; facade API unchanged + +[logging.process.nwserv] +level = info + +[logging.process.ncpserv] +level = info + +[logging.process.nwconn] +level = trace + +[logging.process.nwbind] +level = debug + +[logging.process.nwrouted] +level = warn +``` + +The `level` value parser should treat the names and numbers as exact synonyms: +`0/off/none`, `1/error`, `2/warn/warning`, `3/info`, `4/debug`, and +`5/trace`. Setting a process to `trace` means that process emits `error`, +`warn`, `info`, `debug`, and `trace` events. A process override replaces only +that process threshold; missing process entries inherit `[logging] level`. The +first implementation should not require per-category thresholds. Categories +are still recorded on every event for routing, filtering, and later zlog +configuration, but the stable configuration contract is global plus process +overrides first. + +Maintainer detail is deliberately not a config value. There is no +`level = detail`, no `maintainer_detail = true`, and no production INI switch +that enables `nwlog_detail()`. In normal builds detail call sites are no-ops. +In `MAINTAINER_BUILD`, detail output is controlled by the compile-time build +choice, while the ordinary `0..5` threshold still controls the surrounding +normal log context. + +Legacy numeric sections map into the same model during migration: + +| Legacy entry | Normalized process override | +| --- | --- | +| `100` | IPX setup / future `ipx` process or transport helper | +| `101` | `nwserv` | +| `102` | `ncpserv` | +| `103` | `nwconn` | +| `104` | `nwclient` | +| `105` | `nwbind` | +| `106` | `nwrouted` | + +Values `0..5` in legacy entries are interpreted with the same threshold +semantics as the new names. Values above `5` may still be accepted by legacy +`XDPRINTF` code while the tree is being migrated, but new `nwlog` callers should +not expose `6..99` as administrator-visible levels. + Conceptual call sites should be short and category-specific, not manual construction of large event structures in every handler: diff --git a/TODO.md b/TODO.md index eeafb7d..856fd7d 100644 --- a/TODO.md +++ b/TODO.md @@ -297,6 +297,10 @@ Concrete follow-up for the future facade: - add the normal `nwlog_error()` / `nwlog_warn()` / `nwlog_info()` / `nwlog_debug()` / `nwlog_trace()` facade wrappers around the semantic `1..5` vocabulary; +- define the config parser so `0..5` and `off/error/warn/info/debug/trace` are + synonyms, with one global `[logging] level` plus optional + `[logging.process.] level` overrides while legacy `100..106` entries + remain accepted; - add `nwlog_detail()` as the only maintainer-build-only target for useful legacy `6..99` call sites; - make normal builds return `0`/no-op from `nwlog_detail()`; diff --git a/doc/LOG_LEVEL_AUDIT.md b/doc/LOG_LEVEL_AUDIT.md index 5b5369a..465cd5a 100644 --- a/doc/LOG_LEVEL_AUDIT.md +++ b/doc/LOG_LEVEL_AUDIT.md @@ -171,13 +171,31 @@ A practical first mapping for the future facade is: | `nwlog_trace()` | `5` | packet/message/handoff trace | | `nwlog_detail()` | `6` internally | maintainer-only unsafe detail; emitted only in `MAINTAINER_BUILD`, independent of the normal `1..5` runtime threshold | +The future config parser should accept both the number and the semantic word as +the same threshold value: + +| Accepted config values | Effective threshold | Meaning | +| --- | ---: | --- | +| `0`, `off`, `none` | `0` | no normal log output | +| `1`, `error` | `1` | errors only | +| `2`, `warn`, `warning` | `2` | errors and warnings | +| `3`, `info` | `3` | errors, warnings and informational events | +| `4`, `debug` | `4` | plus local debug diagnostics | +| `5`, `trace` | `5` | plus packet/message/handoff path tracing | + +A process configured as `trace` therefore also emits `error`, `warn`, `info` +and `debug`. `detail` is not an accepted administrator config value. Legacy +entries `100..106` continue to provide per-process thresholds, while the +normalized form should use `[logging] level` plus `[logging.process.] +level` overrides. + Legacy thresholds remain accepted during migration, but old numbers must be reviewed by message content before conversion. In particular, legacy `XDPRINTF(1, ...)` may become error, warning or info, and legacy `XDPRINTF(2..5, -...)` may become debug or trace depending on whether they describe local diagnostics or cross-boundary flow. The facade -should provide semantic wrappers for new code, keep the old threshold behaviour -available during migration, and review sensitive call sites before they are -converted. +...)` may become debug or trace depending on whether they describe local +diagnostics or cross-boundary flow. The facade should provide semantic wrappers +for new code, keep the old threshold behaviour available during migration, and +review sensitive call sites before they are converted. ## Maintainer-detail rule for legacy high levels diff --git a/include/nwlog.h b/include/nwlog.h index 2c3673a..67b0d38 100644 --- a/include/nwlog.h +++ b/include/nwlog.h @@ -6,7 +6,9 @@ * * This header is intentionally declarative for now. It records the new * semantic 1..5 level split that future nwlog_* wrappers should use while the - * legacy XDPRINTF threshold migration is still ongoing. + * legacy XDPRINTF threshold migration is still ongoing. Future configuration + * parsers should treat the numbers and names as synonyms: off/0, error/1, + * warn/2, info/3, debug/4 and trace/5. */ typedef enum nwlog_level_e {