log.handlers#

Module: log.handlers#

pyzmq logging handlers.

This mainly defines the PUBHandler object for publishing logging messages over a zmq.PUB socket.

The PUBHandler can be used with the regular logging module, as in:

>>> import logging
>>> handler = PUBHandler('tcp://127.0.0.1:12345')
>>> handler.root_topic = 'foo'
>>> logger = logging.getLogger('foobar')
>>> logger.setLevel(logging.DEBUG)
>>> logger.addHandler(handler)

Or using dictConfig, as in:

>>> from logging.config import dictConfig
>>> socket = Context.instance().socket(PUB)
>>> socket.connect('tcp://127.0.0.1:12345')
>>> dictConfig({
>>>     'version': 1,
>>>     'handlers': {
>>>         'zmq': {
>>>             'class': 'zmq.log.handlers.PUBHandler',
>>>             'level': logging.DEBUG,
>>>             'root_topic': 'foo',
>>>             'interface_or_socket': socket
>>>         }
>>>     },
>>>     'root': {
>>>         'level': 'DEBUG',
>>>         'handlers': ['zmq'],
>>>     }
>>> })

After this point, all messages logged by logger will be published on the PUB socket.

Code adapted from StarCluster:

Classes#

PUBHandler#

class zmq.log.handlers.PUBHandler(interface_or_socket: str | Socket, context: Context | None = None, root_topic: str = '')#

A basic logging handler that emits log messages through a PUB socket.

Takes a PUB socket already bound to interfaces or an interface to bind to.

Example:

sock = context.socket(zmq.PUB)
sock.bind('inproc://log')
handler = PUBHandler(sock)

Or:

handler = PUBHandler('inproc://loc')

These are equivalent.

Log messages handled by this handler are broadcast with ZMQ topics this.root_topic comes first, followed by the log level (DEBUG,INFO,etc.), followed by any additional subtopics specified in the message by: log.debug(“subtopic.subsub::the real message”)

acquire()#

Acquire the I/O thread lock.

addFilter(filter)#

Add the specified filter to this handler.

close()#

Tidy up any resources used by the handler.

This version removes the handler from an internal map of handlers, _handlers, which is used for handler lookup by name. Subclasses should ensure that this gets called from overridden close() methods.

createLock()#

Acquire a thread lock for serializing access to the underlying I/O.

ctx: Context#
emit(record)#

Emit a log message on my socket.

filter(record)#

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. Returns a zero value if a record is to be dropped, else non-zero.

Changed in version 3.2: Allow filters to be just callables.

flush()#

Ensure all logging output has been flushed.

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

format(record)#

Format a record.

get_name()#
handle(record)#

Conditionally emit the specified logging record.

Emission depends on filters which may have been added to the handler. Wrap the actual emission of the record with acquisition/release of the I/O thread lock. Returns whether the filter passed the record for emission.

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.

property name#
release()#

Release the I/O thread lock.

removeFilter(filter)#

Remove the specified filter from this handler.

property root_topic: str#
setFormatter(fmt, level=0)#

Set the Formatter for this handler.

If no level is provided, the same format is used for all levels. This will overwrite all selective formatters set in the object constructor.

setLevel(level)#

Set the logging level of this handler. level must be an int or a str.

setRootTopic(root_topic: str)#

Set the root topic for this handler.

This value is prepended to all messages published by this handler, and it defaults to the empty string ‘’. When you subscribe to this socket, you must set your subscription to an empty string, or to at least the first letter of the binary representation of this string to ensure you receive any messages from this handler.

If you use the default empty string root topic, messages will begin with the binary representation of the log level string (INFO, WARN, etc.). Note that ZMQ SUB sockets can have multiple subscriptions.

set_name(name)#
socket: Socket#

TopicLogger#

class zmq.log.handlers.TopicLogger(name, level=0)#

A simple wrapper that takes an additional argument to log methods.

All the regular methods exist, but instead of one msg argument, two arguments: topic, msg are passed.

That is:

logger.debug('msg')

Would become:

logger.debug('topic.sub', 'msg')
addFilter(filter)#

Add the specified filter to this handler.

addHandler(hdlr)#

Add the specified handler to this logger.

callHandlers(record)#

Pass a record to all relevant handlers.

Loop through all handlers for this logger and its parents in the logger hierarchy. If no handler was found, output a one-off error message to sys.stderr. Stop searching up the hierarchy whenever a logger with the “propagate” attribute set to zero is found - that will be the last logger whose handlers are called.

critical(level, topic, msg, *args, **kwargs)#

Log ‘msg % args’ with severity ‘CRITICAL’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.critical(“Houston, we have a %s”, “major disaster”, exc_info=1)

debug(level, topic, msg, *args, **kwargs)#

Log ‘msg % args’ with severity ‘DEBUG’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.debug(“Houston, we have a %s”, “thorny problem”, exc_info=1)

error(level, topic, msg, *args, **kwargs)#

Log ‘msg % args’ with severity ‘ERROR’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.error(“Houston, we have a %s”, “major problem”, exc_info=1)

exception(msg, *args, exc_info=True, **kwargs)#

Convenience method for logging an ERROR with exception information.

fatal(level, topic, msg, *args, **kwargs)#

Don’t use this method, use critical() instead.

filter(record)#

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. Returns a zero value if a record is to be dropped, else non-zero.

Changed in version 3.2: Allow filters to be just callables.

findCaller(stack_info=False, stacklevel=1)#

Find the stack frame of the caller so that we can note the source file name, line number and function name.

getChild(suffix)#

Get a logger which is a descendant to this one.

This is a convenience method, such that

logging.getLogger(‘abc’).getChild(‘def.ghi’)

is the same as

logging.getLogger(‘abc.def.ghi’)

It’s useful, for example, when the parent logger is named using __name__ rather than a literal string.

getEffectiveLevel()#

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.

handle(record)#

Call the handlers for the specified record.

This method is used for unpickled records received from a socket, as well as those created locally. Logger-level filtering is applied.

hasHandlers()#

See if this logger has any handlers configured.

Loop through all handlers for this logger and its parents in the logger hierarchy. Return True if a handler was found, else False. Stop searching up the hierarchy whenever a logger with the “propagate” attribute set to zero is found - that will be the last logger which is checked for the existence of handlers.

info(msg, *args, **kwargs)#

Log ‘msg % args’ with severity ‘INFO’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.info(“Houston, we have a %s”, “interesting problem”, exc_info=1)

isEnabledFor(level)#

Is this logger enabled for level ‘level’?

log(level, topic, msg, *args, **kwargs)#

Log ‘msg % args’ with level and topic.

To pass exception information, use the keyword argument exc_info with a True value:

logger.log(level, "zmq.fun", "We have a %s",
        "mysterious problem", exc_info=1)
makeRecord(name, level, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)#

A factory method which can be overridden in subclasses to create specialized LogRecords.

manager = <logging.Manager object>#
removeFilter(filter)#

Remove the specified filter from this handler.

removeHandler(hdlr)#

Remove the specified handler from this logger.

root = <RootLogger root (INFO)>#
setLevel(level)#

Set the logging level of this logger. level must be an int or a str.

warn(level, topic, msg, *args, **kwargs)#
warning(level, topic, msg, *args, **kwargs)#

Log ‘msg % args’ with severity ‘WARNING’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.warning(“Houston, we have a %s”, “bit of a problem”, exc_info=1)