Skip to content

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:

typescript
export interface Logger

Properties ​

PropertyModifiersTypeDescription
auditreadonlyAuditLoggerThe 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 ​

MethodDescription
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 action (the most-specific "leaf"; a per-call action still wins over it). The new logger inherits this logger's context, **merged** with any additional context provided here. Does not mutate the parent.

Unlike pino.child, scope **merges** context (child *replaces* it), which is why it is scope, not child. The pino child is createBaseLogger.

setAction(options)

Append action to this logger's action path **in place** (mutates).

⚠️ 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** (user_id) **in place** (mutates), so it persists for the rest of this logger's lifecycle - every subsequent line, audit and routine, attributes the actor. The mutating twin of Logger.withBindings(), for the common case where one request logger is threaded by reference and gains its identity mid-request.

⚠️ 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 user_id bleeds into other users' lines, **misattributing audit events**. Only ever call this on a per-request logger.

setContext(options)

Merge context into this logger **in place** (mutates).

⚠️ 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.