| |
|---|
| Version | 0.1.0 |
| Purity | browser-safe |
| Purpose | A configured pino instance (createLogger(module) for child loggers) with redaction wired into every log record, plus the display/log-layer credential redactor (redactObject / redactValue / redactJsonString) the Express server re-applies to API responses. |
| Workspace deps | none |
| External deps | pino, pino-pretty |
@clawboo/* package, so the redactor can live here and be shared by both this package’s pino instance and the Express server without a dependency inversion. It is server-oriented but reaches the browser bundle transitively (@clawboo/gateway-client imports it). The single browser hazard, reading process.env at module-eval time, is guarded behind a typeof process check, and pino ships its own browser shim, so the import is browser-safe. The redactor here is the display / log boundary twin of @clawboo/db’s storage-layer scrubSecrets: different boundary, different mask (•••• vs [REDACTED]), composed as defense in depth.
Public API
Functions
| Export | Signature | Contract |
|---|
createLogger | (module: string) => Logger | Returns a pino child logger tagged with { module }. The standard entry point; every server module gets its own named child. |
redactObject | <T>(obj: T): T | Deep-clones obj, masking credential-looking KEYS and credential-shaped string VALUES with ••••. Circular-safe (WeakSet guard → [Circular]). Applied inside the pino formatters.log hook and at every server API site that exposes event payloads / audit entries / trace spans. |
redactValue | (value: unknown, key?: string): unknown | Redacts a single value. When key is supplied and reads as a credential key, the whole value is masked; otherwise strings are scanned for credential-shaped substrings. Numbers / booleans / null pass through unchanged so numeric telemetry survives. |
redactJsonString | <T extends string | null | undefined>(s: T): T | Parses a JSON string field (obs event data, audit summary, tool argsSummary/resultSummary), masks credential keys + values, re-stringifies. Falls back to a value-only scan when the field is not JSON; passes through null / empty. |
Types & interfaces
| Export | Kind | Contract |
|---|
Logger | type | ReturnType<typeof logger.child>, the pino child-logger type, used by consumers (e.g. @clawboo/events’ EventHandlerDeps.log) to type an injectable logger. |
Constants
| Export | Type | Contract |
|---|
logger | pino.Logger | The root logger. name: 'clawboo', level from LOG_LEVEL (default info), formatters.log runs every record through redactObject. Uses the pino-pretty transport unless NODE_ENV === 'production'. |
REDACTION_MASK | string | The bullet mask ('••••') substituted for a redacted value at the display / log boundary. |
The package exposes no classes. logger is a configured pino instance, createLogger is a factory, and the redactor is plain functions. LOG_LEVEL is read from the environment at module load (default info) but is not itself an export.
redact* is the display/log layer and masks with ••••. It is distinct from @clawboo/db’s storage-layer scrubSecrets (masks with [REDACTED] before anything is persisted). They run at different boundaries and compose; already-scrubbed data passes through here harmlessly. Numeric token counts and cost survive both layers (a SAFE_COUNT_KEYS allowlist exempts tokens / inputtokens / tokencount / etc.).
Used by
packages/gateway-client/src/{client,device-auth}.ts, createLogger for the WS client + Node device-auth (the transitive path that pulls the logger into the browser bundle).apps/web/server/index.ts, createLogger for the Express server’s request logging.apps/web/server/lib/redact.ts, re-exports redactObject / redactValue / redactJsonString / REDACTION_MASK as the server’s documented apply-site import; consumed by api/obs.ts, api/tools.ts, api/governanceAudit.ts, api/health.ts, and lib/teamChat/leaderState.ts.apps/web/server/lib/obs/logger.ts, lib/runtimes/native/conversation.ts, lib/teamChat/runTeamExchange.ts, createLogger for module-scoped logging.packages/events/src/types.ts, imports the Logger type for EventHandlerDeps.log.
Source
Barrel: packages/logger/src/index.ts. The redactor lives in redact.ts (re-exported through the barrel). The package.json exports map declares only the root . entry, no subpath barrels.
See also
