272 lines
9.3 KiB
TypeScript
272 lines
9.3 KiB
TypeScript
/// <reference types="node" />
|
|
import { ConsoleHandler, OutputHandler, SyslogHandler } from './output-handlers';
|
|
import { formatItem } from './utils';
|
|
import { Level, LoggingConfig, Output, OutputPerNamespace } from './types';
|
|
import LogOutputs from './LogOutputs';
|
|
import events = require('events');
|
|
/**
|
|
* Log class - centralized logging facility
|
|
* @class Log
|
|
* @param {string} [namespace=''] The namespace to log to
|
|
* @param {Log} [parent] The log parent (prepended to the namespace)
|
|
*/
|
|
declare class Log {
|
|
/**
|
|
* Current version of the library.
|
|
* @static
|
|
* @readonly
|
|
* @name Log.version
|
|
* @type {string}
|
|
*/
|
|
static readonly version: string;
|
|
/**
|
|
* The global logger, with empty namespace
|
|
* @static
|
|
* @readonly
|
|
* @name Log.global
|
|
* @type {string}
|
|
*/
|
|
static readonly global: Log;
|
|
/**
|
|
* Current version of the Jibo platform release.
|
|
* Can be overridden, for instance to be the version of a cloud skill
|
|
* instead of a robot
|
|
* @static
|
|
* @name Log.release
|
|
* @type {string}
|
|
*/
|
|
static release: string;
|
|
/**
|
|
* Name of the currently running process, sent to syslog in the ProcessName
|
|
* header; should be set by each process during its initialization
|
|
* @static
|
|
* @name Log.processName
|
|
* @type {string}
|
|
*/
|
|
static processName: string;
|
|
/**
|
|
* The top-level namespace, added to the front of the namespace in
|
|
* syslog and file output; should be set by each process during its
|
|
* initialization
|
|
* @static
|
|
* @name Log.topLevelNamespace
|
|
* @type {string}
|
|
*/
|
|
static topLevelNamespace: string;
|
|
/**
|
|
* The level of each output channel of the global logger
|
|
* @static
|
|
* @readonly
|
|
* @name Log.outputs
|
|
* @type {LogOutputs}
|
|
*/
|
|
static readonly outputs: LogOutputs;
|
|
private static _jiboLog;
|
|
private static _initialized;
|
|
private static _skipLocalConfig;
|
|
private static _staticNamespaceLevels;
|
|
private static _outputPerNamespace;
|
|
private static _outputHandlers;
|
|
private static _unhandledExceptionLogger;
|
|
private static _uncaughtMap;
|
|
private static _localConfigPath;
|
|
private static _globalErrorHandler;
|
|
private static _localConfig;
|
|
/**
|
|
* The namespace of this logger instance
|
|
* @readonly
|
|
* @name Log#namespace
|
|
* @type {string}
|
|
*/
|
|
readonly namespace: string;
|
|
/**
|
|
* The robot ID, defaulting to the hostname of the current machine
|
|
* It is useful to have this public, so a cloud process can set the
|
|
* robot ID based on the robot credentials provided upon connection
|
|
* @name Log#robotID
|
|
* @type {string}
|
|
*/
|
|
robotID: string;
|
|
/**
|
|
* For Pegasus logging, each cloud call from a robot includes this ID,
|
|
* so the entire transaction can be traced from robot, to Pegasus, and
|
|
* back to the robot
|
|
* @name Log#transID
|
|
* @type {string}
|
|
*/
|
|
transID: string;
|
|
private _outputPerNamespace;
|
|
/**
|
|
* Load the default logging configuration statically
|
|
* @static
|
|
* @method Log.initialize
|
|
* @return {Promise<void>}
|
|
*/
|
|
static initialize(): Promise<void>;
|
|
/**
|
|
* Add an output handler to jibo-log
|
|
* @method Log.addOutputHandler
|
|
* @param {string} name The name of the output channel
|
|
* @param {OutputHandler<Config extends Object>} handler The handler to add
|
|
*/
|
|
static addOutputHandler<Config extends Object>(name: string, handler: OutputHandler<Config>): void;
|
|
/**
|
|
* Set the logging configuration from input (e.g. parsed from JSON file)
|
|
* @static
|
|
* @method Log.loadConfig
|
|
* @param {LoggingConfig} loggingConfig The configuration to load
|
|
* @return {Promise<void>}
|
|
*/
|
|
static loadConfig(loggingConfig: LoggingConfig): Promise<void>;
|
|
/**
|
|
* Generate LoggingConfig for output (e.g. to stringify to JSON file)
|
|
* @static
|
|
* @method Log.getConfig
|
|
* @return {LoggingConfig}
|
|
*/
|
|
static getConfig(): LoggingConfig;
|
|
/**
|
|
* Save the current log configuration file to a local logging config file
|
|
* If process.env.JIBO_LOG_CONFIG: use that; else...
|
|
* On-robot: /var/jibo/t.logging.json
|
|
* Off-robot: ~/.jibo/t.logging.json
|
|
* @static
|
|
* @method Log.saveConfig
|
|
* @return {Promise<void>}
|
|
*/
|
|
static saveConfig(): Promise<void>;
|
|
/**
|
|
* Set up listener for log-level update notifications
|
|
* @static
|
|
* @method Log.handleLogLevelNotifications
|
|
* @param {events.EventEmitter} notificationsDispatcher Event emitter that emits 'LevelChanged' events
|
|
* @param {boolean} [save = false] Whether to save the configuration to disk or not
|
|
* @return {Promise<void>}
|
|
*/
|
|
static handleLogLevelNotifications(notificationsDispatcher: events.EventEmitter, save?: boolean): Promise<void>;
|
|
/**
|
|
* Flush all log lines that output channels may have cached in memory
|
|
* @static
|
|
* @method Log.flush
|
|
* @return {void}
|
|
*/
|
|
static flush(): void;
|
|
private static readonly _onRobot;
|
|
private static _loadConfig(loggingConfig);
|
|
private static _loadLocalConfig();
|
|
private static _loadLocalConfigOnRobot();
|
|
private static _loadLocalConfigOffRobot();
|
|
private static _parentNamespace(namespace);
|
|
/**
|
|
* Whether or not to log globally uncaught exceptions
|
|
* @static
|
|
* @name Log.logUncaughtExceptions
|
|
* @type {boolean}
|
|
*/
|
|
static logUncaughtExceptions: boolean;
|
|
/**
|
|
* Whether or not to log globally unhandled promise rejections
|
|
* @static
|
|
* @name Log.logUnhandledRejections
|
|
* @type {boolean}
|
|
*/
|
|
static logUnhandledRejections: boolean;
|
|
private static _levelGreaterOrEqual(levelOne, levelTwo);
|
|
constructor(namespace?: string, parent?: Log);
|
|
/**
|
|
* A reference to the top level logger instance with namespace ''
|
|
* @name Log#global
|
|
* @type {Log}
|
|
*/
|
|
readonly global: Log;
|
|
/**
|
|
* Configuration for the output of this logger
|
|
* @readonly
|
|
* @name Log#outputs
|
|
* @type {LogOutputs}
|
|
*/
|
|
readonly outputs: LogOutputs;
|
|
/**
|
|
* Creates a new Log instance with namespace `this.namespace + '/' +
|
|
* subNamespace`
|
|
* @method Log#createChild
|
|
* @param {string} subNamespace New namespace which will be appended to
|
|
* the parent namespace
|
|
* @return {Log}
|
|
*/
|
|
createChild(subNamespace: string): Log;
|
|
outputPerNamespace: OutputPerNamespace;
|
|
/**
|
|
* Set the minimum logging level for a given output for this namespace
|
|
* This is generally not invoked directly, but by LogOutputs by setting
|
|
* one of the properties of the outputs property of a log instance
|
|
* e.g. `log.outputs.console = 'debug';`
|
|
* @method Log#setLevelForOutput
|
|
* @param {Output} output The output for which to set the level
|
|
* @param {Level} level The level to which to set the output
|
|
* @return {void}
|
|
*/
|
|
setLevelForOutput(output: Output, level: Level): void;
|
|
/**
|
|
* Check minimum logging level for each output channel for this log's
|
|
* namespace, and log the message if this level is debug or lower
|
|
* @method Log#debug
|
|
* @param {any[]} ...args The arguments to log
|
|
* @return {Log} Instance of log for chaining
|
|
*/
|
|
debug(...args: any[]): Log;
|
|
/**
|
|
* Check minimum logging level for each output channel for this log's
|
|
* namespace, and log the message if this level is info or lower
|
|
* @method Log#info
|
|
* @param {any[]} ...args The arguments to log
|
|
* @return {Log} Instance of log for chaining
|
|
*/
|
|
info(...args: any[]): Log;
|
|
/**
|
|
* Check minimum logging level for each output channel for this log's
|
|
* namespace, and log the message if this level is warn or lower
|
|
* @method Log#warn
|
|
* @param {any[]} ...args The arguments to log
|
|
* @return {Log} Instance of log for chaining
|
|
*/
|
|
warn(...args: any[]): Log;
|
|
/**
|
|
* Check minimum logging level for each output channel for this log's
|
|
* namespace, and log the message if this level isn't none
|
|
* @method Log#error
|
|
* @param {any[]} ...args The arguments to log
|
|
* @return {Log} Instance of log for chaining
|
|
*/
|
|
error(...args: any[]): Log;
|
|
/**
|
|
* A synonym for Log#debug
|
|
* @method Log#log
|
|
* @param {any[]} ...args The arguments to log
|
|
* @return {Log} Instance of log for chaining
|
|
*/
|
|
log(...args: any[]): Log;
|
|
/**
|
|
* Log the error if it is set
|
|
* @method Log#iferr
|
|
* @param {Error|String} err The error which is checked and logged if
|
|
* truthy
|
|
* @param {any[]} [...args] Additional arguments to log along with err
|
|
* @return {Log} Instance of log for chaining
|
|
*/
|
|
iferr(err: any, ...args: any[]): Log;
|
|
/**
|
|
* Get the minimum logging level for the given output for this namespace.
|
|
* If a level isn't set for the namespace, it checks its parent namespace
|
|
* and so on until it finds one, or uses the global namespace.
|
|
* @method Log#getLevelForOutput
|
|
* @param {Output} output The output channel for which to get the level
|
|
*/
|
|
getLevelForOutput(output: Output): Level;
|
|
private _log(level, ...args);
|
|
static formatItem: typeof formatItem;
|
|
static ConsoleHandler: typeof ConsoleHandler;
|
|
static SyslogHandler: typeof SyslogHandler;
|
|
}
|
|
export default Log;
|