pylogging/API.md at master · royalpinto/pylogging

Classes

A LogRecord instance represents an event being logged. LogRecord instances are created every time something is logged. They contain all the information pertinent to the event being logged. The main information passed in is in msg and args, which are combined using util.format to create the message field of the record. The record also includes information such as when the record was created, the stack trace where logging call was made, and any exception information to be logged.

Filter

Filter instances are used to perform arbitrary filtering of LogRecords. Loggers and Handlers can optionally use Filter instances to filter records as desired. The base filter class only allows events which are below a certain point in the logger hierarchy. For example, a filter initialized with "A.B" will allow events logged by loggers "A.B", "A.B.C", "A.B.C.D", "A.B.D" etc. but not "A.BB", "B.A.B" etc. If initialized with the empty string, all events are passed

Filterer

A base class for Loggers and Handlers for managing the filters.

Handler ⇐ Filterer

Handler instances dispatch logging events to specific destinations.

The base handler class Handler, acts as a placeholder which defines the Handler interface. Handlers can optionally use Formatter instances to format records as desired. By default, no formatter is specified; in this case, the 'raw' message as determined by record.getMessage() is logged.

Logger ⇐ Filterer

Instances of the Logger class represent a single logging channel. A "logging channel" indicates an area of an application. Exactly how an "area" is defined is up to the application developer. Since an application can have any number of areas, logging channels are identified by a unique string. Application areas can be nested (e.g. an area of "input processing" might include sub-areas "read CSV files", "read XLS files" and "read Gnumeric files"). To cater for this natural nesting, channel names are organized into a namespace hierarchy where levels are separated by periods, much like the Java or Python package namespace. So in the instance given above, channel names might be "input" for the upper level, and "input.csv", "input.xls" and "input.gnu" for the sub-levels. There is no arbitrary limit to the depth of nesting.

ConsoleHandler ⇐ Handler

A handler which writes log records to stdout/stderr.

Formatter

Formatter instances are used to convert a LogRecord to text. Formatters need to know how a LogRecord is constructed. They are responsible for converting a LogRecord to (usually) a string which can be interpreted by either a human or an external system. The base Formatter allows a formatting string to be specified. If none is supplied, the default formatting string "%(levelname)s:%(name)s:%(message)s\n" is used. Currently, the useful attributes in a LogRecord are described by:

   %(name)s            Name of the logger (logging channel)
   %(level)s           Numeric logging level for the message (DEBUG, INFO,
                       WARN, ERROR, CRITICAL)
   %(levelname)s       Text logging level for the message ("DEBUG", "INFO",
                       "WARN", "ERROR", "EXCEPTION", "CRITICAL")
   %(created)f         Time when the LogRecord was created (time.time()
                       return value)
   %(asctime)s         Textual time when the LogRecord was created
   %(process)d         Process ID (if available)
   %(message)s         The result of record.getMessage(), computed just as
                       the record is emitted
   %(trace)s           The stack trace where logging call was made
NOTE: filename, lineno, modulename, and funcName are not available in this version,
and to fetch these, trace need to parsed by the developer.

Members

CRITICAL: Log level CRITICAL with numeric value 50.
FATAL: Log level FATAL with numeric value same as of CRITICAL.
ERROR: Log level ERROR with numeric value 40.
EXCEPTION: Log level EXCEPTION with numeric value same as of ERROR.
WARN: Log level WARN with numeric value 30.
WARNING: Log level WARNING and is same as WARN.
INFO: Log level INFO with numeric value 20.
DEBUG: Log level DEBUG with numeric value 10.
NOTSET: Log level NOTSET with numeric value 0.

Functions

setLoggerClass(klass): Set the logger class inherited from Logger. This is usefull incase developer wants to use a custom logger class. However this custom class should be inherited from Logger class.
setLogRecordClass(klass): Set the log record class inherited from LogRecord. This is usefull incase developer wants to use a custom log record class. However this custom class should be inherited from LogRecord class.
getLogger([name]) ⇒ Logger: Get logger instance for the given logger name. All calls to this function with a given name return the same logger instance. This means that logger instances never need to be passed between different parts of an application.

LogRecord

Kind: global class

LogRecord
- new LogRecord(name, level, levelname, msg, [args], [trace])
- .getMessage() ⇒ string

new LogRecord(name, level, levelname, msg, [args], [trace])

Initialize a logging record with interesting information.

Param	Type	Description
name	`string`	the logger name.
level	`int`	log level number.
levelname	`int`	log level name.
msg	`string`	the log message.
[args]	`args`	the arguments to be applied on the msg.
[trace]	`string`	the stack trace.

logRecord.getMessage() ⇒ `string`

Return the message for this LogRecord after merging any user-supplied arguments with the message.

Kind: instance method of LogRecord
Returns: string - the formatted message.

Filter

Kind: global class

Filter
- new Filter([name])
- .filter(record) ⇒ boolean

new Filter([name])

Initialize a filter.

Initialize with the name of the logger which, together with its children, will have its events allowed through the filter. If no name is specified, allow every event.

Param	Type	Description
[name]	`string`	the logger name.

filter.filter(record) ⇒ `boolean`

Determine if the specified record is to be logged.

Kind: instance method of Filter
Returns: boolean - Is the specified record to be logged? Returns false for no, true for yes.

Param	Type	Description
record	`LogRecord`	the log record.

Filterer

A base class for Loggers and Handlers for managing the filters.

Kind: global class

Filterer
- new Filterer()
- .addFilter(filter)
- .removeFilter(filter)
- .filter(record) ⇒ boolean

new Filterer()

Initialize the list of filters to be an empty list.

filterer.addFilter(filter)

Add the specified filter to this handler/logger.

Kind: instance method of Filterer

Param	Type	Description
filter	`Filter`	the filter instance.

filterer.removeFilter(filter)

Remove the specified filter from this handler/logger.

Kind: instance method of Filterer

Param	Type	Description
filter	`Filter`	the filter instance.

filterer.filter(record) ⇒ `boolean`

Determine if a record is loggable by consulting all the filters. The default is to allow the record to be logged; any filter can veto this and the record is then dropped.

Kind: instance method of Filterer
Returns: boolean - false if a record is to be dropped, else true.

Param	Type	Description
record	`LogRecord`	the log record.

Handler ⇐ `Filterer`

Handler instances dispatch logging events to specific destinations.

Kind: global class
Extends: Filterer

Handler ⇐ Filterer
- new Handler([level])
- .getName() ⇒ string
- .setLevel(level)
- .setFormatter(formatter)
- .format(record, fmt) ⇒ string
- .emit(record)
- .handle(record) ⇒ boolean
- .flush()
- .close()
- .handleError(record)
- .addFilter(filter)
- .removeFilter(filter)
- .filter(record) ⇒ boolean

new Handler([level])

Initializes the instance - basically setting the formatter to None and the filter list to empty.

Param	Type	Default	Description
[level]	`integer`	`NOTSET`	the log level.

handler.getName() ⇒ `string`

Get the logger name.

Kind: instance method of Handler
Returns: string - the logger name.

handler.setLevel(level)

Set the logging level of this handler.

Kind: instance method of Handler

Param	Type	Description
level	`integer` \| `string`	the log level.

handler.setFormatter(formatter)

Set the formatter for this handler.

Kind: instance method of Handler

Param	Type	Description
formatter	`Formatter`	the formatter instance.

handler.format(record, fmt) ⇒ `string`

Format the specified record. If a formatter is set, use it. Otherwise, return record.getMessage()

Kind: instance method of Handler
Returns: string - formatted message.

Param	Type	Description
record	`LogRecord`	the log record.
fmt	`string`	optional fmt to be used instead of the default one.

handler.emit(record)

Do whatever it takes to actually log the specified logging record. This version is intended to be implemented by subclasses and so throws a Not implemented Error.

Kind: instance method of Handler

Param	Type	Description
record	`LogRecord`	the log record.

handler.handle(record) ⇒ `boolean`

Conditionally emit the specified logging record.

Emission depends on filters which may have been added to the handler.

Kind: instance method of Handler
Returns: boolean - whether the filter passed the record for emission.

Param	Type	Description
record	`LogRecord`	the log record.

handler.flush()

Ensure all logging output has been flushed.

This version does nothing and is intended to be implemented by subclasses.

Kind: instance method of Handler

handler.close()

Tidy up any resources used by the handler.

This version does nothing and is intended to be implemented by subclasses.

Kind: instance method of Handler

handler.handleError(record)

Handle errors which occur during an emit() call. This method should be called from handlers when an exception is encountered during an emit() call. If raiseExceptions is false, exceptions get silently ignored. This is what is mostly wanted for a logging system - most users will not care about errors in the logging system, they are more interested in application errors. You could, however, replace this with a custom handler if you wish. The record which was being processed is passed in to this method.

Kind: instance method of Handler

Param	Type	Description
record	`LogRecord`	the log record.

handler.addFilter(filter)

Add the specified filter to this handler/logger.

Kind: instance method of Handler

Param	Type	Description
filter	`Filter`	the filter instance.

handler.removeFilter(filter)

Remove the specified filter from this handler/logger.

Kind: instance method of Handler

Param	Type	Description
filter	`Filter`	the filter instance.

handler.filter(record) ⇒ `boolean`

Determine if a record is loggable by consulting all the filters. The default is to allow the record to be logged; any filter can veto this and the record is then dropped.

Kind: instance method of Handler
Returns: boolean - false if a record is to be dropped, else true.

Param	Type	Description
record	`LogRecord`	the log record.

Logger ⇐ `Filterer`

Kind: global class
Extends: Filterer

Logger ⇐ Filterer
- new Logger(name, level)
- .addHandler(handler)
- .removeHandler(handler)
- .getEffectiveLevel() ⇒ int
- .isEnabledFor(level) ⇒ boolean
- .handle(record)
- .debug(msg, ...args)
- .info(msg, ...args)
- .warn(msg, ...args)
- .error(msg, ...args)
- .exception(msg, ...args)
- .critical(msg, ...args)
- .addFilter(filter)
- .removeFilter(filter)
- .filter(record) ⇒ boolean

new Logger(name, level)

Initialize the logger with a name and an optional level.

Param	Type	Description
name	`string`	the logger name.
level	`int/string`	the log level.

logger.addHandler(handler)

Add the specified handler to this logger.

Kind: instance method of Logger

Param	Type	Description
handler	`Handler`	an handler instance to be added.

logger.removeHandler(handler)

Remove the specified handler from this logger.

Kind: instance method of Logger

Param	Type	Description
handler	`Handler`	an handler instance to be removed.

logger.getEffectiveLevel() ⇒ `int`

Get the effective level for this logger. Loop through this logger and its parents in the logger hierarchy, looking for a non-zero logging level. Return the first one found.

Kind: instance method of Logger
Returns: int - first found level in the lookup.

logger.isEnabledFor(level) ⇒ `boolean`

Is this logger enabled for level 'level'?

Kind: instance method of Logger
Returns: boolean - true if enabled for gievn level otherwise false.

Param	Type	Description
level	`int`	the log level

logger.handle(record)

Call the handlers for the specified record.

Kind: instance method of Logger

Param	Type	Description
record	`LogRecord`	the log record to handle

logger.debug(msg, ...args)

Log util.format(msg, ...args) with severity 'DEBUG'.

Kind: instance method of Logger

Param	Type	Description
msg	`string`	the log message.
...args	`args`	args to be applied on the message. To pass extra fields and excInfo, pass an object as the last parameter with key excInfo or extra or both. If key extra or excInfo is present in the last parameter passed, pop it out from the args list and do not consider for string formatting and set excInfo and extra fields to log record.

Example

logger.debug('Hi, I am a %s message', 'debug');
// Hi, I am a debug message

Example

logger.debug('Hi, I am a %s message', 'debug', {id: 90});
// Hi, I am a debug message {id: 90}

Example

logger.debug('Hi, I am a %s message', 'debug', {extra: {httpStatus: 200}});
// Hi, I am a debug message
// <Object with extra field is ignored, however these extra fields are
// available as part of the log record.
// Ex: record.httpStatus, record.excInfo etc.>

logger.info(msg, ...args)

Log util.format(msg, ...args) with severity 'INFO'.

Kind: instance method of Logger

Param	Type	Description
msg	`string`	the log message.
...args	`args`	args to be applied on the message. Visit for more details

logger.warn(msg, ...args)

Log util.format(msg, ...args) with severity 'WARN'.

Kind: instance method of Logger

Param	Type	Description
msg	`string`	the log message.
...args	`args`	args to be applied on the message. Visit for more details

logger.error(msg, ...args)

Log util.format(msg, ...args) with severity 'ERROR'.

Kind: instance method of Logger

Param	Type	Description
msg	`string`	the log message.
...args	`args`	args to be applied on the message. Visit for more details

logger.exception(msg, ...args)

Log util.format(msg, ...args) with severity 'EXCEPTION'.

Kind: instance method of Logger

Param	Type	Description
msg	`string`	the log message.
...args	`args`	args to be applied on the message. Visit for more details

logger.critical(msg, ...args)

Log util.format(msg, ...args) with severity 'CRITICAL'.

Kind: instance method of Logger

Param	Type	Description
msg	`string`	the log message.
...args	`args`	args to be applied on the message. Visit for more details

logger.addFilter(filter)

Add the specified filter to this handler/logger.

Kind: instance method of Logger

Param	Type	Description
filter	`Filter`	the filter instance.

logger.removeFilter(filter)

Remove the specified filter from this handler/logger.

Kind: instance method of Logger

Param	Type	Description
filter	`Filter`	the filter instance.

logger.filter(record) ⇒ `boolean`

Determine if a record is loggable by consulting all the filters. The default is to allow the record to be logged; any filter can veto this and the record is then dropped.

Kind: instance method of Logger
Returns: boolean - false if a record is to be dropped, else true.

Param	Type	Description
record	`LogRecord`	the log record.

ConsoleHandler ⇐ `Handler`

A handler which writes log records to stdout/stderr.

Kind: global class
Extends: Handler

ConsoleHandler ⇐ Handler
- new ConsoleHandler()
- .emit(record)
- .getName() ⇒ string
- .setLevel(level)
- .setFormatter(formatter)
- .format(record, fmt) ⇒ string
- .handle(record) ⇒ boolean
- .flush()
- .close()
- .handleError(record)
- .addFilter(filter)
- .removeFilter(filter)
- .filter(record) ⇒ boolean

new ConsoleHandler()

Initialize the ConsoleHandler instance.

consoleHandler.emit(record)

Emit log record to stdout/stderr.

Kind: instance method of ConsoleHandler
Overrides: emit

Param	Type	Description
record	`LogRecord`	the log record to be emitted.

consoleHandler.getName() ⇒ `string`

Get the logger name.

Kind: instance method of ConsoleHandler
Returns: string - the logger name.

consoleHandler.setLevel(level)

Set the logging level of this handler.

Kind: instance method of ConsoleHandler

Param	Type	Description
level	`integer` \| `string`	the log level.

consoleHandler.setFormatter(formatter)

Set the formatter for this handler.

Kind: instance method of ConsoleHandler

Param	Type	Description
formatter	`Formatter`	the formatter instance.

consoleHandler.format(record, fmt) ⇒ `string`

Format the specified record. If a formatter is set, use it. Otherwise, return record.getMessage()

Kind: instance method of ConsoleHandler
Returns: string - formatted message.

Param	Type	Description
record	`LogRecord`	the log record.
fmt	`string`	optional fmt to be used instead of the default one.

consoleHandler.handle(record) ⇒ `boolean`

Conditionally emit the specified logging record.

Emission depends on filters which may have been added to the handler.

Kind: instance method of ConsoleHandler
Returns: boolean - whether the filter passed the record for emission.

Param	Type	Description
record	`LogRecord`	the log record.

consoleHandler.flush()

Ensure all logging output has been flushed.

This version does nothing and is intended to be implemented by subclasses.

Kind: instance method of ConsoleHandler

consoleHandler.close()

Tidy up any resources used by the handler.

This version does nothing and is intended to be implemented by subclasses.

Kind: instance method of ConsoleHandler

consoleHandler.handleError(record)

Kind: instance method of ConsoleHandler

Param	Type	Description
record	`LogRecord`	the log record.

consoleHandler.addFilter(filter)

Add the specified filter to this handler/logger.

Kind: instance method of ConsoleHandler

Param	Type	Description
filter	`Filter`	the filter instance.

consoleHandler.removeFilter(filter)

Remove the specified filter from this handler/logger.

Kind: instance method of ConsoleHandler

Param	Type	Description
filter	`Filter`	the filter instance.

consoleHandler.filter(record) ⇒ `boolean`

Determine if a record is loggable by consulting all the filters. The default is to allow the record to be logged; any filter can veto this and the record is then dropped.

Kind: instance method of ConsoleHandler
Returns: boolean - false if a record is to be dropped, else true.

Param	Type	Description
record	`LogRecord`	the log record.

Formatter

   %(name)s            Name of the logger (logging channel)
   %(level)s           Numeric logging level for the message (DEBUG, INFO,
                       WARN, ERROR, CRITICAL)
   %(levelname)s       Text logging level for the message ("DEBUG", "INFO",
                       "WARN", "ERROR", "EXCEPTION", "CRITICAL")
   %(created)f         Time when the LogRecord was created (time.time()
                       return value)
   %(asctime)s         Textual time when the LogRecord was created
   %(process)d         Process ID (if available)
   %(message)s         The result of record.getMessage(), computed just as
                       the record is emitted
   %(trace)s           The stack trace where logging call was made

   NOTE: filename, lineno, modulename, and funcName are not available in this version,
   and to fetch these, trace need to parsed by the developer.

Kind: global class

Formatter
- new Formatter([fmt], [datefmt])
- .format(record, fmt) ⇒ string
- .formatField(record, name) ⇒ string
- .formatTime(record, [datefmt]) ⇒ string

new Formatter([fmt], [datefmt])

Initialize the formatter with specified format strings.

Param	Type	Description
[fmt]	`string`	the log format to be used.
[datefmt]	`string`	date format to be used. this format is passed to `moment` library for date formatting.

formatter.format(record, fmt) ⇒ `string`

Format the record.

Kind: instance method of Formatter
Returns: string - formatted string.

Param	Type	Description
record	`LogRecord`	the log record to be formatted.
fmt	`string`	optional fmt to be used instead of the default one.

formatter.formatField(record, name) ⇒ `string`

Format a record field.

Kind: instance method of Formatter
Returns: string - formatted record field.

Param	Type	Description
record	`LogRecord`	the log record.
name	`string`	name of the record field.

formatter.formatTime(record, [datefmt]) ⇒ `string`

Format the datetime field.

Kind: instance method of Formatter
Returns: string - formatted datetime(asctime) field.

Param	Type	Description
record	`LogRecord`	the log record.
[datefmt]	`string`	date format to be used instead of the default one.

CRITICAL

Log level CRITICAL with numeric value 50.

Kind: global variable

FATAL

Log level FATAL with numeric value same as of CRITICAL.

Kind: global variable

ERROR

Log level ERROR with numeric value 40.

Kind: global variable

EXCEPTION

Log level EXCEPTION with numeric value same as of ERROR.

Kind: global variable

WARN

Log level WARN with numeric value 30.

Kind: global variable

WARNING

Log level WARNING and is same as WARN.

Kind: global variable

INFO

Log level INFO with numeric value 20.

Kind: global variable

DEBUG

Log level DEBUG with numeric value 10.

Kind: global variable

NOTSET

Log level NOTSET with numeric value 0.

Kind: global variable

setLoggerClass(klass)

Set the logger class inherited from Logger. This is usefull incase developer wants to use a custom logger class. However this custom class should be inherited from Logger class.

Kind: global function

Param	Type	Description
klass	`LoggerClass`	the the logger class to be used.

setLogRecordClass(klass)

Set the log record class inherited from LogRecord. This is usefull incase developer wants to use a custom log record class. However this custom class should be inherited from LogRecord class.

Kind: global function

Param	Type	Description
klass	`LogRecordClass`	the the log record class to be used.

getLogger([name]) ⇒ `Logger`

Get logger instance for the given logger name. All calls to this function with a given name return the same logger instance. This means that logger instances never need to be passed between different parts of an application.

Kind: global function
Returns: Logger - the logger instance.

Param	Type	Default	Description
[name]	`string`	`"'root'"`	name of the logger.

FilesExpand file tree

API.md

Latest commit

History

API.md

File metadata and controls

Classes

Members

Functions

LogRecord

new LogRecord(name, level, levelname, msg, [args], [trace])

logRecord.getMessage() ⇒ string

Filter

new Filter([name])

filter.filter(record) ⇒ boolean

Filterer

new Filterer()

filterer.addFilter(filter)

filterer.removeFilter(filter)

filterer.filter(record) ⇒ boolean

Handler ⇐ Filterer

new Handler([level])

handler.getName() ⇒ string

handler.setLevel(level)

handler.setFormatter(formatter)

handler.format(record, fmt) ⇒ string

handler.emit(record)

handler.handle(record) ⇒ boolean

handler.flush()

handler.close()

handler.handleError(record)

handler.addFilter(filter)

handler.removeFilter(filter)

handler.filter(record) ⇒ boolean

Logger ⇐ Filterer

new Logger(name, level)

logger.addHandler(handler)

logger.removeHandler(handler)

logger.getEffectiveLevel() ⇒ int

logger.isEnabledFor(level) ⇒ boolean

logger.handle(record)

logger.debug(msg, ...args)

logger.info(msg, ...args)

logger.warn(msg, ...args)

logger.error(msg, ...args)

logger.exception(msg, ...args)

logger.critical(msg, ...args)

logger.addFilter(filter)

logger.removeFilter(filter)

logger.filter(record) ⇒ boolean

ConsoleHandler ⇐ Handler

new ConsoleHandler()

consoleHandler.emit(record)

consoleHandler.getName() ⇒ string

consoleHandler.setLevel(level)

consoleHandler.setFormatter(formatter)

consoleHandler.format(record, fmt) ⇒ string

consoleHandler.handle(record) ⇒ boolean

consoleHandler.flush()

consoleHandler.close()

consoleHandler.handleError(record)

consoleHandler.addFilter(filter)

consoleHandler.removeFilter(filter)

consoleHandler.filter(record) ⇒ boolean

Formatter

new Formatter([fmt], [datefmt])

formatter.format(record, fmt) ⇒ string

formatter.formatField(record, name) ⇒ string

formatter.formatTime(record, [datefmt]) ⇒ string

CRITICAL

FATAL

ERROR

EXCEPTION

WARN

WARNING

INFO

DEBUG

NOTSET

setLoggerClass(klass)

setLogRecordClass(klass)

logRecord.getMessage() ⇒ `string`

filter.filter(record) ⇒ `boolean`

filterer.filter(record) ⇒ `boolean`

Handler ⇐ `Filterer`

handler.getName() ⇒ `string`

handler.format(record, fmt) ⇒ `string`

handler.handle(record) ⇒ `boolean`

handler.filter(record) ⇒ `boolean`

Logger ⇐ `Filterer`

logger.getEffectiveLevel() ⇒ `int`

logger.isEnabledFor(level) ⇒ `boolean`

logger.filter(record) ⇒ `boolean`

ConsoleHandler ⇐ `Handler`

consoleHandler.getName() ⇒ `string`

consoleHandler.format(record, fmt) ⇒ `string`

consoleHandler.handle(record) ⇒ `boolean`

consoleHandler.filter(record) ⇒ `boolean`

formatter.format(record, fmt) ⇒ `string`

formatter.formatField(record, name) ⇒ `string`

formatter.formatTime(record, [datefmt]) ⇒ `string`

getLogger([name]) ⇒ `Logger`