officescripts-logging-framework
    Preparing search index...

    Interface Logger

    Represents a logging interface for capturing and managing log events at various levels. Provides methods for logging messages, querying log state, managing appenders, and exporting logger state. Implementations should ensure they should not maintain global mutable state outside the singleton and efficient log event handling.

    • Usually the LoggerImpl implementation should be implemented via singleton pattern.
    • LogEvent for the structure of log events.
    • Appender for the interface that handles sending log events to output channels.
    • LOG_EVENT for the enumeration of log event types.
    • Layout for the layout used to format log events before sending them to appenders.
    interface Logger {
        addAppender(appender: Appender): void;
        error(msg: string, extraFields?: object): void;
        exportState(): {
            action: string;
            criticalEvents: LogEvent[];
            errorCount: number;
            level: string;
            warningCount: number;
        };
        getAction(): number;
        getAppenders(): Appender[];
        getCriticalEvents(): LogEvent[];
        getErrCnt(): number;
        getLevel(): number;
        getWarnCnt(): number;
        hasCriticalEvents(): boolean;
        hasErrors(): boolean;
        hasWarnings(): boolean;
        info(msg: string, extraFields?: object): void;
        removeAppender(appender: Appender): void;
        reset(): void;
        setAppenders(appenders: Appender[]): void;
        toString(): string;
        trace(msg: string, extraFields?: object): void;
        warn(msg: string, extraFields?: object): void;
    }

    Implemented by

    Index

    Methods

    addAppender error exportState getAction getAppenders getCriticalEvents getErrCnt getLevel getWarnCnt hasCriticalEvents hasErrors hasWarnings info removeAppender reset setAppenders toString trace warn

    Methods

    • Adds a new appender to the logger.

      Parameters

      • appender: Appender

        The Appender instance to add.

      Returns void

      ScriptError if:

      • The singleton instance is not available (not instantiated).
      • The appender is null or undefined.
      • The appender is already registered in the logger.

      Logger.setAppenders for setting multiple appenders at once and for more details on the validation of the appenders.

    • Sends an error log event with the provided message and optional extraFields to all appenders.

      Parameters

      • msg: string

        The error message to log.

      • OptionalextraFields: object

        Optional structured data (object) to attach to the log event. May include metadata, context, etc.

      Returns void

      ScriptError if:

      • The singleton instance is not available (not instantiated)
      • The logger is configured to exit on critical events such as warnings and errors.

    • Exports the current state of the logger, including level, action, error/warning counts, and critical events (warnings and errors).

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

      An object containing the logger's state.

      ScriptError if the singleton instance is not available (not instantiated).

    • Gets the current action setting for error/warning events.

      Returns number

      The action value (e.g., CONTINUE or EXIT).

      ScriptError if the singleton instance is not available (not instantiated).

    • Gets the array of appenders currently registered with the logger.

      Returns Appender[]

      An array of Appender instances.

      ScriptError if the singleton instance is not available (not instantiated).

    • Gets an array of all error and warning log events sent.

      Returns LogEvent[]

      An array of LogEvent objects representing error and warning events.

      ScriptError if the singleton instance is not available (not instantiated).

    • Gets the total number of error log events sent.

      Returns number

      The count of error events.

      ScriptError if the singleton instance is not available (not instantiated).

    • Gets the current log level setting.

      Returns number

      The log level value (e.g., OFF, ERROR, WARN, INFO, TRACE). It refers to the level of verbosity to show during the logging process.

      ScriptError if the singleton instance is not available (not instantiated).

    • Gets the total number of warning log events sent.

      Returns number

      The count of warning events.

      ScriptError if the singleton instance is not available (not instantiated).

    • Checks if any error or warning log events have been sent.

      Returns boolean

      True if at least one error or warning event has been sent; otherwise, false.

      ScriptError if the singleton instance is not available (not instantiated).

    • Checks if any error log events have been sent.

      Returns boolean

      True if at least one error event has been sent; otherwise, false.

      ScriptError if the singleton instance is not available (not instantiated).

    • Checks if any warning log events have been sent.

      Returns boolean

      True if at least one warning event has been sent; otherwise, false.

      ScriptError if the singleton instance is not available (not instantiated).

    • Sends an informational log event with the provided message and optional extraFields to all appenders.

      Parameters

      • msg: string

        The informational message to log.

      • OptionalextraFields: object

        Optional structured data (object) to attach to the log event.

      Returns void

      ScriptError if the singleton instance is not available (not instantiated).

    • Removes an appender from the logger, if the resulting array of appenders appender is not empty.

      Parameters

      • appender: Appender

        The Appender instance to remove.

      Returns void

      ScriptError if the singleton instance is not available (not instantiated).

    • Clears the logger's history of error and warning events and resets counters.

      Returns void

      ScriptError if the singleton instance is not available (not instantiated).

    • Sets the array of appenders for the logger.

      Parameters

      • appenders: Appender[]

        The array of Appender instances to set.

      Returns void

      ScriptError if:

      • The singleton instance is not available (not instantiated).
      • The resulting array doesn't contain unique implementations of Appender.
      • appender is null or undefined or has null or undefined elements

    • Returns a string representation of the logger's state, including level, action, and message counts and appenders.

      Returns string

      A string describing the logger's current state.

      ScriptError if the singleton instance is not available (not instantiated).

    • Sends a trace log event with the provided message and optional extraFields to all appenders.

      Parameters

      • msg: string

        The trace message to log.

      • OptionalextraFields: object

        Optional structured data (object) to attach to the log event.

      Returns void

      ScriptError if the singleton instance is not available (not instantiated).

    • Sends a warning log event with the provided message and optional extraFields to all appenders.

      Parameters

      • msg: string

        The warning message to log.

      • OptionalextraFields: object

        Optional structured data (object) to attach to the log event.

      Returns void

      ScriptError if:

      • The singleton instance is not available (not instantiated)
      • The logger is configured to exit on critical events such as warnings and errors.

    Settings

    Member Visibility

    On This Page

    Methods