Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Logger

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.

// 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/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

constructor

  • Constructs a new Logger.

    Parameters

    • optionsOrName: LoggerOptions | string

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

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

    Returns Logger

Properties

Static DEFAULT_LEVEL

DEFAULT_LEVEL: WARN = LoggerLevel.WARN

The default LoggerLevel when constructing new Logger instances.

Static LEVEL_NAMES

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

A list of all lower case LoggerLevel names.

See LoggerLevel

Static ROOT_NAME

ROOT_NAME: "sfdx" = "sfdx"

The name of the root sfdx Logger.

Methods

addField

  • Add a field to all log lines for this logger. For convenience this object is returned.

    Parameters

    • name: string

      The name of the field to add.

    • value: FieldValue

      The value of the field to be logged.

    Returns Logger

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. Resolved or rejected upon completion of the addition.

    Parameters

    • logFile: string

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

    Returns Promise<void>

addStream

child

  • Create a child logger, typically to add a few log record fields. For convenience this object is returned.

    Parameters

    • name: string

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

    • Default value fields: Fields = {}

      Additional fields included in all log lines for the child logger.

    Returns Logger

close

  • close(fn?: undefined | function): void
  • Close the logger, including any streams, and remove all listeners.

    Parameters

    • Optional fn: undefined | function

      A function with signature (stream: LoggerStream) => void to call for each stream with the stream as an arg.

    Returns void

debug

  • debug(...args: Array<unknown>): Logger
  • Logs at debug level with filtering applied. For convenience this object is returned.

    Parameters

    • Rest ...args: Array<unknown>

      Any number of arguments to be logged.

    Returns Logger

error

  • error(...args: Array<unknown>): Logger
  • Logs at error level with filtering applied. For convenience this object is returned.

    Parameters

    • Rest ...args: Array<unknown>

      Any number of arguments to be logged.

    Returns Logger

fatal

  • fatal(...args: Array<unknown>): Logger
  • Logs at fatal level with filtering applied. For convenience this object is returned.

    Parameters

    • Rest ...args: Array<unknown>

      Any number of arguments to be logged.

    Returns Logger

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

getLevel

getName

  • getName(): string
  • Gets the name of this logger.

    Returns string

info

  • info(...args: Array<unknown>): Logger
  • Logs at info level with filtering applied. For convenience this object is returned.

    Parameters

    • Rest ...args: Array<unknown>

      Any number of arguments to be logged.

    Returns Logger

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. For convenience this object is returned.

    Parameters

    Returns Logger

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. For convenience this object is returned.

    Parameters

    • Rest ...args: any[]

      Any number of arguments to be logged.

    Returns Logger

useMemoryLogging

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

    Returns Logger

warn

  • warn(...args: Array<unknown>): Logger
  • Logs at warn level with filtering applied. For convenience this object is returned.

    Parameters

    • Rest ...args: Array<unknown>

      Any number of arguments to be logged.

    Returns Logger

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

      Additional fields included in all log lines.

    Returns Promise<Logger>

Static getLevelByName

  • Gets a numeric LoggerLevel value by string name.

    see

    LoggerLevel

    Parameters

    • levelName: string

      The level name to convert to a LoggerLevel enum value.

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

    Returns LoggerLevelValue

Static root

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

    Returns Promise<Logger>