API

Complete API reference for the evlog-backed Logger module

This page documents the public API of the @vercube/logger package. Under the hood it delegates to evlog; evlog's own primitives are re-exported for advanced use.

Logger (Abstract Class)

The DI token and contract implemented by every logger.

abstract class Logger {
  public abstract configure(options: LoggerTypes.Options): void;
  public abstract debug(...args: LoggerTypes.Arg[]): void;
  public abstract info(...args: LoggerTypes.Arg[]): void;
  public abstract warn(...args: LoggerTypes.Arg[]): void;
  public abstract error(...args: LoggerTypes.Arg[]): void;
  public abstract set(context: LoggerTypes.Context): void;
  public abstract getContext(): LoggerTypes.Context;
  public abstract child(context: LoggerTypes.Context): Logger;
  public abstract emit(overrides?: LoggerTypes.Context): void;
}

configure(options)

Initializes the underlying evlog logger. Maps to evlog's initLogger. The logLevel option is an alias for evlog's minLevel.

container.get(Logger).configure({ logLevel: 'info', pretty: true });

debug() / info() / warn() / error()

Emit a single event at the given level. Accept any mix of strings, objects and errors:

logger.info('AuthService', 'user logged in');     // tagged log
logger.info('request completed', { status: 200 }); // message + fields
logger.error('DB::connect', error);                 // tag + Error
logger.warn('rate limit approaching');              // message only

See How arguments map to events.

set(context)

Merge structured fields into every subsequent event from this logger.

logger.set({ requestId: 'abc', userId: 42 });
logger.info('processing'); // event includes requestId + userId

getContext()

Returns a shallow copy of the accumulated context.

child(context)

Creates a derived logger that inherits the parent's context plus extra fields. The child's context is isolated from the parent.

const reqLogger = logger.child({ requestId: 'abc' });

emit(overrides?)

Flush the accumulated context as one wide event, then reset it.

logger.set({ jobId: 'sync-001' });
logger.emit({ outcome: 'success' });

BaseLogger (Class)

The default evlog-backed implementation of Logger, bound automatically by @vercube/core.

import { Logger, BaseLogger } from '@vercube/logger';

container.bind(Logger, BaseLogger);

All methods are described under Logger.

Types

LoggerTypes.Level

type Level = 'debug' | 'info' | 'warn' | 'error';

Hierarchical, aligned with evlog: debug < info < warn < error.

LoggerTypes.Arg

type Arg = unknown;

A single argument passed to a log method.

LoggerTypes.Context

type Context = Record<string, unknown>;

Structured fields attached to wide events.

LoggerTypes.Options

Configuration accepted by configure(). Extends evlog's LoggerConfig:

interface Options extends LoggerConfig {
  /** Alias for evlog `minLevel`; wins when both are set. */
  logLevel?: Level;
}

Notable LoggerConfig fields: enabled, env, pretty, silent, stringify, minLevel, sampling, redact, drain. See the evlog configuration reference.

Re-exported evlog primitives

For advanced wide-event and structured-error usage, @vercube/logger re-exports evlog directly:

import {
  log,             // evlog's simple singleton log API
  initLogger,      // low-level init (configure() wraps this)
  createLogger,    // create an isolated wide-event logger
  createRequestLogger,
  createError,     // structured errors
  parseError,
  EvlogError,
  defineError,
  defineErrorCatalog,
} from '@vercube/logger';

import type {
  Log, RequestLogger, RequestLoggerOptions, LoggerConfig, LogLevel,
  WideEvent, EnvironmentContext, SamplingConfig, RedactConfig,
  DrainContext, DrainFn, ErrorOptions,
} from '@vercube/logger';

Toolkit

The evlog toolkit (framework-integration building blocks) is available as a subpath export:

import {
  createMiddlewareLogger,
  createLoggerStorage,
  extractSafeHeaders,
  extractSafeNodeHeaders,
} from '@vercube/logger/toolkit';

EvlogMiddleware (from @vercube/core)

Global middleware that emits one wide event per request. Registered by default; disable via requestLogging: false in the app config.

import { EvlogMiddleware, EVLOG_REQUEST_LOGGER_KEY } from '@vercube/core';

The request-scoped logger is stored in RequestContext under EVLOG_REQUEST_LOGGER_KEY, so handlers can enrich the wide event.

Report an issue or Edit this page on GitHub
Previous

Overview

The @vercube/serverless package bridges AWS Lambda and Azure Functions to Vercube’s Request / Response model.

Next