lib/logging

Logging and telemetry system for True Life.

This module provides a comprehensive logging and tracing solution that works across all runtimes (web, client, server) and exports telemetry to OpenTelemetry.

Architecture

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────────────┐
│  Web UI  │ ──► │  Client  │ ──► │  Server  │ ──► │  OTEL Collector  │
└──────────┘     └──────────┘     └──────────┘     └──────────────────┘
                                                             │
                                                             ▼
                                                   ┌──────────────────┐
                                                   │   Tempo / Loki   │
                                                   └──────────────────┘
                                                             │
                                                             ▼
                                                   ┌──────────────────┐
                                                   │     Grafana      │
                                                   └──────────────────┘

Quick Start

import { log, createLogger, withSpan } from "@core/logging";

// Simple logging
log.info("Application started");
log.error("Something failed", new Error("oops"));

// Module-specific logger
const logger = createLogger("banking");
logger.info("Transaction complete", { amount: 100 });

// Traced operations
await withSpan("process-payment", async (span) => {
    span.attributes = { orderId: "123" };
    log.info("Processing payment...");
    await processPayment();
});

Trace Context Propagation

Trace context flows from web → client → server, creating a unified trace:

[web:button-click]
  └── [client:handle-interaction]
        └── [server:process-request]

Enumerations

Enumeration	Description
LogLevel	Log severity levels aligned with OpenTelemetry severity numbers.

Classes

Class	Description
Logger	Structured logger with trace context support.

Interfaces

Interface	Description
LoggerConfig	Configuration for the logger.
LogRecord	A structured log record compatible with OTLP Log Data Model.
Span	A span representing a unit of work in a trace.
TelemetryBatch	Batch of telemetry data for forwarding between runtimes. Used for the web → client → server pipeline.
TraceContext	W3C Trace Context compatible trace context.
TraceStack	Stack of trace contexts for nested operations. Allows building a trace hierarchy as requests flow through the system.

Type Aliases

Type Alias	Description
Attributes	Arbitrary attributes that can be attached to log records and spans.
LogLevelName	String representation of log levels for human readability.
Runtime	Runtime environment identifier.

Variables

DEFAULT_LOGGER_CONFIG

const DEFAULT_LOGGER_CONFIG: LoggerConfig;

Defined in: src/lib/logging/types.ts:275

Default logger configuration.

---

log

const log: Logger;

Defined in: src/lib/logging/logger.ts:376

Global logger instance. Use this for quick logging without creating a module-specific logger.

---

LOG_LEVEL_NAMES

const LOG_LEVEL_NAMES: Record\<LogLevel, LogLevelName\>;

Defined in: src/lib/logging/types.ts:45

Maps LogLevel enum to string names.

---

LOG_LEVEL_VALUES

const LOG_LEVEL_VALUES: Record\<LogLevelName, LogLevel\>;

Defined in: src/lib/logging/types.ts:57

Maps string names to LogLevel enum values.

Functions

Function	Description
buildTraceStack	Builds a trace stack from the current context stack.
clearContextStack	Clears the entire context stack. Useful for cleanup between tests or on shutdown.
createContextFromStack	Creates a trace context from a trace stack received from another runtime. This continues the trace by creating a new span as a child of the last span.
createLogger	Creates a logger for a specific module.
createTraceContext	Creates a new trace context, optionally as a child of an existing context.
endSpan	Ends a span and pops it from the context stack.
generateSpanId	Generates a new span ID (16 hex characters).
generateTraceId	Generates a new trace ID (32 hex characters).
getActiveSpan	Gets an active span by its span ID.
getCurrentContext	Gets the current trace context, if any.
getRuntime	Gets the current runtime.
onLogRecord	Registers a listener for log records. Used by the telemetry pipeline to forward logs.
onSpanEnd	Registers a listener for when spans end.
onSpanStart	Registers a listener for when spans start.
parseTraceparent	Parses a W3C traceparent header into a trace context.
popContext	Pops the current trace context from the stack.
pushContext	Pushes a trace context onto the stack.
serializeTraceparent	Serializes a trace context to a W3C traceparent header format.
setLogLevel	Sets the minimum log level for the global logger.
setRuntime	Sets the current runtime. Called during initialization.
startSpan	Starts a new span and pushes it onto the context stack.
withSpan	Executes a function within a new span context. Automatically ends the span when the function completes.
withSpanSync	Synchronous version of withSpan for non-async operations.