@itwin/core-bentley/lib/cjs/Logger.d.ts

Bentley JavaScript core components

/** @packageDocumentation
 * @module Logging
 */
import { BeEvent } from "./BeEvent";
import { LoggingMetaData } from "./BentleyError";
/** Defines the *signature* for a log function.
 * @public
 */
export type LogFunction = (category: string, message: string, metaData: LoggingMetaData) => void;
/** Use to categorize logging messages by severity.
 * @public
 */
export declare enum LogLevel {
    /** Tracing and debugging - low level */
    Trace = 0,
    /** Information - mid level */
    Info = 1,
    /** Warnings - high level */
    Warning = 2,
    /** Errors - highest level */
    Error = 3,
    /** Higher than any real logging level. This is used to turn a category off. */
    None = 4
}
/** Identifies a logging category and the LogLevel that should be used for it. The LogLevel is specified by its string name.
 * @public
 */
export interface LoggerCategoryAndLevel {
    category: string;
    logLevel: string;
}
/** Specifies logging levels, including the default logging level and a set of categories and levels for them.
 * @public
 */
export interface LoggerLevelsConfig {
    defaultLevel?: string;
    categoryLevels?: LoggerCategoryAndLevel[];
}
/** A global set of metadata that should be included with every log message.
 * You can provide an object representing the metadata, or a function to be invoked to obtain the metadata object each
 * time a message is logged.
 * Each key-value pair of the object will be stringified and combined with the log message's per-call metadata.
 * The keys you provide to each method is used solely to identify your entries so that you can later update or delete them - these keys
 * are **not** included in log messages. Don't modify or remove metadata associated with keys that belong to someone else.
 * @note Each extra bit of metadata adds cost and overhead to the logging system. Avoid adding unnecessary or unnecessarily verbose metadata.
 * @see [[Logger.staticMetaData]] to access the global metadata.
 * @beta
 */
export interface StaticLoggerMetaData {
    /** Add or update some metadata to be included with every logged message. */
    set(key: string, metadata: LoggingMetaData): void;
    /** Remove metadata previously [[set]] using the specified `key`, so it will no longer be included with every logged message. */
    delete(key: string): void;
}
/** Logger allows libraries and apps to report potentially useful information about operations, and it allows apps and users to control
 * how or if the logged information is displayed or collected. See [Learning about Logging]($docs/learning/common/Logging.md).
 * @public
 */
export declare class Logger {
    protected static _logError: LogFunction | undefined;
    protected static _logWarning: LogFunction | undefined;
    protected static _logInfo: LogFunction | undefined;
    protected static _logTrace: LogFunction | undefined;
    private static _onLogLevelChanged;
    private static _staticMetaData;
    /** An event raised whenever [[setLevel]] or [[setLevelDefault]] is called. */
    static get onLogLevelChanged(): BeEvent<() => void>;
    private static _categoryFilter;
    /** Maps category names to the least severe level at which messages in that category should be displayed,
     * or `undefined` if a minimum has not been defined.
     * @see [[setLevel]] to change the minimum logging level for a category.
     */
    static get categoryFilter(): Readonly<{
        [categoryName: string]: LogLevel | undefined;
    }>;
    private static _minLevel;
    /** The least severe level at which messages should be displayed by default.
     * @see [[setLevelDefault]] to change this default.
     * @see [[setLevel]] to override this default for specific categories.
     */
    static get minLevel(): LogLevel | undefined;
    /** Should the call stack be included when an exception is logged?  */
    static logExceptionCallstacks: boolean;
    /** Contains metadata that should be included with every logged message.
     * @beta
     */
    static get staticMetaData(): StaticLoggerMetaData;
    /** Initialize the logger streams. Should be called at application initialization time. */
    static initialize(logError?: LogFunction, logWarning?: LogFunction, logInfo?: LogFunction, logTrace?: LogFunction): void;
    /** Initialize the logger to output to the console. */
    static initializeToConsole(): void;
    /** merge the supplied metadata with all static metadata into one object */
    static getMetaData(metaData?: LoggingMetaData): object;
    /** stringify the metadata for a log message by merging the supplied metadata with all static metadata into one object that is then `JSON.stringify`ed. */
    static stringifyMetaData(metaData?: LoggingMetaData): string;
    /** Set the least severe level at which messages should be displayed by default. Call setLevel to override this default setting for specific categories. */
    static setLevelDefault(minLevel: LogLevel): void;
    /** Set the minimum logging level for the specified category. The minimum level is least severe level at which messages in the
     * specified category should be displayed.
     */
    static setLevel(category: string, minLevel: LogLevel): void;
    /** Interpret a string as the name of a LogLevel */
    static parseLogLevel(str: string): LogLevel;
    /** Set the log level for multiple categories at once. Also see [[validateProps]] */
    static configureLevels(cfg: LoggerLevelsConfig): void;
    private static isLogLevel;
    /** Check that the specified object is a valid LoggerLevelsConfig. This is useful when reading a config from a .json file. */
    static validateProps(config: any): void;
    /** Get the minimum logging level for the specified category. */
    static getLevel(category: string): LogLevel | undefined;
    /** Turns off the least severe level at which messages should be displayed by default.
     * This turns off logging for all messages for which no category minimum level is defined.
     */
    static turnOffLevelDefault(): void;
    /** Turns off all category level filters previously defined with [[Logger.setLevel]].
     */
    static turnOffCategories(): void;
    /** Check if messages in the specified category should be displayed at this level of severity. */
    static isEnabled(category: string, level: LogLevel): boolean;
    /** Log the specified message to the **error** stream.
     * @param category  The category of the message.
     * @param message  The message.
     * @param metaData  Optional data for the message
     */
    static logError(category: string, message: string, metaData?: LoggingMetaData): void;
    private static getExceptionMessage;
    /** Log the specified exception.
     * For legacy [[BentleyError]] exceptions, the special "exceptionType" property will be added as metadata. Otherwise, all enumerable members of the exception are logged as metadata.
     * @param category  The category of the message.
     * @param err  The exception object.
     * @param log The logger output function to use - defaults to Logger.logError
     */
    static logException(category: string, err: any, log?: LogFunction): void;
    /** Log the specified message to the **warning** stream.
     * @param category  The category of the message.
     * @param message  The message.
     * @param metaData  Optional data for the message
     */
    static logWarning(category: string, message: string, metaData?: LoggingMetaData): void;
    /** Log the specified message to the **info** stream.
     * @param category  The category of the message.
     * @param message  The message.
     * @param metaData  Optional data for the message
     */
    static logInfo(category: string, message: string, metaData?: LoggingMetaData): void;
    /** Log the specified message to the **trace** stream.
     * @param category  The category of the message.
     * @param message  The message.
     * @param metaData  Optional data for the message
     */
    static logTrace(category: string, message: string, metaData?: LoggingMetaData): void;
}
/** Simple performance diagnostics utility.
 * It measures the time from construction to disposal. On disposal it logs the routine name along with
 * the duration in milliseconds.
 * It also logs the routine name at construction time so that nested calls can be disambiguated.
 *
 * The timings are logged using the log category **Performance** and log severity [[LogLevel.INFO]].
 * Enable those, if you want to capture timings.
 * @public
 */
export declare class PerfLogger implements Disposable {
    private static _severity;
    private _operation;
    private _metaData?;
    private _startTimeStamp;
    constructor(operation: string, metaData?: LoggingMetaData);
    private logMessage;
    [Symbol.dispose](): void;
    /** @deprecated in 5.0 - will not be removed until after 2026-06-13. Use [Symbol.dispose] instead. */
    dispose(): void;
}
//# sourceMappingURL=Logger.d.ts.map