diff --git a/REDESIGN.md b/REDESIGN.md index adceb08..e960027 100644 --- a/REDESIGN.md +++ b/REDESIGN.md @@ -1437,9 +1437,10 @@ The project-level layout should follow the existing include/source split: ```text include/nwlog.h public internal logging facade used by mars-nwe modules -src/nwlog.c facade implementation, redaction, common formatting -src/nwlog_zlog.c optional zlog backend, if enabled at build time -src/nwlog_syslog.c or built-in backend code for simple builds +src/nwlog.c facade implementation, redaction, common formatting +src/nwlog_simple.c simple stderr/stdout/file/callback backend +src/nwlog_syslog.c optional syslog(3)-style backend derived from simple +src/nwlog_zlog.c optional zlog backend, if enabled at build time ``` Protocol handlers, providers, `nwconn`, `nwserv`, `nwbind`, future `nwqueue`, @@ -1450,7 +1451,7 @@ That facade can initially keep using the existing mars-nwe logging functions, `stderr`, or a small vendored backend. Later it may grow simple and advanced backends behind the same API. -There are two useful backend classes: +There are three 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 @@ -1459,8 +1460,14 @@ There are two useful backend classes: 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. + context/correlation fields, optional file output, and journald-friendly + stderr/stdout formatting should live behind `nwlog`, not in endpoint code. + + This backend is the right default for systemd deployments: services can log to + stderr/stdout and let journald capture, timestamp, rotate, and forward logs + according to the unit configuration. mars-nwe should still emit structured, + grep-friendly lines so `journalctl -u ...` remains useful without requiring a + heavier routing backend. The project layout should make the imported code clearly internal, for example: @@ -1470,14 +1477,27 @@ There are two useful backend classes: 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 + 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. **Syslog bridge backend.** If classic syslog integration is wanted, do not + overload the simple backend with syslog-specific behavior. Instead clone the + adapted simple backend structure into a separate implementation: + + ```text + include/nwlog_syslog.h internal syslog backend declarations, if needed + src/nwlog_syslog.c syslog(3)-style backend derived from simple + ``` + + `nwlog_syslog.c` may reuse the same level/category mapping, redaction hooks, + event formatting helpers, and callback shape as `nwlog_simple.c`, but its + output path should be explicit: `openlog()`, `syslog()`, and `closelog()` or + the platform equivalent. This keeps `backend = simple` predictable for + stderr/stdout/file/journald use, while `backend = syslog` clearly means the + traditional syslog path. Provider and endpoint code must not care which of + the two is active. +3. **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`, @@ -1497,8 +1517,10 @@ The preferred dependency shape is therefore: ```text mars-nwe code -> nwlog facade - -> 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 + -> simple backend: src/nwlog_simple.c from imported/adapted rxi/log.c-style code + -> stderr/stdout for systemd/journald, optional local file/callback + -> syslog backend: src/nwlog_syslog.c derived from the simple backend shape + -> classic syslog(3) output when explicitly configured -> optional advanced backend: src/nwlog_zlog.c using zlog -> admin-configured zlog rules/formats/outputs ``` @@ -1524,7 +1546,7 @@ to edit C-style backend internals directly: ```ini [logging] -backend = zlog ; builtin, simple, syslog, file, zlog +backend = simple ; simple, syslog, zlog level = info redact_secrets = yes config = /etc/mars-nwe/zlog.conf