ionic-logging-service/types/ionic-logging-service.d.ts

Logging functionalities for apps built with Ionic framework

import * as i0 from '@angular/core';
import { Signal } from '@angular/core';
import * as log4javascript from 'log4javascript';

/**
 * Configuration for AjaxAppender.
 */
interface AjaxAppenderConfiguration {
    /**
     * Url to send JavaScript logs
     */
    url: string;
    /**
     * Specifies whether cookies should be sent with each request.
     *
     * Default: false.
     */
    withCredentials?: boolean;
    /**
     * Number of log messages sent in each request.
     *
     * Default: 1.
     */
    batchSize?: number;
    /**
     * Interval for sending log messages (in milliseconds).
     *
     * If set to 0, every message will be sent immediatedly.
     *
     * Default: 0.
     */
    timerInterval?: number;
    /**
     * Threshold.
     *
     * Valid values are: ALL, DEBUG, ERROR, FATAL, INFO, OFF, TRACE, WARN
     *
     * Default: WARN.
     */
    threshold?: string;
}

/**
 * An appender which sends the log messages to a server via HTTP.
 *
 * A typical configuration could be:
 *
 * ```json
 * {
 *   "url": "https://my.backend.xy/LoggingBackend",
 *   "batchSize": 10,
 *   "timerInterval": 60000,
 *   "threshold": "INFO"
 * }
 * ```
 */
declare class AjaxAppender extends log4javascript.Appender {
    private static batchSizeDefault;
    private static timerIntervalDefault;
    private static thresholdDefault;
    private ajaxAppender;
    private url;
    private withCredentials;
    private lastFailure;
    /**
     * Creates a new instance of the appender.
     *
     * @param configuration configuration for the appender.
     */
    constructor(configuration: AjaxAppenderConfiguration);
    /**
     * Configures the logging depending on the given configuration.
     *
     * Only the defined properties get overwritten.
     * Neither url nor withCredentials can be modified.
     *
     * @param configuration configuration data.
     */
    configure(configuration: AjaxAppenderConfiguration): void;
    /**
     * Appender-specific method to append a log message.
     *
     * @param loggingEvent event to be appended.
     */
    append(loggingEvent: log4javascript.LoggingEvent): void;
    /**
     * Gets the appender's name.
     * Mainly for unit testing purposes.
     *
     * @return appender's name
     */
    toString(): string;
    /**
     * Get the internally used appender.
     * Mainly for unit testing purposes.
     */
    getInternalAppender(): log4javascript.AjaxAppender;
    /**
     * Returns the number of log messages sent in each request.
     */
    getBatchSize(): number;
    /**
     * Sets the number of log messages to send in each request.
     *
     * @param batchSize new batch size
     */
    setBatchSize(batchSize: number): void;
    /**
     * Returns the appender's layout.
     */
    getLayout(): log4javascript.Layout;
    /**
     * Sets the appender's layout.
     */
    setLayout(layout: log4javascript.Layout): void;
    /**
     * Returns the length of time in milliseconds between each sending of queued log messages.
     */
    getTimerInterval(): number;
    /**
     * Sets the length of time in milliseconds between each sending of queued log messages.
     *
     * @param timerInterval new timer interval
     */
    setTimerInterval(timerInterval: number): void;
    /**
     * Last error message when the appender could not send log messages to the server.
     * @returns error message
     */
    getLastFailure(): Signal<string | undefined>;
}

/**
 * Configuration for BrowserConsoleAppender.
 */
interface BrowserConsoleAppenderConfiguration {
    /**
     * Threshold.
     *
     * Valid values are: ALL, DEBUG, ERROR, FATAL, INFO, OFF, TRACE, WARN
     *
     * Default: DEBUG.
     */
    threshold?: string;
}

/**
 * Configuration for LocalStorageAppender.
 */
interface LocalStorageAppenderConfiguration {
    /**
     * Key which is used to store the messages in the local storage.
     */
    localStorageKey: string;
    /**
     * Maximum number of log messages stored by the appender.
     *
     * Default: 250.
     */
    maxMessages?: number;
    /**
     * Threshold.
     *
     * Valid values are: ALL, DEBUG, ERROR, FATAL, INFO, OFF, TRACE, WARN
     *
     * Default: WARN.
     */
    threshold?: string;
}

/**
 * Log message.
 */
interface LogMessage {
    /**
     * Time when the log was written.
     */
    timeStamp: Date;
    /**
     * Log level.
     */
    level: string;
    /**
     * Name of the logger.
     */
    logger: string | undefined;
    /**
     * Method, in which the message was written.
     */
    methodName: string;
    /**
     * Message.
     */
    message: string[];
}

/**
 * An appender which stores the log messages in the browser's local storage.
 *
 * The messages are saved JSON-serialized.
 * You have to configure which key is used for storing the messages.
 *
 * A typical configuration could be:
 *
 * ```json
 * {
 *   "localStorageKey": "myLogs",
 *   "maxMessages": 500,
 *   "threshold": "INFO"
 * }
 * ```
 */
declare class LocalStorageAppender extends log4javascript.Appender {
    private static maxMessagesDefault;
    private static thresholdDefault;
    private maxMessages;
    private localStorageKey;
    private logMessages;
    /**
     * Creates a new instance of the appender.
     *
     * @param configuration configuration for the appender.
     */
    constructor(configuration: LocalStorageAppenderConfiguration);
    /**
     * Load log messages from local storage which are stored there under the given key.
     *
     * @param localStorageKey local storage key
     * @return stored messages
     */
    static loadLogMessages(localStorageKey: string): LogMessage[];
    /**
     * Remove log messages from local storage which are stored there under the given key.
     *
     * @param localStorageKey local storage key
     */
    static removeLogMessages(localStorageKey: string): void;
    /**
     * Configures the logging depending on the given configuration.
     *
     * Only the defined properties get overwritten.
     * The localStorageKey cannot be modified.
     *
     * @param configuration configuration data.
     */
    configure(configuration: LocalStorageAppenderConfiguration): void;
    /**
     * Appender-specific method to append a log message.
     *
     * @param loggingEvent event to be appended.
     */
    append(loggingEvent: log4javascript.LoggingEvent): void;
    /**
     * Gets the appender's name.
     * Mainly for unit testing purposes.
     *
     * @return appender's name
     */
    toString(): string;
    /**
     * Get the key which is used to store the messages in the local storage.
     */
    getLocalStorageKey(): string;
    /**
     * Get the maximum number of messages which will be stored in local storage.
     */
    getMaxMessages(): number;
    /**
     * Set the maximum number of messages which will be stored in local storage.
     *
     * If the appender stores currently more messages than the new value allows, the oldest messages get removed.
     *
     * @param value new maximum number
     */
    setMaxMessages(value: number): void;
    /**
     * Gets all messages stored in local storage.
     * Mainly for unit testing purposes.
     *
     * @return stored messages
     */
    getLogMessages(): LogMessage[];
    /**
     * Removes all messages from local storage.
     * Mainly for unit testing purposes.
     */
    clearLog(): void;
}

/**
 * Logging levels.
 */
declare enum LogLevel {
    /**
     * All events should be logged.
     */
    ALL = 0,
    /**
     * A fine-grained debug message, typically capturing the flow through the application.
     */
    TRACE = 1,
    /**
     * A general debugging event.
     */
    DEBUG = 2,
    /**
     * An event for informational purposes.
     */
    INFO = 3,
    /**
     * An event that might possible lead to an error.
     */
    WARN = 4,
    /**
     * An error in the application, possibly recoverable.
     */
    ERROR = 5,
    /**
     * A severe error that will prevent the application from continuing.
     */
    FATAL = 6,
    /**
     * No events will be logged.
     */
    OFF = 7
}

/**
 * Helper class for converting log levels from and to different data type.
 */
declare class LogLevelConverter {
    /**
     * Converts log4javascript.Level to internal LogLevel.
     *
     * @param level log4javascript's data type
     * @return internal data type.
     */
    static levelFromLog4Javascript(level: log4javascript.Level): LogLevel;
    /**
     * Converts string representation to internal LogLevel.
     *
     * @param level string representation
     * @return internal data type.
     */
    static levelFromString(level: string): LogLevel;
    /**
     * Converts internal LogLevel to log4javascript.Level.
     *
     * @param internal data type.
     * @return level log4javascript's data type
     */
    static levelToLog4Javascript(level: LogLevel): log4javascript.Level;
}

/**
 * Logger for writing log messages.
 */
declare class Logger {
    private logger;
    /**
     * Creates a new instance of a logger.
     */
    constructor(logger?: string | any);
    /**
     * Get the log level.
     */
    getLogLevel(): LogLevel;
    /**
     * Set the log level.
     *
     * @param level the new log level
     */
    setLogLevel(level: LogLevel): void;
    /**
     * Logs a message at level TRACE.
     *
     * @param methodName name of the method
     * @param params optional parameters to be logged; objects will be formatted as JSON
     */
    trace(methodName: string, ...params: any[]): void;
    /**
     * Logs a message at level DEBUG.
     *
     * @param methodName name of the method
     * @param params optional parameters to be logged; objects will be formatted as JSON
     */
    debug(methodName: string, ...params: any[]): void;
    /**
     * Logs a message at level INFO.
     *
     * @param methodName name of the method
     * @param params optional parameters to be logged; objects will be formatted as JSON
     */
    info(methodName: string, ...params: any[]): void;
    /**
     * Logs a message at level WARN.
     *
     * @param methodName name of the method
     * @param params optional parameters to be logged; objects will be formatted as JSON
     */
    warn(methodName: string, ...params: any[]): void;
    /**
     * Logs a message at level ERROR.
     *
     * @param methodName name of the method
     * @param params optional parameters to be logged; objects will be formatted as JSON
     */
    error(methodName: string, ...params: any[]): void;
    /**
     * Logs a message at level FATAL.
     *
     * @param methodName name of the method
     * @param params optional parameters to be logged; objects will be formatted as JSON
     */
    fatal(methodName: string, ...params: any[]): void;
    /**
     * Logs the entry into a method.
     * The method name will be logged at level INFO, the parameters at level DEBUG.
     *
     * @param methodName name of the method
     * @param params optional parameters to be logged; objects will be formatted as JSON
     */
    entry(methodName: string, ...params: any[]): void;
    /**
     * Logs the exit of a method.
     * The method name will be logged at level INFO, the parameters at level DEBUG.
     *
     * @param methodName name of the method
     * @param params optional parameters to be logged; objects will be formatted as JSON
     */
    exit(methodName: string, ...params: any[]): void;
    /**
     * Formats the given argument.
     */
    formatArgument(arg: any): string;
    /**
     * Returns the internal Logger (for unit tests only).
     */
    getInternalLogger(): log4javascript.Logger;
}

/**
 * Configuration for MemoryAppender.
 */
interface MemoryAppenderConfiguration {
    /**
     * Maximum number of log messages stored by the appender.
     *
     * Default: 250.
     */
    maxMessages?: number;
    /**
     * Threshold.
     *
     * Valid values are: ALL, DEBUG, ERROR, FATAL, INFO, OFF, TRACE, WARN.
     *
     * Default: ALL.
     */
    threshold?: string;
}

/**
 * Partial configuration definition for LoggingService.
 */
interface LoggingServiceConfiguration {
    /**
     * Log levels for different loggers.
     * Default: root: WARN
     */
    logLevels?: {
        /**
         * Logger name or "root" for root logger.
         */
        loggerName: string;
        /**
         * Log level.
         * Valid values are: ALL, DEBUG, ERROR, FATAL, INFO, OFF, TRACE, WARN
         */
        logLevel: string;
    }[];
    /**
     * Settings for AjaxAppender.
     */
    ajaxAppender?: AjaxAppenderConfiguration;
    /**
     * Settings for LocalStorageAppender.
     */
    localStorageAppender?: LocalStorageAppenderConfiguration;
    /**
     * Settings for MemoryAppender.
     */
    memoryAppender?: MemoryAppenderConfiguration;
    /**
     * Settings for BrowserConsoleAppender.
     */
    browserConsoleAppender?: BrowserConsoleAppenderConfiguration;
}

/**
 * Service for logging functionality.
 *
 * By default, the following settings are used:
 *  - logger: root with level WARN
 *  - appender: BrowserConsoleAppender with threshold DEBUG and MemoryAppender with threshold ALL
 *
 * Via [configure](#configure), it is possible to amend these settings.
 */
declare class LoggingService {
    private memoryAppender;
    private browserConsoleAppender;
    private ajaxAppender;
    /**
     * Creates a new instance of the service.
     */
    constructor();
    /**
     * Configures the logging depending on the given configuration.
     *
     * @param configuration configuration data.
     */
    configure(configuration?: LoggingServiceConfiguration): void;
    /**
     * Gets the root logger from which all other loggers derive.
     *
     * @return root logger
     */
    getRootLogger(): Logger;
    /**
     * Gets a logger with the specified name, creating it if a logger with that name does not already exist.
     *
     * @param loggerName name of the logger
     * @return logger
     */
    getLogger(loggerName: string): Logger;
    /**
     * Gets the last log messages.
     *
     * The log messages are retrieved from the internal [MemoryAppender](../memoryappender.html).
     * That means you will get only the most current messages. The number of the messages is limited
     * by its maxMessages value.
     *
     * @return log messages
     */
    getLogMessages(): Signal<LogMessage[]>;
    /**
     * Loads the log messages written by the LocalStorageAppender with the given key.
     *
     * @param localStorageKey key for the local storage
     * @returns log messages
     */
    getLogMessagesFromLocalStorage(localStorageKey: string): LogMessage[];
    /**
     * Remove all log messages.
     */
    removeLogMessages(): void;
    /**
     * Removes the log messages written by the LocalStorageAppender with the given key.
     *
     * @param localStorageKey key for the local storage
     */
    removeLogMessagesFromLocalStorage(localStorageKey: string): void;
    /**
     * Error messages when the ajax appender could not send log messages to the server.
     * @returns error messages
     */
    getLastAjaxAppenderFailure(): Signal<string | undefined>;
    static ɵfac: i0.ɵɵFactoryDeclaration<LoggingService, never>;
    static ɵprov: i0.ɵɵInjectableDeclaration<LoggingService>;
}

/**
 * An appender which stores the log messages in the browser's memory.
 *
 * The MemoryAppender is enabled by default.
 * If you do not specify anything else, it is using this configuration:
 *
 * ```JSON
 * {
 *   "memoryAppender": [
 *     {
 *       "maxMessages": 250,
 *       "threshold": "ALL"
 *     }
 * }
 * ```
 */
declare class MemoryAppender extends log4javascript.Appender {
    private static maxMessagesDefault;
    private static thresholdDefault;
    private maxMessages;
    private logMessages;
    /**
     * Creates a new instance of the appender.
     *
     * @param configuration configuration for the appender.
     */
    constructor(configuration?: MemoryAppenderConfiguration);
    /**
     * Configures the logging depending on the given configuration.
     * Only the defined properties get overwritten.
     *
     * @param configuration configuration data.
     */
    configure(configuration: MemoryAppenderConfiguration): void;
    /**
     * Appender-specific method to append a log message.
     *
     * @param loggingEvent event to be appended.
     */
    append(loggingEvent: log4javascript.LoggingEvent): void;
    /**
     * Gets the appender's name.
     * Mainly for unit testing purposes.
     *
     * @return appender's name
     */
    toString(): string;
    /**
     * Get the maximum number of messages which will be stored in memory.
     */
    getMaxMessages(): number;
    /**
     * Set the maximum number of messages which will be stored in memory.
     *
     * If the appender stores currently more messages than the new value allows, the oldest messages get removed.
     *
     * @param value new maximum number
     */
    setMaxMessages(value: number): void;
    /**
     * Gets all messages stored in memory.
     *
     * @return stored messages
     */
    getLogMessages(): Signal<LogMessage[]>;
    /**
     * Remove all messages stored in memory.
     */
    removeLogMessages(): void;
}

export { AjaxAppender, LocalStorageAppender, LogLevel, LogLevelConverter, Logger, LoggingService, MemoryAppender };
export type { AjaxAppenderConfiguration, BrowserConsoleAppenderConfiguration, LocalStorageAppenderConfiguration, LogMessage, LoggingServiceConfiguration, MemoryAppenderConfiguration };