@salesforce/core
Options
All
  • Public
  • Public/Protected
  • All
Menu

A logging abstraction powered by 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.

example

// Gets the root sfdx logger const logger = await Logger.root();

example

// Creates a child logger of the root sfdx logger with custom fields applied const childLogger = await Logger.child('myRootChild', {tag: 'value'});

example

// Creates a custom logger unaffiliated with the root logger const myCustomLogger = new Logger('myCustomLogger');

example

// 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/cwallsfdc/node-bunyan

see

https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_cli_log_messages.htm

Hierarchy

  • Logger

Index

Constructors

Properties

Methods

Constructors

constructor

  • Constructs a new Logger.

    throws

    {SfdxError} {name: 'RedundantRootLogger'}: More than one attempt is made to construct the root Logger.

    Parameters

    • optionsOrName: LoggerOptions | string

      A set of LoggerOptions or name to use with the default options.

    Returns Logger

Properties

Static DEFAULT_LEVEL

DEFAULT_LEVEL: WARN = LoggerLevel.WARN

The default LoggerLevel when constructing new Logger instances.

type

{LoggerLevel}

Static LEVEL_NAMES

LEVEL_NAMES: string[] = Object.values(LoggerLevel).filter(isString).map(v => v.toLowerCase())

A list of all lower case LoggerLevel names.

type

{string[]}

see

LoggerLevel

Static ROOT_NAME

ROOT_NAME: "sfdx" = "sfdx"

The name of the root sfdx Logger.

type

{string}

see

Logger.root

Methods

addField

  • Add a field to all log lines for this logger.

    Parameters

    • name: string

      The name of the field to add.

    • value: FieldValue

      The value of the field to be logged.

    Returns Logger

    For convenience this object is returned.

addFilter

  • addFilter(filter: function): void

  • Adds a filter to be applied to all logged messages.

    Parameters

    • filter: function

      A function with signature (...args: any[]) => any[] that transforms log message arguments.

        • (...args: Array<unknown>): unknown

        • Parameters

          • Rest ...args: Array<unknown>

          Returns unknown

    Returns void

addLogFileStream

  • addLogFileStream(logFile: string): Promise<void>

  • Adds a file stream to this logger.

    Parameters

    • logFile: string

      The path to the log file. If it doesn't exist it will be created.

    Returns Promise<void>

    Resolved or rejected upon completion of the addition.

addStream

  • Adds a stream.

    Parameters

    Returns void

child

  • Create a child logger, typically to add a few log record fields.

    Parameters

    • name: string

      The name of the child logger that is emitted w/ log line as log:<name>.

    • Default value fields: Fields = {}

    Returns Logger

    For convenience this object is returned.

close

  • close(fn?: undefined | function): void

  • Close the logger, including any streams, and remove all listeners.

    Parameters

    • Optional fn: undefined | function

    Returns void

debug

  • debug(...args: Array<unknown>): Logger

  • Logs at debug level with filtering applied.

    Parameters

    • Rest ...args: Array<unknown>

      Any number of arguments to be logged.

    Returns Logger

    For convenience this object is returned.

error

  • error(...args: Array<unknown>): Logger

  • Logs at error level with filtering applied.

    Parameters

    • Rest ...args: Array<unknown>

      Any number of arguments to be logged.

    Returns Logger

    For convenience this object is returned.

fatal

  • fatal(...args: Array<unknown>): Logger

  • Logs at fatal level with filtering applied.

    Parameters

    • Rest ...args: Array<unknown>

      Any number of arguments to be logged.

    Returns Logger

    For convenience this object is returned.

getBufferedRecords

  • Gets an array of log line objects. Each element is an object that corresponds to a log line.

    Returns LogLine[]

getBunyanLogger

  • getBunyanLogger(): any

  • Gets the underlying Bunyan logger.

    Returns any

    The low-level Bunyan logger.

getLevel

  • Gets the current level of this logger.

    Returns LoggerLevelValue

getName

  • getName(): string

  • Gets the name of this logger.

    Returns string

info

  • info(...args: Array<unknown>): Logger

  • Logs at info level with filtering applied.

    Parameters

    • Rest ...args: Array<unknown>

      Any number of arguments to be logged.

    Returns Logger

    For convenience this object is returned.

readLogContentsAsText

  • readLogContentsAsText(): string

  • Reads a text blob of all the log lines contained in memory or the log file.

    Returns string

setLevel

  • 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.

    example

    // Sets the level from the environment or default value logger.setLevel()

    example

    // Set the level from the INFO enum logger.setLevel(LoggerLevel.INFO)

    example

    // Sets the level case-insensitively from a string value logger.setLevel(Logger.getLevelByName('info'))

    throws

    {SfdxError} {name: 'UnrecognizedLoggerLevelName'}: A value of level read from SFDX_LOG_LEVEL was invalid.

    Parameters

    Returns Logger

    For convenience this object is returned.

shouldLog

  • 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.

    Parameters

    • level: LoggerLevelValue

      The requested log level to compare against the currently set log level.

    Returns boolean

trace

  • trace(...args: any[]): Logger

  • Logs at trace level with filtering applied.

    Parameters

    • Rest ...args: any[]

      Any number of arguments to be logged.

    Returns Logger

    For convenience this object is returned.

useMemoryLogging

  • Use in-memory logging for this logger instance instead of any parent streams. Useful for testing.

    WARNING: This cannot be undone for this logger instance.

    Returns Logger

    For convenience this object is returned.

warn

  • warn(...args: Array<unknown>): Logger

  • Logs at warn level with filtering applied.

    Parameters

    • Rest ...args: Array<unknown>

      Any number of arguments to be logged.

    Returns Logger

    For convenience this object is returned.

Static child

  • Create a child of the root logger, inheriting this instance's configuration such as level, streams, etc.

    Parameters

    • name: string

      The name of the child logger.

    • Optional fields: Fields

    Returns Promise<Logger>

Static getLevelByName

  • Gets a numeric LoggerLevel value by string name.

    throws

    {SfdxError} {name: 'UnrecognizedLoggerLevelName'}: The level name was not case-insensitively recognized as a valid LoggerLevel value.

    see

    LoggerLevel

    Parameters

    • levelName: string

      The level name to convert to a LoggerLevel enum value.

    Returns LoggerLevelValue

Static root

  • Gets the root logger with the default level and file stream.

    Returns Promise<Logger>