Logging API reference

import type { ChildLoggerOptions } from 'pino';
import type * as logging from './contracts/index.js';
/**
 * Application logging service exposed as `app().log`.
 *
 * Pino supplies the default driver while this service owns framework discovery
 * and lifecycle. Applications may inject a compatible driver in tests.
 *
 * @example
 * app().log.info({ websiteId }, 'Website crawl started');
 */
export declare class Log implements logging.Logger {
    #private;
    /**
     * Creates the application logger from explicit options or the Pino driver.
     *
     * @param options - Logging level, destinations, context, and driver overrides.
     */
    constructor(options?: logging.LoggingOptions);
    /** Returns the current trace function, respecting runtime level changes. */
    get trace(): logging.Logger['trace'];
    /** Returns the current debug function, respecting runtime level changes. */
    get debug(): logging.Logger['debug'];
    /** Returns the current info function, respecting runtime level changes. */
    get info(): logging.Logger['info'];
    /** Returns the current warning function, respecting runtime level changes. */
    get warn(): logging.Logger['warn'];
    /** Returns the current error function, respecting runtime level changes. */
    get error(): logging.Logger['error'];
    /** Returns the current fatal function, respecting runtime level changes. */
    get fatal(): logging.Logger['fatal'];
    /** Returns the driver's non-emitting log function. */
    get silent(): logging.Logger['silent'];
    /**
     * Returns the minimum severity currently emitted by the driver.
     */
    get level(): string;
    /**
     * Changes the minimum emitted severity at runtime.
     *
     * @param level - Pino-compatible log level.
     */
    set level(level: string);
    /**
     * Returns the underlying compatible logger for framework integrations.
     *
     * @returns Driver logger accepted by Fastify and worker adapters.
     */
    get logger(): logging.Logger;
    /**
     * Creates a context-bearing child logger.
     *
     * @param bindings - Stable structured fields for subsequent records.
     * @param options - Optional Pino child logger overrides.
     * @returns Child logger sharing the configured destinations.
     */
    child(bindings: logging.LogBindings, options?: ChildLoggerOptions): logging.Logger;
    /**
     * Waits for accepted records to reach their configured destination.
     */
    flush(): Promise<void>;
    /**
     * Flushes records and releases transport resources.
     */
    close(): Promise<void>;
}

import type { ChildLoggerOptions, LogFn } from 'pino';
/**
 * Standard severity levels supported by the framework logger.
 */
export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent';
/**
 * Structured fields attached to one log record or child logger.
 */
export type LogBindings = Record<string, unknown>;
/**
 * Application logger contract shared by framework services and app code.
 *
 * The call signatures intentionally match Pino so structured records can be
 * passed directly to Fastify and Pino-compatible transports.
 */
export interface Logger {
    /** Minimum severity currently emitted by the logger. */
    level: string;
    /** Writes a highly detailed diagnostic record. */
    trace: LogFn;
    /** Writes a development diagnostic record. */
    debug: LogFn;
    /** Writes a normal operational record. */
    info: LogFn;
    /** Writes a recoverable problem record. */
    warn: LogFn;
    /** Writes a failed operation record. */
    error: LogFn;
    /** Writes a process-ending failure record. */
    fatal: LogFn;
    /** Accepts a record without emitting output. */
    silent: LogFn;
    /**
     * Creates a logger that includes stable fields on every record.
     *
     * @param bindings - Structured context inherited by child records.
     * @param options - Optional Pino child logger behavior.
     * @returns Child logger sharing the same destinations.
     */
    child(bindings: LogBindings, options?: ChildLoggerOptions): Logger;
}

import type { LoggerDriver } from './LoggerDriver.js';
import type { LogBindings, LogLevel } from './Logger.js';
/**
 * HTTP delivery settings for the Platform development log transport.
 */
export interface DevtoolsLogOptions {
    /** Explicit event ingestion endpoint, overriding devtools environment values. */
    url?: string;
    /** Maximum log records sent in one HTTP request. */
    batchSize?: number;
    /** Maximum delay before a partial log batch is sent. */
    flushIntervalMs?: number;
    /** Pause before later records are attempted after a failed request. */
    retryAfterMs?: number;
    /** Maximum duration allowed for one ingestion request. */
    requestTimeoutMs?: number;
    /** Maximum unsent records retained before the oldest record is discarded. */
    maxPendingEvents?: number;
    /** Additional ingestion headers, such as a future service token. */
    headers?: Record<string, string>;
}
/**
 * Application logging configuration.
 */
export interface LoggingOptions {
    /** Injectable logging driver used by tests or alternate implementations. */
    driver?: LoggerDriver;
    /** Minimum emitted severity. Defaults to info, or silent in tests. */
    level?: LogLevel;
    /** Human-readable application or process name attached to every record. */
    source?: string;
    /** Runtime environment copied onto every record. */
    environment?: string;
    /** Disables all logging when false. */
    enabled?: boolean;
    /** Stable fields attached to every root logger record. */
    bindings?: LogBindings;
    /** Sensitive field paths removed before records reach any destination. */
    redact?: false | string[];
    /** Writes newline-delimited JSON to standard output. Defaults to true. */
    console?: boolean;
    /**
     * Streams logs to Platform devtools.
     *
     * Interactive development enables this automatically. Pass false to opt out
     * or an options object to configure delivery explicitly.
     */
    devtools?: boolean | DevtoolsLogOptions;
}

import type { Logger } from './Logger.js';
/**
 * Driver boundary used by the framework logging service.
 */
export interface LoggerDriver {
    /** Logger implementation used for record creation. */
    readonly logger: Logger;
    /**
     * Waits until records already accepted by the driver reach its destination.
     */
    flush(): Promise<void>;
    /**
     * Flushes records and releases transport resources.
     */
    close(): Promise<void>;
}

import { type DestinationStream, type Logger as PinoLogger } from 'pino';
import type * as logging from '../contracts/index.js';
/**
 * Pino-backed logger driver with optional worker-thread devtools delivery.
 */
export declare class PinoLoggerDriver implements logging.LoggerDriver {
    #private;
    readonly logger: PinoLogger;
    /**
     * Creates a Pino logger and its configured destinations.
     *
     * @param options - Framework logging configuration.
     * @param destination - Optional direct destination used by focused tests.
     */
    constructor(options?: logging.LoggingOptions, destination?: DestinationStream);
    /**
     * Waits until Pino has handed accepted records to its destination.
     */
    flush(): Promise<void>;
    /**
     * Flushes records and closes the worker transport when one is active.
     */
    close(): Promise<void>;
}

/**
 * Body representation retained by development HTTP exchange logging.
 */
export interface HttpBodyLog {
    /** How the original payload was represented or why it was omitted. */
    kind: 'empty' | 'json' | 'text' | 'binary' | 'stream';
    /** Media type reported by the request or response. */
    contentType?: string;
    /** Redacted serialized payload size before the development capture limit. */
    sizeBytes?: number;
    /** Whether the displayed value was shortened to the configured byte limit. */
    truncated?: boolean;
    /** Redacted JSON value or captured text when the body is inspectable. */
    value?: unknown;
    /** Human-readable explanation for an omitted payload. */
    note?: string;
}
/**
 * Request fields retained by a development HTTP exchange record.
 */
export interface HttpRequestLog {
    /** HTTP method used by the client. */
    method: string;
    /** Path and query string requested by the client. */
    url: string;
    /** Redacted request headers. */
    headers: Record<string, unknown>;
    /** Bounded and redacted request payload. */
    body: HttpBodyLog;
}
/**
 * Response fields retained by a development HTTP exchange record.
 */
export interface HttpResponseLog {
    /** HTTP status selected before the response is sent. */
    statusCode: number;
    /** Redacted response headers. */
    headers: Record<string, unknown>;
    /** Bounded and redacted response payload. */
    body: HttpBodyLog;
}
/**
 * Development-only request and response data attached to a Pino log record.
 */
export interface HttpExchangeLog {
    /** Incoming request details visible to the Fastify handler. */
    request: HttpRequestLog;
    /** Outgoing response details visible to Fastify's send lifecycle. */
    response: HttpResponseLog;
}