Logging functions

Configuration examples

YAML logging config (see Logging config YAML for example) can be used as follows:

import seismometer.logging
import yaml
log_config = yaml.safe_load(log_config_file)
seismometer.logging.dictConfig(log_config)

Given that logging configuration is a simple dictionary, config file is not restricted to YAML format. See Logging config dict for example.

Logging config dict

log_config = {
    "version": 1,
    "root": { "handlers": ["stdout"] },
    "handlers": {
        "stdout": {
            "class": "logging.StreamHandler",
            "stream": "ext://sys.stdout",
            "formatter": "precise_formatter",
        },
        "syslog": {
            "class": "seismometer.logging.SysLogHandler",
            "formatter": "syslog_formatter",
            "facility": "daemon",
            # XXX: change "somethingd" to your daemon name if you plan to use
            # syslog handler
            "process_name": "somethingd"
        },
    },
    "formatters": {
        "brief_formatter": {
            "format": "%(levelname)-8s %(message)s",
        },
        "precise_formatter": {
            "format": "%(asctime)s %(levelname)-8s %(name)-15s %(message)s",
            "datefmt": "<%Y-%m-%d %H:%M:%S>",
        },
        "syslog_formatter": {
            "format": "[%(name)s] %(message)s",
        },
    },
}

Logging config YAML

---
version: 1
root:
  handlers: [stdout]
handlers:
  stdout:
    class: logging.StreamHandler
    stream: ext://sys.stdout
    formatter: precise_formatter
  syslog:
    class: seismometer.logging.SysLogHandler
    formatter: syslog_formatter
    facility: daemon
    # XXX: change "somethingd" to your daemon name if you plan to use
    # syslog handler
    process_name: somethingd
formatters:
  brief_formatter:
    format: "%(levelname)-8s %(message)s"
  precise_formatter:
    format: "%(asctime)s %(levelname)-8s %(name)-15s %(message)s"
    datefmt: "%Y-%m-%d %H:%M:%S"
  syslog_formatter:
    format: "[%(name)s] %(message)s"

Programming interface

For Python 2.7, logging.config module has a dictConfig() function. For older releases (2.4 through 2.6, possibly even older) Seismometer Toolbox provides seismometer.logging.dictConfig() function that works the same way (on Python 2.7 it’s actually imported logging.config.dictConfig()). User can configure logging following way, regardless of the Python release:

import seismometer.logging
seismometer.logging.dictConfig(log_config)

Logging configuration functions

seismometer.logging.dictConfig(config)
Parameters:config – configuration dict

Compatibility function for setting up logging using dict, possibly loaded from file.

For Python 2.7+ this function is just logging.config.dictConfig(). For older releases, local copy is used.

seismometer.logging.configure_from_file(filename, default=None)
Parameters:
  • filename – file (JSON or YAML) to read configuration from (may be None)
  • default – configuration to use in case when filename doesn’t exist

Function configures logging according to dict config read from filename. If filename is missing and default was specified, logging is configured according to that one. If no acceptable filename nor default was provided, RuntimeError is raised.

default should be dict config, but as a shorthand, it may be "stderr" or "null". Logging will be configured then with log_config_stderr() or log_config_null(), respectively.

seismometer.logging.log_config_syslog(procname, facility='daemon', level='info')
Parameters:
  • procname – name of the process to report to syslog
  • facility – syslog facility
  • level – log level
Returns:

logging config dictionary

Function returns logging configuration that logs to syslog messages of severity info or higher. Intended to be used with dictConfig().

Some valid values for facility: "daemon", "local0" through "local7", "syslog", "user".

Valid log levels: "debug", "info", "warning", "error", "critical".

seismometer.logging.log_config_stderr()
Returns:logging config dictionary

Function returns logging configuration that prints to STDERR logs of severity warning or higher. Intended to be used with dictConfig().

seismometer.logging.log_config_null()
Returns:logging config dictionary

Function returns logging configuration that suppresses any logs whatsoever. Intended to be used with dictConfig().

Log handler classes

class seismometer.logging.NullHandler

Sink log handler. Used to suppress logs.

class seismometer.logging.SysLogHandler(facility, process_name)

Syslog log handler. This one works a little better than logging.handlers.SysLogHandler with regard to syslog restarts and is independent from log socket location. On the other hand, it only logs to locally running syslog.

This handler requires two fields to be provided in configuration: "facility" (e.g. "daemon", "local0" through "local7", "syslog", "user") and "process_name", which will identify the daemon in logs.