Library API

class noblklog.AsyncStreamHandler(stream=None, terminator='\n', max_queued=None)[source]

Asynchronous logging handler that writes to a stream.

Requires an output stream that actually supports non-blocking writes. If no stream is specified explicitly, standard error is used.

On common Unix platforms only true FIFOs and named as well as unnamed pipes are supported. This specifically includes the standard output and error streams as well as shell pipes between processs but explicitly excludes files.

The handler tries as best as possible to check for unsupported output streams but cannot detect all possible problematic configurations.

The log records are written to the stream followed by terminator.

Parameters:

max_queued (int) – Sets a size limit for the internal queue that is used in case of message congestion. This will guard against unbounded memory usage but on the other hand will risk dropped log messages in case the queue is full. Default is None for unlimited queue size.

class noblklog.AsyncSyslogHandler(...)[source]

Asynchronous logging handler for sending RFC 3164 or 5424 compatible messages to Syslog.

This handler only implements sending log messages to a local unix domain socket. Usually this is /dev/log to get them delivered to the local Syslog daemon. Delivering directly to remote destinations is not implemented as I see no need to increase code complexity when just about every Syslog daemon already supports forwarding messages.

Traditionally Syslog uses UDP (SOCK_DGRAM) for transport. This is usually also the case for delivery over the local Unix domain socket. Using a Datagram protocol has the advantage of keeping all messages seperate but limits the maximum message size. The protcol limit is usually not a problem as Syslog daemons set smaller limits by default.

In addition to tuning your Syslog daemon you’ll also need to to switch to a TCP / stream transport if you really want to go above the ~65k bytes message limit of UDP. Take a minute to also review the parameter message_framing and your Syslog daemon’s settings if you go that way.

This handler will encode messages contents in UTF-8. For RFC 5424 this is the specified behaviour. For RFC 3164 this usually works, too. (“Usually” is all you can ever hope for the old Syslog protocol.)

Parameters:

  • facility (str) – Set the Syslog facility to send messages with. See encodePriority() for possible values. Defaults to 'user'.

  • hostname (str) – Specify the default hostname to send messages with. Defaults to the value returned by socket.gethostname(). Individual messages can overwrite this by passing extra={'hostname': 'string'} to the logging method.

  • appname (str) – Specify the default appname (or tag in RFC 3164 jargon) to send messages with. Defaults to '-' to denote unspecified as per RFC 5424. Use extra={'appname': 'string'} to overwrite this for individual messages.

  • procid (str) – Specify the default process id to send with the messages with. Defaults to '-' for RFC 5424 mode and completly dropping the field for RFC 3164. Since the logging module will by default pass the result of os.getpid() for each message logged and this handler will use that value there’s usually no reason to use this parameter. Use extra={'procid': 'string'} to overwrite this for individual messages.

  • structured_data – Default structured data elements to send with all messages. Needs to be a dictionary of dictionaries like this: {"SD-ID": {"PARAM-NAME": "PARAM-VALUE", ...}, ...}. Defaults to an empty dictionary. Elements from extra={"structured_data": ...} and extra={"sd": ...} will be added on a per message basis.

  • socket_path (str) – Path of the Unix domain socket to connect and deliver messages to. On common Unix systems with common configurations there’s no need to use any value but the default ('/dev/log').

  • socket_types (list) – List of socket types to try connecting to the Syslog socket with. The first type for which a connection succeeds will be used. By default SOCK_DGRAM will be tried before SOCK_STREAM.

  • message_format (int) – Specify how to format the sent messages. Usually you should use the default of SYSLOG_FORMAT_RFC5424 as this format is simply much better. With SYSLOG_FORMAT_RFC3164 you get the predecessor that should work just about everywhere but is much well defined.

  • message_framing (int) – Tells the handler how to delimit messages on stream transports. For datagramm (UDP) mode this parameter is ignored. The default value of SYSLOG_FRAMING_NON_TRANSPARENT will simply end each message with a newline character. This can break if you’re logging newlines. Try using SYSLOG_FRAMING_OCTET_COUNTING then but be warned that some Syslog deamons might need configuration changes or simply not support this mode.

  • utf8_bom (bool) – Some RFC 5424 Syslog deamons will trip over the UTF-8 byte order mark required by the standard. This is obviously broken behaviour but since fixing other peoples messes is had here’s a workaround. Set this parameter to False to write the message without a BOM between header and content.

  • utc_timestamp (bool) – Send message timestamp as UTC instead of localtime with timezone information. Will be ignored in RFC 3164 mode. This can be useful if your log messages originate in different timezones but some component of your logging stack can’t handle the timezones in the Syslog timestamps.

  • max_queued (int) – Sets a size limit for the internal queue that is used in case of message congestion. This will guard against unbounded memory usage but on the other hand will risk dropped log messages in case the queue is full. Default is None for unlimited queue size.