officescripts-logging-framework
    Preparing search index...

    Class LoggerImpl

    Singleton class that manages application logging through appenders.

    • Supports the following log events: ERROR, WARN, INFO, TRACE (LOG_EVENT enum).
    • Supports the level of information (verbose) to show via LoggerImpl.LEVEL: OFF, ERROR, WARN, INFO, TRACE, where WARN is the default maximum level of verbosity.
    • If the level of information (LEVEL) is OFF, no log events will be sent to the appenders.
    • Supports the action to take in case of ERROR, WARN log events: the script can continue (LoggerImpl.ACTION.CONTINUE), or abort (LoggerImpl.ACTION.EXIT default). Such actions only take effect if the LEVEL is not LoggerImpl.LEVEL.OFF.
    • Allows defining appenders, controlling the channels the events are sent to.
    • Collects error/warning sent by the appenders via getCriticalEvents().

    Usage:

    • Initialize with LoggerImpl.getInstance(level, action).
    • Add one or more appenders (e.g. ConsoleAppender, ExcelAppender), via addAppender() for example.
    • Use logger.error(), logger.warn(), logger.info(), or logger.trace() to log.

    Features:

    • Supports multiple appenders, allowing logs to be sent to different destinations (e.g., console, Excel).
    • If when invoking any log method (e.g. logger.error()) if the singleton was not instantiated, it does a lazy initialization of the logger with default configuration, i.e. LoggerImpl.LEVEL=WARN and LoggerImpl.ACTION=EXIT.
    • If no appender is added, ConsoleAppender is used by default.
    • Logs are routed through all registered appenders.
    • Collects a summary of error/warning messages and counts. If no appender is defined when a log event occurs, LoggerImpl will automatically create and add a ConsoleAppender. This ensures that log messages are not silently dropped. You may replace or remove this appender at any time using setAppenders() or removeAppender().
    // Minimal logger usage; ConsoleAppender is auto-added if none specified
    LoggerImpl.getInstance().error("This message will appear in the console by default.")
    • Logger for the interface definition.
    • Appender for the interface definition of the appenders
    • ConsoleAppender for the implementation details of the console appender.
    • LogEvent for the structure of log events.

    Implements

    Index

    Properties

    ACTION LEVEL

    Methods

    addAppender error exportState getAction getAppenders getCriticalEvents getErrCnt getLevel getWarnCnt hasCriticalEvents hasErrors hasWarnings info removeAppender reset setAppenders toShortString toString trace warn clearInstance getActionLabel getInstance getLevelLabel

    Properties

    ACTION: Readonly<{ CONTINUE: 0; EXIT: 1 }> = ...

    Static constant (enum pattern) for log event types. Note: enum can't be defined inside a class, so we use a constant object.

    • CONTINUE means the script continues in case of error/warning log events.
    • EXIT means the script throws a ScriptError in case of error/warning log events.
    LEVEL: Readonly<{ OFF: number } & typeof LOG_EVENT> = ...

    Static constant. It generates the same sequence as LOG_EVENT, but adding the zero case with OFF. It ensures the numeric values match the values of LOG_EVENT. Note: enum can't be defined inside a class, so we use a constant object.

    • OFF means no log events will be sent to the appenders.
    • ERROR means only error log events will be sent to the appenders.
    • WARN means error and warning log events will be sent to the appenders.
    • INFO means error, warning, and info log events will be sent to the appenders.
    • TRACE means all log events (error, warning, info, trace) will be sent to the appenders.

    LOG_EVENT for the log event types used to determine the color of the message.

    Methods

    • Adds an appender to the list of appenders.

      Parameters

      Returns void

      ScriptError If:

      • The singleton was not instantiated,
      • The input argument is null or undefined,
      • It breaks the class uniqueness of the appenders. All appenders must be from a different implementation of the Appender class.

      LoggerImpl.setAppenders

    • Sends an error log message (with optional structured extra fields) to all appenders if the level allows it. The level has to be greater than or equal to LoggerImpl.LEVEL.ERROR to send this event to the appenders. After the message is sent, it updates the error counter.

      Parameters

      • msg: string

        The error message to log.

      • OptionalextraFields: LogEventExtraFields

        Optional structured data to attach to the log event (e.g., context info, tags).

      Returns void

      If no singleton was defined, it does lazy initialization with default configuration. If no appender was defined, it does lazy initialization to ConsoleAppender.

      ScriptError If:

      • Level is greater than LoggerImpl.LEVEL.OFF and the action is LoggerImpl.ACTION.EXIT.
      • If any internal error occurs while sending the event to the appenders.

    • Serializes the current state of the logger to a plain object, useful for capturing logs and metrics for post-run analysis. For testing/debugging: Compare expected vs actual logger state. For persisting logs into Excel, JSON, or another external system.

      Returns {
          action: string;
          criticalEvents: LogEvent[];
          errorCount: number;
          level: string;
          warningCount: number;
      }

      A structure with key information about the logger, such as: level, action, errorCount, warningCount, and criticalEvents.

      ScriptError If the singleton was not instantiated.

    • Returns 0 | 1

      The action to take in case of errors or warning log events.

      ScriptError If the singleton was not instantiated.

    • Returns number

      Total number of error message events sent to the appenders.

      ScriptError If the singleton was not instantiated.

    • Returns the level of verbosity allowed in the Logger. The levels are incremental, i.e. it includes all previous levels. For example: LoggerImpl.LEVEL.WARN includes warnings and errors since LoggerImpl.LEVEL.ERROR is lower.

      Returns number

      The current log level.

      ScriptError If the singleton was not instantiated.

    • Returns number

      Total number of warning events sent to the appenders.

      ScriptError If the singleton was not instantiated.

    • Returns boolean

      true if some error or warning event has been sent by the appenders, otherwise false.

      ScriptError If the singleton was not instantiated.

    • Returns boolean

      true if an error log event was sent to the appenders, otherwise false.

      ScriptError If the singleton was not instantiated.

    • Returns boolean

      true if a warning log event was sent to the appenders, otherwise false.

      ScriptError If the singleton was not instantiated.

    • Sends an info log message (with optional structured extra fields) to all appenders if the level allows it. The level has to be greater than or equal to LoggerImpl.LEVEL.INFO to send this event to the appenders.

      Parameters

      • msg: string

        The informational message to log.

      • OptionalextraFields: LogEventExtraFields

        Optional structured data to attach to the log event (e.g., context info, tags).

      Returns void

      ScriptError If any internal error occurs while sending the event to the appenders.

      • If no singleton was defined, it does lazy initialization with default configuration.
      • If no appender was defined, it does lazy initialization to ConsoleAppender.

    • If the list of appenders is not empty, removes the appender from the list.

      Parameters

      • appender: Appender

        The appender to remove.

      Returns void

      ScriptError If the singleton was not instantiated.

    • Resets the Logger history, i.e., state (errors, warnings, including the list of critical events). It doesn't reset the appenders.

      Returns void

      ScriptError If the singleton was not instantiated.

    • Sets the array of appenders with the input argument appenders.

      Parameters

      • appenders: Appender[]

        Array with all appenders to set.

      Returns void

      ScriptError If:

      • The singleton was not instantiated.
      • appenders is null or undefined, or contains null or undefined entries.
      • The appenders to add are not unique by appender class. See JSDoc from LoggerImpl.addAppender for more details.

    • Short version of the toString() which excludes the appenders details.

      Returns string

      Similar to toString, but showing the list of appenders name only.

      ScriptError If the singleton was not instantiated.

      LoggerImpl.toString for more details.

    • Returns string

      A string representation of the logger instance. toString() includes the logger's level, action, error count, warning count, and a list of appenders with their string representations.

      ScriptError If the singleton was not instantiated.

    • Sends a trace log message (with optional structured extra fields) to all appenders if the level allows it. The level has to be greater than or equal to LoggerImpl.LEVEL.TRACE to send this event to the appenders.

      Parameters

      • msg: string

        The trace message to log.

      • OptionalextraFields: LogEventExtraFields

        Optional structured data to attach to the log event (e.g., context info, tags).

      Returns void

      ScriptError If any internal error occurs while sending the event to the appenders.

      • If no singleton was defined, it does lazy initialization with default configuration.
      • If no appender was defined, it does lazy initialization to ConsoleAppender.

    • Sends a warning log message (with optional structured extra fields) to all appenders if the level allows it. The level has to be greater than or equal to LoggerImpl.LEVEL.WARN to send this event to the appenders. After the message is sent, it updates the warning counter.

      Parameters

      • msg: string

        The warning message to log.

      • OptionalextraFields: LogEventExtraFields

        Optional structured data to attach to the log event (e.g., context info, tags).

      Returns void

      ScriptError If:

      • Level is greater than LoggerImpl.LEVEL.ERROR and the action is LoggerImpl.ACTION.EXIT.
      • Any internal error occurs while sending the event to the appenders.
      • If no singleton was defined, it does lazy initialization with default configuration.
      • If no appender was defined, it does lazy initialization to ConsoleAppender.

    • Sets the singleton instance to null, useful for running different scenarios and testing purposes.

      Returns void

      Mainly intended for testing purposes. The state of the singleton will be lost. This method is available only in src folder, it is not deployed in dist folder (production). It doesn't set the appenders to null, so the appenders are not cleared.

      ScriptError If the singleton was not instantiated.

      // Testing how the logger works with default configuration, and then changing the configuration.
      // Since the class doesn't define setter methods to change the configuration, you can use
      // clearInstance to reset the singleton and instantiate it with different configuration.
      // Testing default configuration
      let logger = LoggerImpl.getInstance() // LEVEL: WARN, ACTION: EXIT
      logger.error("error event") // Output: "error event" and ScriptError
      // Now we want to test with the following configuration: LoggerImpl.LEVEL:WARN, LoggerImpl.ACTION:CONTINUE
      LoggerImpl.clearInstance() // Clear the singleton
      logger = LoggerImpl.getInstance(LoggerImpl.LEVEL.WARN, LoggerImpl.ACTION.CONTINUE)
      logger.error("error event") // Output: "error event" (no ScriptError was thrown)

    • Returns the label for a log action value.

      Parameters

      • Optionalaction: 0 | 1

        The log action to get the label for.

      Returns string

      The label for the action.

      • If action is undefined, returns the label for the current logger instance's action.
      • If neither is set, returns UNKNOWN.
      LoggerImpl.getActionLabel(LoggerImpl.ACTION.CONTINUE) // Returns "CONTINUE"
      LoggerImpl.getActionLabel() // Returns the current logger instance's action label

    • Returns the singleton Logger instance, creating it if it doesn't exist. If the Logger is created during this call, the provided level and action parameters initialize the log level and error-handling behavior.

      Parameters

      • level: number = LoggerImpl.DEFAULT_LEVEL

        The verbosity level (default: LoggerImpl.LEVEL.WARN). Controls verbosity. Sends events to the appenders up to the defined level of verbosity. The level of verbosity is incremental, except for value LoggerImpl.LEVEL.OFF, which suppresses all messages sent to the appenders. For example: LoggerImpl.LEVEL.INFO allows sending errors, warnings, and information events, but excludes trace events.

      • action: 0 | 1 = LoggerImpl.DEFAULT_ACTION

        The action on error/warning (default: LoggerImpl.ACTION.EXIT). Determines if the script should continue or abort. If the value is LoggerImpl.ACTION.EXIT, throws a ScriptError exception, i.e. aborts the Script. If the action is LoggerImpl.ACTION.CONTINUE, the script continues. It only takes effect if the level is not LoggerImpl.LEVEL.OFF.

      Returns LoggerImpl

      The singleton Logger instance.

      Subsequent calls ignore these parameters and return the existing instance.

      ScriptError If:

      • The level input value was not defined in LoggerImpl.LEVEL or it doesn't match the LOG_EVENT enum values in the specified order.
      • The action input value was not defined in LoggerImpl.ACTION.
      // Initialize logger at INFO level, continue on errors/warnings
      const logger = Logger.getInstance(LoggerImpl.LEVEL.INFO, LoggerImpl.ACTION.CONTINUE)
      // Subsequent calls ignore parameters, return the same instance
      const sameLogger = Logger.getInstance(LoggerImpl.LEVEL.ERROR, LoggerImpl.ACTION.EXIT)
      logger.info("Starting the Script") // Send this message to all appenders
      logger.trace("Step one")           // Doesn't send because of LoggerImpl.LEVEL value: INFO

    • Returns the label for the given log level.

      Parameters

      • Optionallevel: number

      Returns string

      The label for the log level.

      • If level is undefined, returns the label for the current logger instance's level.
      • If neither is set, returns UNKNOWN.
      LoggerImpl.getLevelLabel(LoggerImpl.LEVEL.INFO) // Returns "INFO"
      LoggerImpl.getLevelLabel() // Returns the current logger instance's level label

    Settings

    Member Visibility

    On This Page

    Properties
    Methods