From e9d6ad9fe02abe302ef35e07dbc00905c5aae63d Mon Sep 17 00:00:00 2001 From: Mario Fetka Date: Tue, 2 Jun 2026 09:00:29 +0000 Subject: [PATCH] docs: clarify imported nwlog simple backend layout --- REDESIGN.md | 61 +++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 47 insertions(+), 14 deletions(-) diff --git a/REDESIGN.md b/REDESIGN.md index c09e4f0..adceb08 100644 --- a/REDESIGN.md +++ b/REDESIGN.md @@ -1447,26 +1447,59 @@ Protocol handlers, providers, `nwconn`, `nwserv`, `nwbind`, future `nwqueue`, not include zlog headers or call zlog macros directly. That facade can initially keep using the existing mars-nwe logging functions, -`stderr`, or `syslog`. Later it may use an advanced backend. +`stderr`, or a small vendored backend. Later it may grow simple and advanced +backends behind the same API. -`zlog` is a good candidate for that advanced backend because it is a C logging -library with category, format, and rule based configuration. That model fits -mars-nwe well: code can emit category-specific events such as `ncp`, `handoff`, -`queue`, `directory`, `auth`, or `transport`, while the administrator decides in -the logging configuration whether those categories go to a file, stdout/stderr, -syslog-style output, a pipe, or an external log-forwarder path. The zlog -project documentation describes these three core concepts as categories, formats, -and rules, where rules bind a category/level to an output and format. Before -choosing it, packaging, license compatibility, portability, and maintenance state -still need to be verified for the target distributions. +There are two useful backend classes: + +1. **Simple built-in backend.** A tiny C backend derived from `rxi/log.c` can be + imported into the source tree for simple builds. It should be treated as + vendored implementation code, renamed and namespaced for mars-nwe. The base + upstream code only provides local-style logging primitives such as stderr, + file output, and callback hooks; it is not an out-of-the-box syslog, GELF, or + remote routing solution. That is fine for the built-in backend, but mars-nwe + must adapt it for the project requirements: redaction hooks, category mapping, + context/correlation fields, optional file output, and any future syslog-like + bridge should live behind `nwlog`, not in endpoint code. + + The project layout should make the imported code clearly internal, for + example: + + ```text + include/nwlog_simple.h internal/simple backend declarations, if needed + src/nwlog_simple.c imported/adapted rxi/log.c-style backend + ``` + + If the backend later grows real syslog support, that can either stay in the + simple backend or split into `src/nwlog_syslog.c`. Until then, avoid naming + the vendored `rxi/log.c` adaptation as if it already were a full syslog + backend. Imported symbols such as `log_info`, `log_error`, or `log_add_fp` + must be renamed, hidden, or made `static` so they do not leak into the global + mars-nwe namespace. Public entry points should look like + `nwlog_simple_init()` and `nwlog_simple_emit()`. +2. **Advanced routing backend.** `zlog` remains the preferred candidate for + administrator-controlled routing because it is a C logging library with + category, format, and rule based configuration. That model fits mars-nwe + well: code can emit category-specific events such as `ncp`, `handoff`, + `queue`, `directory`, `auth`, or `transport`, while the administrator decides + in the logging configuration whether those categories go to a file, + stdout/stderr, syslog-style output, a pipe, or an external log-forwarder path. + The zlog project documentation describes these three core concepts as + categories, formats, and rules, where rules bind a category/level to an output + and format. + +Before choosing any backend, packaging, license compatibility, portability, and +maintenance state still need to be verified for the target distributions. The +architecture must not depend on one backend being available. The preferred dependency shape is therefore: ```text mars-nwe code -> nwlog facade - -> simple built-in backend: stderr/file/syslog - -> optional advanced backend: zlog + -> builtin/simple backend: src/nwlog_simple.c from imported/adapted rxi/log.c-style code + -> optional syslog bridge: src/nwlog_syslog.c, if implemented later + -> optional advanced backend: src/nwlog_zlog.c using zlog -> admin-configured zlog rules/formats/outputs ``` @@ -1491,7 +1524,7 @@ to edit C-style backend internals directly: ```ini [logging] -backend = zlog ; builtin, syslog, file, zlog +backend = zlog ; builtin, simple, syslog, file, zlog level = info redact_secrets = yes config = /etc/mars-nwe/zlog.conf