@axiomhq/logging/dist/cjs/logger.d.cts

The official logging package for Axiom

import { Transport } from '.';
/**
 * Symbol used to specify properties that should be added to the root of the log event
 * rather than to the fields property.
 *
 * @example
 * const EVENT = Symbol.for('logging.event');
 * logger.info("User logged in", {
 *   userId: 123,
 *   [EVENT]: { traceId: "abc123" }
 * });
 */
export declare const EVENT: unique symbol;
/**
 * LogEvent interface representing a log entry.
 * This interface defines the structure of log events processed by the logger.
 */
export interface LogEvent extends Record<string, any> {
    level: string;
    message: string;
    fields: any;
    _time: string;
    '@app': {
        [key: FrameworkIdentifier['name']]: FrameworkIdentifier['version'];
    };
    source: string;
}
export declare const LogLevelValue: {
    readonly debug: 0;
    readonly info: 1;
    readonly warn: 2;
    readonly error: 3;
    readonly off: 100;
};
export declare const LogLevel: {
    readonly debug: "debug";
    readonly info: "info";
    readonly warn: "warn";
    readonly error: "error";
    readonly off: "off";
};
export type LogLevelValue = (typeof LogLevelValue)[keyof typeof LogLevelValue];
export type LogLevel = keyof typeof LogLevelValue;
export type Formatter<T extends Record<string, any> = LogEvent, U extends Record<string, any> = LogEvent> = (logEvent: T) => U;
export type FrameworkIdentifier = {
    name: `${string}-version`;
    version: string;
};
export type LoggerConfig = {
    args?: Record<string | symbol, any>;
    transports: [Transport, ...Transport[]];
    logLevel?: LogLevel;
    formatters?: Array<Formatter>;
    overrideDefaultFormatters?: boolean;
};
export declare class Logger {
    initConfig: LoggerConfig;
    children: Logger[];
    logLevel: LogLevelValue;
    config: LoggerConfig;
    constructor(initConfig: LoggerConfig);
    raw(log: any): void;
    /**
     * Log a debug message
     * @param message The log message
     * @param options Log options that can include fields and a special EVENT symbol
     *
     * @example
     * // Add fields to the log event
     * logger.debug("User action", { userId: 123 });
     */
    debug: (message: string, args?: Record<string | symbol, any>) => void;
    /**
     * Log an info message
     * @param message The log message
     * @param options Log options that can include fields and a special EVENT symbol
     *
     * @example
     * // Add fields to the log event
     * logger.info("User logged in", { userId: 123 });
     */
    info: (message: string, args?: Record<string | symbol, any>) => void;
    /**
     * Log a warning message
     * @param message The log message
     * @param options Log options that can include fields and a special EVENT symbol
     *
     * @example
     * // Add fields to the log event
     * logger.warn("Rate limit approaching", { requestCount: 950 });
     */
    warn: (message: string, args?: Record<string | symbol, any>) => void;
    /**
     * Log an error message
     * @param message The log message
     * @param options Log options that can include fields and a special EVENT symbol
     *
     * @example
     * // Log an error with stack trace
     * try {
     *   // some code that throws
     * } catch (err) {
     *   logger.error("Operation failed", err);
     * }
     */
    error: (message: string, args?: Record<string | symbol, any>) => void;
    /**
     * Create a child logger with additional context fields
     * @param fields Additional context fields to include in all logs from this logger
     *
     * @example
     * // Create a child logger with additional fields
     * const childLogger = logger.with({ userId: 123 });
     */
    with: (fields: Record<string | symbol, any>) => Logger;
    private _transformEvent;
    /**
     * Log a message with the specified level
     * @param level The log level
     * @param message The log message
     * @param options Log options or Error object
     */
    log: (level: LogLevel, message: string, args?: Record<string | symbol, any>) => void;
    flush: () => Promise<void>;
}