docs: clarify imported nwlog simple backend layout

This commit is contained in:
Mario Fetka
2026-06-02 09:00:29 +00:00
parent 4138b3cad8
commit e9d6ad9fe0

View File

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