@aws-blocks/bb-logger

Structured logging with consistent JSON format, log levels, and contextual metadata.

Design & mock parity details: DESIGN.md

When to Use

• You need structured, queryable application logs
• You want consistent log format across your backend
• You need request-scoped loggers with correlation IDs
• You want log level filtering without code changes

When NOT to Use

• For numeric measurements over time → use Metrics
• For distributed request tracing → use Tracing

Quick Start

import { Scope } from '@aws-blocks/core';
import { Logger } from '@aws-blocks/bb-logger';

const scope = new Scope('my-app');
const log = new Logger(scope, 'app');

log.info('Server started', { port: 3000 });
log.warn('Slow query', { durationMs: 1500 });
log.error('Request failed', { err: new Error('timeout') });

API

Constructor

new Logger(scope: ScopeParent, id: string, options?: LoggingOptions)

Options:

• level — Minimum log level ('debug' | 'info' | 'warn' | 'error'). Default: 'info'.
• defaultContext — Fields included in every log entry.

Log retention is not a Logger option — it is a compute-level setting (see Retention below).

Methods

log.debug(message: string, context?: Record<string, unknown>): void
log.info(message: string, context?: Record<string, unknown>): void
log.warn(message: string, context?: Record<string, unknown>): void
log.error(message: string, context?: Record<string, unknown>): void
log.child(context: Record<string, unknown>): ChildLogger

All log methods are synchronous (no await needed).

Log Entry Format

Every log entry is a JSON object written to stdout (or stderr for errors):

{
  "level": "info",
  "message": "User logged in",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "logger": "app",
  "userId": "user-123"
}

Child Loggers

Create request-scoped loggers that inherit context:

const requestLog = log.child({ requestId: 'req-abc', userId: 'u-123' });
requestLog.info('Processing request');
// Output includes requestId and userId automatically

Children can be nested:

const dbLog = requestLog.child({ component: 'database' });
dbLog.warn('Slow query', { table: 'users', durationMs: 500 });

Log Level Precedence

1. Constructor level option
2. Default: 'info'

Set the level per Logger via the level option. There is no LOG_LEVEL env var — log level is a runtime construction-time choice.

Error Object Handling

Error instances passed in context are automatically extracted:

try {
  await doSomething();
} catch (err) {
  log.error('Operation failed', { err });
  // err is serialized as { name, message, stack }
}

Serialization Safety

The logger handles edge cases gracefully:

• Circular references → replaced with "[Circular]"
• BigInt values → converted to string
• Functions/Symbols → replaced with "[unserializable]"
• Errors in context → extracted to { name, message, stack }

Retention (Production)

Logging is always on, and retention is a compute-level setting — not a Logger option. Every compute captures its handler's stdout to its own CloudWatch log group, which carries the stack-wide default retention (defaults.logRetention — one week in sandbox, one year in production).

To change retention, set logRetention on the stack-wide defaults (it applies to every compute's handler log group):

import { BlocksPresets } from '@aws-blocks/core/cdk';
import { RetentionDays } from 'aws-cdk-lib/aws-logs';

// In your aws-blocks backend, override the preset's logRetention:
defaults: { ...BlocksPresets.production, logRetention: RetentionDays.ONE_MONTH };

A Logger no longer reconfigures retention — the compute owns the single, framework-owned handler log group. Per-compute retention (a logRetention prop on the compute) arrives with the public compute-configuration surface; until then, defaults.logRetention is the retention knob.

Local Development

In local dev (npm run dev), the Logger BB:

• Writes structured JSON to stdout/stderr (same as production)
• Does NOT persist logs to disk
• Does NOT create any files in .bb-data/
• Retention has no local effect (it is a cloud-only, compute-level setting)
• Log level comes from the Logger's level option (default 'info')

Errors

import { LoggingErrors } from '@aws-blocks/bb-logger';

LoggingErrors.SerializationFailed // 'SerializationFailedException'

This error is used as a marker in degraded log entries when context serialization fails (not thrown to consumers).