Logging

pytiger uses the Python logging framework to generate messages and bubble them up through to handlers.

The legacy pytiger.logging.legacy.LegacySyslogger class replicates old behaviour for a managed transition to the full framework. It should not be used for new works.

Quick Start

The following snippet will cater for most simple uses:

>>> import logging
>>> import pytiger.logging.config
>>> pytiger.logging.config.basic_config(level=logging.WARNING)
>>> log = logging.getLogger(__name__)
>>> log.info('This entry will not appear')
>>> log.warning('Unable to biggle')
W: Unable to biggle
>>> log.error('Abandon ship, all ye who run this')
E: Abandon ship, all ye who run this

pytiger.logging.config – Configure Python logging

New in version 1.2.0.

Configure the Python logging system following Tiger conventions.

This module, combined with the Python logging package, is the spiritual successor to the deprecated pytiger.logging.legacy module.

Example usage:

>>> import logging
>>> import pytiger.logging.config
>>> pytiger.logging.config.basic_config()
>>> log = logging.getLogger(__name__)
>>> log.warning('Unable to biggle')
W: Unable to biggle
>>> log.error('Abandon ship, all ye who run this')
E: Abandon ship, all ye who run this

class pytiger.logging.config.LevelTagFilter

Log filter that adds the leveltag field.

This logging.Filter sub-class (using duck-typing) is used to add the leveltag field to logging.LogRecord objects so that the tag is available for use when formatted with the TCL_FORMAT format string.

pytiger.logging.config.TCL_FORMAT = '%(leveltag)s: %(message)s'

Log format string following Tiger Computing conventions.

pytiger.logging.config.basic_config(fmt=None, datefmt=None, level=None, stderr=True, stderr_level=None, syslog=True, syslog_level=None)

Perform basic configuration of the Python logging system.

This is very similar to logging.basicConfig() but designed to follow Tiger Computing’s logging conventions: messages are logged to stderr and to syslog, and messages are prefixed with a single character tag describing the log level.

This function does nothing if the root logger already has handlers configured, therefore this function will only configure logging once. It is a convenience method to do one-shot configuration of the Python logging package.

The default behaviour is to:

• Create a logging.StreamHandler which writes to sys.stderr.
• Create a pytiger.logging.syslog.SyslogHandler, which forwards messages to syslog using syslog.syslog().
• Add the LevelTagFilter to the above handlers.
• Set a formatter on the above handlers using the TCL_FORMAT format string.
• Add the handlers to the root logger.
• Sets the root logger’s log level to logging.INFO.

Parameters:

• fmt (str) – Use the specified format string for the handlers.
• datefmt (str) – Use the specified date/time format.
• level – Set the root logger’s log level.
• stderr (bool) – Determine whether the stderr StreamHandler is configured or added to the root logger.
• stderr_level – Set the stderr logger’s log level.
• syslog (bool) – Determine whether the SyslogHandler is configured or added to the root logger.
• syslog_level – Set the syslog logger’s log level.

pytiger.logging.syslog – Syslog logging handler

New in version 1.2.0.

Provides a true syslog handler for the Python logging framework based on the Python syslog module.

pytiger.logging.syslog.FACILITY_NAMES = {'auth': 32, 'cron': 72, 'daemon': 24, 'kern': 0, 'local0': 128, 'local1': 136, 'local2': 144, 'local3': 152, 'local4': 160, 'local5': 168, 'local6': 176, 'local7': 184, 'lpr': 48, 'mail': 16, 'news': 56, 'syslog': 40, 'user': 8, 'uucp': 64}

Mapping of syslog facility names to numeric values

pytiger.logging.syslog.PRIORITY_MAP = [(10, 7), (20, 6), (30, 4), (40, 3), (50, 2)]

Mapping of logging priority levels to syslog priority

pytiger.logging.syslog.PRIORITY_NAMES = {'alert': 1, 'crit': 2, 'debug': 7, 'emerg': 0, 'err': 3, 'info': 6, 'notice': 5, 'warning': 4}

Mapping of syslog priority names to numeric values

class pytiger.logging.syslog.SyslogFormatter(fmt=None, datefmt=None)

Default custom formatter for the SyslogHandler.

formatException(ei)

Return a blank string for all exceptions.

This avoids sending exceptions to syslog at any priority.

class pytiger.logging.syslog.SyslogHandler(ident=None, facility=8, options=1, formatter=<class 'pytiger.logging.syslog.SyslogFormatter'>)

Python log handler for syslog.

This uses the Python native syslog module, unlike logging.handlers.SysLogHandler. This means that syslog messages are sent to the local syslog daemon over /dev/log rather than sending UDP messages to localhost (or some remote host).

emit(record)

Emit a record.

pytiger.logging.syslog.encode_priority(fac, pri)

Encode the facility and priority into an integer.

Uses the priority() and facility() functions to look up the values based on the given parameters.

pytiger.logging.syslog.facility(facility)

Lookup a syslog facility number.

Accepts either a string or integer facility. If this is a string, the value is looked up in the FACILITY_NAMES dictionry.

pytiger.logging.syslog.priority(priority)

Lookup a syslog priority level.

Accepts either a string or integer priority level. If this is a string, the value is looked up in the PRIORITY_NAMES dictionry.

pytiger.logging.legacy – Legacy logging module

New in version 1.0.0.

Deprecated since version 1.2.0.

Defines a number of log level attributes and LegacySyslogger to carry out the real work.

This module should not be used for new work, but is provided to smooth the transition from tclutils.log.

By default, log entries are sent to standard output and the system logger.

Four valid log level constants are provided at the module level:

• ERROR – a problem that means execution cannot, or should not continue
• WARNING – an unexpected situtation but execution will continue
• INFO – informational output not indicative of a problem e.g. progress messages
• DEBUG – a message that should only be emitted when debugging code

These constants may be used anywhere that a level is expected by LegacySyslogger.

class pytiger.logging.legacy.LegacySyslogger

An object that looks a bit like a Python logging object so that we can transition more easily later.

Deprecated since version 1.2.0.

Example usage:

>>> s = LegacySyslogger()
>>> # Long hand:
>>> s.log(WARNING, 'Unable to biggle')
W: Unable to biggle
>>> # Short hand:
>>> s.warning('Could not frob; continuing')
W: Could not frob, continuing
>>> s.error('Abandon ship, all ye who run this')
E: Abandon ship, all ye who run this

log_level

Minimum level at which to emit a log entry

log_to_stdout

Whether to log to stdout (True or False)

log_to_syslog

Whether to log to syslog (True or False)

log(level, msg)

Print a message if its level is equal or less than the filter level. Depending on configuration, the message may be emitted to syslog or to stdout or both.

Parameters:

• level (int) – Log message level
• msg (str) – Log message text

debug(msg)

Shorthand for log(DEBUG, msg)()

error(msg)

Shorthand for log(ERROR, msg)

info(msg)

Shorthand for log(INFO, msg)

warning(msg)

Shorthand for log(WARNING, msg)