Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

docs: define structured logging standard

Alfredo Lopezf5107d2e9ce2
diff --git a/AGENTS.md b/AGENTS.md
index b01ca1dd1..90072669c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -93,3 +93,42 @@ Labs reference. Use repository-standard conventional prefixes instead:
`ci/*`, `build/*`, `perf/*`, or `revert/*`, choosing the one that describes
the change. This rule applies to new branches; it does not retroactively
rewrite branches that already exist outside the task's scope.
+
+## Logging standard
+
+Use structured service logging for production Node.js/runtime code. Pino is
+the repository reference implementation: `control-api` already exposes a
+redacting root Pino logger and `workspace-files-controller` uses Pino with
+`pino-http`. The repository does not use Winston. Other services currently
+have local structured adapters (for example, `mcp-host`, HCC, workflow
+recipes, and the workflow approval reader); those adapters remain the local
+boundary until a separately scoped service migration is approved.
+
+The choice is about the logging contract, not a blanket dependency migration:
+structured JSON, explicit levels, contextual fields/child loggers,
+`LOG_LEVEL` filtering, and secret-safe redaction. Direct `console.*` calls in
+production code bypass those guarantees; in `control-api` they also bypass
+Pino's redaction list. Winston or a new ad-hoc logger must not be introduced
+to solve a one-file cleanup.
+
+When modifying an individual file:
+
+- In production Node.js code, use the existing logger or structured adapter
+ for that service. Do not bypass it with `console.log`, `console.info`,
+ `console.warn`, `console.error`, `console.debug`, or `console.trace`.
+- Map levels consistently: `log`/`info` → `info`, `warn` → `warn`,
+ `error` → `error`, and `debug`/`trace` → the adapter's debug/trace level.
+ Pass fields as structured data; pass errors as an error field (for Pino,
+ `{ err }`) rather than interpolating them into a string.
+- Preserve the service's redaction, correlation, and JSON-output behavior.
+ Never log tokens, credentials, authorization headers, DSNs, private URLs,
+ cookies, keys, or raw request/response bodies.
+- Scope the cleanup to the file already being changed and the minimum import
+ or adapter support it needs. Do not sweep neighboring files, start a
+ repository-wide migration, or add a second logging convention as collateral
+ work.
+- Direct `console.*`/`process.stdout` is allowed only inside a logger adapter,
+ an explicit CLI/bootstrap path that runs before a logger exists, tests,
+ E2E/fixtures, or intentional development-only diagnostics. Do not import a
+ server logger into browser/renderer bundles; use their existing client
+ logging boundary.
diff --git a/CLAUDE.md b/CLAUDE.md
index e23a2c362..a7d52c1f4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -11,3 +11,20 @@ Labs reference. Use the repository's conventional prefixes instead: `feat/*`,
The local Minikube T0/T1/T2 contract is development-only. Follow the
canonical `make minikube-t2-preflight` and `make minikube-t2` entry points and
the ownership, secret-safety, and evidence rules in `AGENTS.md`.
+
+## Logging standard
+
+For production Node.js/runtime code, use structured logging. Pino is the
+repository reference implementation because `control-api` uses a redacting
+root logger and `workspace-files-controller` uses Pino/Pino HTTP; Winston is
+not a repository dependency. Services with an existing structured wrapper
+(`mcp-host`, HCC, workflow recipes, and the workflow approval reader) should
+continue using that wrapper rather than bypassing it.
+
+When editing a file, replace its direct `console.*` calls with the existing
+service logger, preserve levels/context/redaction, and keep the change scoped
+to that file plus minimal support. Do not start a repository-wide logging
+migration or add a second logger convention. Direct console output is reserved
+for logger adapters, explicit CLI/bootstrap output, tests, E2E/fixtures, and
+intentional development diagnostics; never emit secrets, tokens, credentials,
+DSNs, private URLs, or raw request/response bodies.