@salesforce/core/lib/logger.d.ts

/// <reference types="node" />
import { Writable } from 'stream';
/**
 * A Bunyan `Serializer` function.
 *
 * @param input The input to be serialized.
 * **See** {@link https://github.com/forcedotcom/node-bunyan#serializers|Bunyan Serializers API}
 */
export type Serializer = (input: unknown) => unknown;
/**
 * A collection of named `Serializer`s.
 *
 * **See** {@link https://github.com/forcedotcom/node-bunyan#serializers|Bunyan Serializers API}
 */
export interface Serializers {
    [key: string]: Serializer;
}
/**
 * The common set of `Logger` options.
 */
export interface LoggerOptions {
    /**
     * The logger name.
     */
    name: string;
    /**
     * The logger format type. Current options include LogFmt or JSON (default).
     */
    format?: LoggerFormat;
    /**
     * The logger's serializers.
     */
    serializers?: Serializers;
    /**
     * Whether or not to log source file, line, and function information.
     */
    src?: boolean;
    /**
     * The desired log level.
     */
    level?: LoggerLevelValue;
    /**
     * A stream to write to.
     */
    stream?: Writable;
    /**
     * An array of streams to write to.
     */
    streams?: LoggerStream[];
}
/**
 * Standard `Logger` levels.
 *
 * **See** {@link https://github.com/forcedotcom/node-bunyan#levels|Bunyan Levels}
 */
export declare enum LoggerLevel {
    TRACE = 10,
    DEBUG = 20,
    INFO = 30,
    WARN = 40,
    ERROR = 50,
    FATAL = 60
}
/**
 * `Logger` format types.
 */
export declare enum LoggerFormat {
    JSON = 0,
    LOGFMT = 1
}
/**
 * A Bunyan stream configuration.
 *
 * @see {@link https://github.com/forcedotcom/node-bunyan#streams|Bunyan Streams}
 */
export interface LoggerStream {
    [key: string]: any;
    /**
     * The type of stream -- may be inferred from other properties.
     */
    type?: string;
    /**
     * The desired log level for the stream.
     */
    level?: LoggerLevelValue;
    /**
     * The stream to write to.  Mutually exclusive with `path`.
     */
    stream?: Writable;
    /**
     * The name of the stream.
     */
    name?: string;
    /**
     * A log file path to write to.  Mutually exclusive with `stream`.
     */
    path?: string;
}
/**
 * Any numeric `Logger` level.
 */
export type LoggerLevelValue = LoggerLevel | number;
/**
 * A collection of named `FieldValue`s.
 *
 * **See** {@link https://github.com/forcedotcom/node-bunyan#log-record-fields|Bunyan Log Record Fields}
 */
export interface Fields {
    [key: string]: FieldValue;
}
/**
 * All possible field value types.
 */
export type FieldValue = string | number | boolean;
/**
 * Log line interface
 */
export interface LogLine {
    name: string;
    hostname: string;
    pid: string;
    log: string;
    level: number;
    msg: string;
    time: string;
    v: number;
}
/**
 * A logging abstraction powered by {@link https://github.com/forcedotcom/node-bunyan|Bunyan} that provides both a default
 * logger configuration that will log to `sfdx.log`, and a way to create custom loggers based on the same foundation.
 *
 * ```
 * // Gets the root sfdx logger
 * const logger = await Logger.root();
 *
 * // Creates a child logger of the root sfdx logger with custom fields applied
 * const childLogger = await Logger.child('myRootChild', {tag: 'value'});
 *
 * // Creates a custom logger unaffiliated with the root logger
 * const myCustomLogger = new Logger('myCustomLogger');
 *
 * // Creates a child of a custom logger unaffiliated with the root logger with custom fields applied
 * const myCustomChildLogger = myCustomLogger.child('myCustomChild', {tag: 'value'});
 * ```
 * **See** https://github.com/forcedotcom/node-bunyan
 *
 * **See** https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_dev_cli_log_messages.htm
 */
export declare class Logger {
    /**
     * The name of the root sfdx `Logger`.
     */
    static readonly ROOT_NAME = "sf";
    /**
     * The default `LoggerLevel` when constructing new `Logger` instances.
     */
    static readonly DEFAULT_LEVEL = LoggerLevel.WARN;
    /**
     * A list of all lower case `LoggerLevel` names.
     *
     * **See** {@link LoggerLevel}
     */
    static readonly LEVEL_NAMES: string[];
    private static readonly lifecycle;
    private static rootLogger?;
    /**
     * The default rotation period for logs. Example '1d' will rotate logs daily (at midnight).
     * See 'period' docs here: https://github.com/forcedotcom/node-bunyan#stream-type-rotating-file
     */
    readonly logRotationPeriod: string;
    /**
     * The number of backup rotated log files to keep.
     * Example: '3' will have the base sf.log file, and the past 3 (period) log files.
     * See 'count' docs here: https://github.com/forcedotcom/node-bunyan#stream-type-rotating-file
     */
    readonly logRotationCount: number;
    /**
     * Whether debug is enabled for this Logger.
     */
    debugEnabled: boolean;
    private bunyan;
    private readonly format;
    /**
     * Constructs a new `Logger`.
     *
     * @param optionsOrName A set of `LoggerOptions` or name to use with the default options.
     *
     * **Throws** *{@link SfError}{ name: 'RedundantRootLoggerError' }* More than one attempt is made to construct the root
     * `Logger`.
     */
    constructor(optionsOrName: LoggerOptions | string);
    /**
     * Gets the root logger with the default level, file stream, and DEBUG enabled.
     */
    static root(): Promise<Logger>;
    /**
     * Gets the root logger with the default level, file stream, and DEBUG enabled.
     */
    static getRoot(): Logger;
    /**
     * Destroys the root `Logger`.
     *
     * @ignore
     */
    static destroyRoot(): void;
    /**
     * Create a child of the root logger, inheriting this instance's configuration such as `level`, `streams`, etc.
     *
     * @param name The name of the child logger.
     * @param fields Additional fields included in all log lines.
     */
    static child(name: string, fields?: Fields): Promise<Logger>;
    /**
     * Create a child of the root logger, inheriting this instance's configuration such as `level`, `streams`, etc.
     *
     * @param name The name of the child logger.
     * @param fields Additional fields included in all log lines.
     */
    static childFromRoot(name: string, fields?: Fields): Logger;
    /**
     * Gets a numeric `LoggerLevel` value by string name.
     *
     * @param {string} levelName The level name to convert to a `LoggerLevel` enum value.
     *
     * **Throws** *{@link SfError}{ name: 'UnrecognizedLoggerLevelNameError' }* The level name was not case-insensitively recognized as a valid `LoggerLevel` value.
     * @see {@Link LoggerLevel}
     */
    static getLevelByName(levelName: string): LoggerLevelValue;
    /**
     * Adds a stream.
     *
     * @param stream The stream configuration to add.
     * @param defaultLevel The default level of the stream.
     */
    addStream(stream: LoggerStream, defaultLevel?: LoggerLevelValue): void;
    /**
     * Adds a file stream to this logger. Resolved or rejected upon completion of the addition.
     *
     * @param logFile The path to the log file.  If it doesn't exist it will be created.
     */
    addLogFileStream(logFile: string): Promise<void>;
    /**
     * Adds a file stream to this logger. Resolved or rejected upon completion of the addition.
     *
     * @param logFile The path to the log file.  If it doesn't exist it will be created.
     */
    addLogFileStreamSync(logFile: string): void;
    /**
     * Gets the name of this logger.
     */
    getName(): string;
    /**
     * Gets the current level of this logger.
     */
    getLevel(): LoggerLevelValue;
    /**
     * Set the logging level of all streams for this logger.  If a specific `level` is not provided, this method will
     * attempt to read it from the environment variable `SFDX_LOG_LEVEL`, and if not found,
     * {@link Logger.DEFAULT_LOG_LEVEL} will be used instead. For convenience `this` object is returned.
     *
     * @param {LoggerLevelValue} [level] The logger level.
     *
     * **Throws** *{@link SfError}{ name: 'UnrecognizedLoggerLevelNameError' }* A value of `level` read from `SFDX_LOG_LEVEL`
     * was invalid.
     *
     * ```
     * // Sets the level from the environment or default value
     * logger.setLevel()
     *
     * // Set the level from the INFO enum
     * logger.setLevel(LoggerLevel.INFO)
     *
     * // Sets the level case-insensitively from a string value
     * logger.setLevel(Logger.getLevelByName('info'))
     * ```
     */
    setLevel(level?: LoggerLevelValue): Logger;
    /**
     * Gets the underlying Bunyan logger.
     */
    getBunyanLogger(): any;
    /**
     * Compares the requested log level with the current log level.  Returns true if
     * the requested log level is greater than or equal to the current log level.
     *
     * @param level The requested log level to compare against the currently set log level.
     */
    shouldLog(level: LoggerLevelValue): boolean;
    /**
     * Use in-memory logging for this logger instance instead of any parent streams. Useful for testing.
     * For convenience this object is returned.
     *
     * **WARNING: This cannot be undone for this logger instance.**
     */
    useMemoryLogging(): Logger;
    /**
     * Gets an array of log line objects. Each element is an object that corresponds to a log line.
     */
    getBufferedRecords(): LogLine[];
    /**
     * Reads a text blob of all the log lines contained in memory or the log file.
     */
    readLogContentsAsText(): string;
    /**
     * Adds a filter to be applied to all logged messages.
     *
     * @param filter A function with signature `(...args: any[]) => any[]` that transforms log message arguments.
     */
    addFilter(filter: (...args: unknown[]) => unknown): void;
    /**
     * Close the logger, including any streams, and remove all listeners.
     *
     * @param fn A function with signature `(stream: LoggerStream) => void` to call for each stream with the stream as an arg.
     */
    close(fn?: (stream: LoggerStream) => void): void;
    /**
     * Create a child logger, typically to add a few log record fields. For convenience this object is returned.
     *
     * @param name The name of the child logger that is emitted w/ log line as `log:<name>`.
     * @param fields Additional fields included in all log lines for the child logger.
     */
    child(name: string, fields?: Fields): Logger;
    /**
     * Add a field to all log lines for this logger. For convenience `this` object is returned.
     *
     * @param name The name of the field to add.
     * @param value The value of the field to be logged.
     */
    addField(name: string, value: FieldValue): Logger;
    /**
     * Logs at `trace` level with filtering applied. For convenience `this` object is returned.
     *
     * @param args Any number of arguments to be logged.
     */
    trace(...args: any[]): Logger;
    /**
     * Logs at `debug` level with filtering applied. For convenience `this` object is returned.
     *
     * @param args Any number of arguments to be logged.
     */
    debug(...args: unknown[]): Logger;
    /**
     * Logs at `debug` level with filtering applied.
     *
     * @param cb A callback that returns on array objects to be logged.
     */
    debugCallback(cb: () => unknown[] | string): void;
    /**
     * Logs at `info` level with filtering applied. For convenience `this` object is returned.
     *
     * @param args Any number of arguments to be logged.
     */
    info(...args: unknown[]): Logger;
    /**
     * Logs at `warn` level with filtering applied. For convenience `this` object is returned.
     *
     * @param args Any number of arguments to be logged.
     */
    warn(...args: unknown[]): Logger;
    /**
     * Logs at `error` level with filtering applied. For convenience `this` object is returned.
     *
     * @param args Any number of arguments to be logged.
     */
    error(...args: unknown[]): Logger;
    /**
     * Logs at `fatal` level with filtering applied. For convenience `this` object is returned.
     *
     * @param args Any number of arguments to be logged.
     */
    fatal(...args: unknown[]): Logger;
    /**
     * Enables logging to stdout when the DEBUG environment variable is used. It uses the logger
     * name as the debug name, so you can do DEBUG=<logger-name> to filter the results to your logger.
     */
    enableDEBUG(): void;
    private applyFilters;
    private uncaughtExceptionHandler;
    private exitHandler;
    private createLogFmtFormatterStream;
}