69 lines
2.4 KiB
Markdown
69 lines
2.4 KiB
Markdown
# Logging standard
|
|
|
|
Lumi uses the structured logger in `src/services/logger.js` for operational
|
|
events. It stores searchable entries for the admin UI, attaches request context,
|
|
redacts common credential fields, and publishes live admin updates.
|
|
|
|
## Operational logging
|
|
|
|
Core services create a named logger:
|
|
|
|
```js
|
|
const { createLogger } = require("./logger");
|
|
const logger = createLogger("updater");
|
|
|
|
logger.info("Update check completed", { version }, {
|
|
category: "updates",
|
|
event: "update_check_completed"
|
|
});
|
|
```
|
|
|
|
Plugins receive a plugin-scoped `logger` in their `init()` dependencies. Use
|
|
that injected logger when practical. A plugin module that must log outside
|
|
`init()` may create a logger named `plugin:<plugin-id>`.
|
|
|
|
Use:
|
|
|
|
- `debug` for detailed, low-value troubleshooting information.
|
|
- `info` for meaningful lifecycle and administrative actions.
|
|
- `warn` for degraded behavior that Lumi can continue through.
|
|
- `error` for a failed operation that may require attention.
|
|
|
|
Pass an `Error` as the details argument when one is available. The logger
|
|
preserves its stack trace while applying credential redaction:
|
|
|
|
```js
|
|
logger.error("Plugin refresh failed", error, {
|
|
event: "plugin_refresh_failed"
|
|
});
|
|
```
|
|
|
|
Do not include passwords, tokens, cookies, pairing secrets, authorization
|
|
headers, or full request bodies in messages or metadata. Redaction is a safety
|
|
net, not a reason to collect secrets.
|
|
|
|
## Metrics and high-frequency events
|
|
|
|
Do not write high-frequency counters or per-frame events to the operational log.
|
|
There is no global metrics API.
|
|
|
|
A feature may retain its own bounded metrics only when it also owns the storage,
|
|
retention, and inspection UI. Lumi AI is one example:
|
|
`plugins/lumi_ai/backend/metrics.js` aggregates AI timings and retains bounded
|
|
work history. Operational failures in such a feature still belong in the core
|
|
logger.
|
|
|
|
## Console output
|
|
|
|
Direct `console.*` calls are captured after `hookConsole()` starts, but they lose
|
|
the useful source and event metadata of a named logger. Prefer a named logger in
|
|
runtime code. Console output remains reasonable in standalone verification and
|
|
build scripts where the terminal is the intended consumer.
|
|
|
|
## Retention and context
|
|
|
|
Operational logs default to 30 days and at most 100,000 entries. Request
|
|
correlation is inherited through `withLogContext()` and logger `run()` scopes.
|
|
The logger redacts common sensitive keys and credential-looking text before an
|
|
entry is stored or published.
|