docs: clarify simple and syslog nwlog backends

This commit is contained in:
Mario Fetka
2026-06-02 09:06:44 +00:00
parent e9d6ad9fe0
commit 626e4f5568

View File

@@ -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