Class Logger

A logging abstraction powered by Pino that provides both a default logger configuration that will log to the default path, 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'});

// get a raw pino logger from the root instance of Logger
// you can use these to avoid constructing another Logger wrapper class and to get better type support
const logger = Logger.getRawRootLogger().child({name: 'foo', otherProp: 'bar'});
logger.info({some: 'stuff'}, 'a message');


// get a raw pino logger from the current instance
const childLogger = await Logger.child('myRootChild', {tag: 'value'});
const logger = childLogger.getRawLogger();

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

Constructors

constructor

Properties

DEFAULT_LEVEL LEVEL_NAMES ROOT_NAME

Methods

addField child debug debugCallback error fatal getBufferedRecords getLevel getName getRawLogger info readLogContentsAsText setLevel shouldLog trace warn child childFromRoot getLevelByName getRawRootLogger getRoot root

Constructors

constructor

  • new Logger(optionsOrName): Logger

  • Constructs a new Logger.

    Parameters

    • optionsOrName: string | LoggerOptions

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

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

    Returns Logger

Properties

Static Readonly DEFAULT_LEVEL

DEFAULT_LEVEL: WARN = LoggerLevel.WARN

The default LoggerLevel when constructing new Logger instances.

Static Readonly LEVEL_NAMES

LEVEL_NAMES: string[] = ...

A list of all lower case LoggerLevel names.

See LoggerLevel

Static Readonly ROOT_NAME

ROOT_NAME: "sf" = 'sf'

The name of the root sfdx Logger.

Methods

addField

  • addField(name, value): Logger

  • 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

child

  • child(name, fields?): Logger

  • 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. Will be prefixed with the parent logger name and :

    • fields: Fields = {}

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

    Returns Logger

debug

  • debug(...args): Logger

  • Logs at debug level with filtering applied. For convenience this object is returned.

    Parameters

    • Rest ...args: unknown[]

      Any number of arguments to be logged.

    Returns Logger

debugCallback

  • debugCallback(cb): void

  • Logs at debug level with filtering applied.

    Parameters

    • cb: (() => string | unknown[])

      A callback that returns on array objects to be logged.

        • (): string | unknown[]

        • Returns string | unknown[]

    Returns void

error

  • error(...args): Logger

  • Logs at error level with filtering applied. For convenience this object is returned.

    Parameters

    • Rest ...args: unknown[]

      Any number of arguments to be logged.

    Returns Logger

fatal

  • fatal(...args): Logger

  • Logs at fatal level with filtering applied. For convenience this object is returned.

    Parameters

    • Rest ...args: unknown[]

      Any number of arguments to be logged.

    Returns Logger

getBufferedRecords

getLevel

getName

getRawLogger

  • getRawLogger(): Logger

  • get the bare (pino) logger instead of using the class hierarchy

    Returns Logger

info

  • info(...args): Logger

  • Logs at info level with filtering applied. For convenience this object is returned.

    Parameters

    • Rest ...args: 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

  • setLevel(level?): Logger

  • 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, Logger.DEFAULT_LOG_LEVEL will be used instead. For convenience this object is returned.

    Parameters

    • Optional level: number

      The logger level.

      Throws 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'))

    Returns Logger

shouldLog

  • shouldLog(level): boolean

  • 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: number

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

    Returns boolean

trace

  • trace(...args): 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

warn

  • warn(...args): Logger

  • Logs at warn level with filtering applied. For convenience this object is returned.

    Parameters

    • Rest ...args: unknown[]

      Any number of arguments to be logged.

    Returns Logger

Static child

  • child(name, fields?): Promise<Logger>

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

    Parameters

    • name: string

      The name of the child logger.

    • Optional fields: Fields

      Additional fields included in all log lines.

    Returns Promise<Logger>

Static childFromRoot

  • childFromRoot(name, fields?): Logger

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

    Parameters

    • name: string

      The name of the child logger.

    • Optional fields: Fields

      Additional fields included in all log lines.

    Returns Logger

Static getLevelByName

  • getLevelByName(levelName): number

  • Gets a numeric LoggerLevel value by string name.

    Parameters

    • levelName: string

      The level name to convert to a LoggerLevel enum value.

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

    Returns number

    See

    {@Link LoggerLevel}

Static getRawRootLogger

  • getRawRootLogger(): Logger

  • get the bare (pino) logger instead of using the class hierarchy

    Returns Logger

Static getRoot

Static root

Settings

Member Visibility

Theme

On This Page

constructorDEFAULT_LEVELLEVEL_NAMESROOT_NAMEaddFieldchilddebugdebugCallbackerrorfatalgetBufferedRecordsgetLevelgetNamegetRawLoggerinforeadLogContentsAsTextsetLevelshouldLogtracewarnchildchildFromRootgetLevelByNamegetRawRootLoggergetRootroot