Home > @opengovsg/logging > Logger
Logger interface
Structured logger with action scoping, contextual metadata, and severity levels aligned to RFC 5424 (syslog).
## Choosing a level (the discriminator is *does someone need to act?*)
- debug — verbose diagnostics, only while actively debugging. - info — the routine activity trail; no action implied. - notice — significant or **auditable** business events. - warn — something off but handled; no action needed now. - error — an operation failed; a human should investigate.
Signature:
export interface LoggerProperties
| Property | Modifiers | Type | Description |
|---|---|---|---|
| audit | readonly | AuditLogger | The fixed-shape **audit** helpers — audit.<category>.<event>(…) — for recording compliance-auditable events with a type-enforced shape. Server side only; absent from BasicLogger. See AuditLogger. |
Methods
| Method | Description |
|---|---|
| debug(input) | Verbose diagnostic detail useful only while actively debugging (e.g. branch traces, intermediate values). Typically disabled in production. No one is expected to act on it. |
| error(input) | An operation failed and a human likely needs to investigate (potentially page-worthy). Carries the error that caused the failure. |
| info(input) | Routine, expected business events that form the normal activity trail (e.g. a request handled, a record read). Useful for reconstructing what happened; no action implied. This is the default level — reach for notice when an event is auditable, or warn/error when something is off. |
| notice(input) | Significant or **auditable** business events that are normal but worth recording for later reconstruction — e.g. ownership transfer, mutating a critical resource, a permission change, an authentication. Not an error: notice carries no error field. |
| scope(options) | Return a **new** logger whose action is set to Unlike |
| setAction(options) | Append ⚠️ Mutation is shared: if this logger is reused across concurrent requests (e.g. a module-level singleton), the scope bleeds between them. Prefer Logger.scope() for request-scoped work. |
| setBindings(bindings) | Bind the acting user at the **root level** ( ⚠️ Mutation is shared: see the caveat on Logger.setAction(). Here the stakes are higher - if a logger is reused across requests (e.g. a module-level singleton), a bound |
| setContext(options) | Merge ⚠️ Mutation is shared: see the caveat on Logger.setAction(). Prefer Logger.withContext() when you need an isolated logger. |
| warn(input) | Something is off but was handled or recovered and needs no immediate action (e.g. a retry, a fallback path taken, a deprecated route hit). May carry an error for context. |
| withBindings(bindings) | Return a **new** logger that binds the acting user at the **root level** (user_id), leaving the original unchanged. Unlike Logger.withContext() (which lands in context), user_id is a top-level field and so satisfies the audit scope-read asserts - e.g. binding the acting user once it is known mid-request (self-signup, deferred auth), so audit.resource.* and other actor-scoped events attribute the actor instead of warning. Request-fixed facets (client_ip, user_agent, path) are set at creation and inherited untouched. |
| withContext(options) | Return a **new** logger with context merged into the existing one, leaving the original logger unchanged. |