docs: clarify imported nwlog simple backend layout
This commit is contained in:
61
REDESIGN.md
61
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
|
||||
|
||||
Reference in New Issue
Block a user