2. API Reference

2.1. Class SysLogHandler

class syslog2.SysLogHandler(address=('localhost', 514), facility=1, socktype=None, program=None, format=None, append_nul=True)

A logging handler that sends log records to the local system log or to a remote Syslog server.

Parameters

• address (str or tuple(host(str), port(int)) –

  Address of the target system log, as follows:

  • string “local”: Targets the local system log. The socktype parameter is ignored. For details, see Local system log targets.

  • other string: Address for a UNIX domain socket. The socktype parameter specifies the socket type.

  • tuple(host(str), port(int)): Hostname and port for an Internet domain socket. The socktype parameter specifies the socket type.

• facility (int or str) – Syslog facility to be used, either the facility code as an integer, or the facility name as a string using the names defined in SysLogHandler.facility_names. For details on how the syslog facility is used, see Use of the syslog facility.

• socktype (int or None) –

  Socket type to be used when address specifies a socket:

  • socket.SOCK_DGRAM - datagram/UDP-based socket

  • socket.SOCK_STREAM - stream/TCP-based socket

  • None - The socket type is automatically selected as follows:

    • For UNIX domain sockets, socket.SOCK_DGRAM is tried first and then socket.SOCK_STREAM.

    • For Internet domain sockets, the socket type is determined when resolving the network address.

• program (str) – A program identifier string that is used in the log message. If None, the base file name from sys.args[0] is used. For details on how the program identifier is used, see Use of the program identifier.

• format (str) –

  Selects the format of the log message that is sent to the system log, i.e. what is added to the message provided by the Python logging formatter. The Python logging formatter must match the selected format. Valid formats are:

  • ”user” - The logging formatter needs to create the complete log message that will be sent, and this class does not add or change anything. The append_nul argument is ignored.

  • ”pri” - The logging formatter needs to create the complete log message except for <PRI> which is added to the front of the log message by this class. A 0x00 Byte is appended as determined by the append_nul argument. This is what the standard Python SysLogHandler class does.

  • ”rfc5424” - Syslog format as defined in RFC5424. The logging formatter only creates the message field, and all other Syslog fields are automatically populated. A 0x00 Byte is appended as determined by the append_nul argument.

  • ”rfc3164” - Syslog format as defined in RFC3164. The logging formatter only creates the message field, and all other Syslog fields are automatically populated. A 0x00 Byte is appended as determined by the append_nul argument.

  • None - Dependent on the target, the right format is selected. The logging formatter only creates the message field.

• append_nul (bool) – Boolean controlling whether a 0x00 Byte is appended to the log message for some log formats. Some older Syslog servers need this.

Raises

syslog2.SysLogTargetError – The target system log(s) could not be found or used.

Methods

acquire	Acquire the I/O thread lock.
addFilter	Add the specified filter to this handler.
close	Close the Syslog handler.
createLock	Acquire a thread lock for serializing access to the underlying I/O.
emit	Emit a log record to the system log.
encodePriority	Deprecated: Return the Syslog priority from the syslog facility and severity.
filter	Determine if a record is loggable by consulting all the filters.
flush	Ensure all logging output has been flushed.
format	Format the specified record.
get_name
handle	Conditionally emit the specified logging record.
handleError	Handle errors which occur during an emit() call.
mapPriority	Deprecated: Return the syslog severity code for a Python logging level name.
release	Release the I/O thread lock.
removeFilter	Remove the specified filter from this handler.
setFormatter	Set the formatter for this handler.
setLevel	Set the logging level of this handler.
set_name

Attributes

LOG_ALERT	action must be taken immediately
LOG_AUTH	security/authorization messages
LOG_AUTHPRIV	security/authorization messages (private)
LOG_CONSOLE	Log alert
LOG_CRIT	critical conditions
LOG_CRON	clock daemon
LOG_DAEMON	system daemons
LOG_DEBUG	debug-level messages
LOG_EMERG	system is unusable
LOG_ERR	error conditions
LOG_FTP	FTP daemon
LOG_INFO	informational
LOG_KERN	kernel messages
LOG_LOCAL0	reserved for local use
LOG_LOCAL1	reserved for local use
LOG_LOCAL2	reserved for local use
LOG_LOCAL3	reserved for local use
LOG_LOCAL4	reserved for local use
LOG_LOCAL5	reserved for local use
LOG_LOCAL6	reserved for local use
LOG_LOCAL7	reserved for local use
LOG_LPR	line printer subsystem
LOG_MAIL	mail system
LOG_NEWS	network news subsystem
LOG_NOTICE	normal but significant condition
LOG_NTP	NTP subsystem
LOG_SECURITY	Log audit
LOG_SOLCRON	Scheduling daemon (Solaris)
LOG_SYSLOG	messages generated internally by syslogd
LOG_USER	random user-level messages
LOG_UUCP	UUCP subsystem
LOG_WARNING	warning conditions
facility_names	Mapping of Syslog facility names to Syslog facility codes.
severity_names	Mapping of Syslog severity names to Syslog severity codes.

Details

LOG_ALERT = 1

action must be taken immediately

LOG_AUTH = 4

security/authorization messages

LOG_AUTHPRIV = 10

security/authorization messages (private)

LOG_CONSOLE = 14

Log alert

LOG_CRIT = 2

critical conditions

LOG_CRON = 9

clock daemon

LOG_DAEMON = 3

system daemons

LOG_DEBUG = 7

debug-level messages

LOG_EMERG = 0

system is unusable

LOG_ERR = 3

error conditions

LOG_FTP = 11

FTP daemon

LOG_INFO = 6

informational

LOG_KERN = 0

kernel messages

LOG_LOCAL0 = 16

reserved for local use

LOG_LOCAL1 = 17

reserved for local use

LOG_LOCAL2 = 18

reserved for local use

LOG_LOCAL3 = 19

reserved for local use

LOG_LOCAL4 = 20

reserved for local use

LOG_LOCAL5 = 21

reserved for local use

LOG_LOCAL6 = 22

reserved for local use

LOG_LOCAL7 = 23

reserved for local use

LOG_LPR = 6

line printer subsystem

LOG_MAIL = 2

mail system

LOG_NEWS = 7

network news subsystem

LOG_NOTICE = 5

normal but significant condition

LOG_NTP = 12

NTP subsystem

LOG_SECURITY = 13

Log audit

LOG_SOLCRON = 15

Scheduling daemon (Solaris)

LOG_SYSLOG = 5

messages generated internally by syslogd

LOG_USER = 1

random user-level messages

LOG_UUCP = 8

UUCP subsystem

LOG_WARNING = 4

warning conditions

close()

Close the Syslog handler.

This method releases all resources acquired since init, and then calls the superclass close().

emit(record)

Emit a log record to the system log.

The input record is formatted using the Python logging formatter, and then the log message is built dependent on the selected format.

The record is then sent to the target system log.

encodePriority(facility, priority)

Deprecated: Return the Syslog priority from the syslog facility and severity.

The Syslog priority value is calculated using the algorithm defined in RFC5424 section 6.2.1.

This method is of not much use for users and has been deprecated.

Parameters

• facility (int or str) – Syslog facility to be used, either the facility code as an integer, or the facility name as a string using the names defined in SysLogHandler.facility_names.

• priority (int or str) – Syslog severity to be used, either the severity code as an integer, or the severity name as a string using the names defined in SysLogHandler.severity_names.

Returns

Syslog priority value

Return type

int

facility_names = {'auth': 4, 'authpriv': 10, 'console': 14, 'cron': 9, 'daemon': 3, 'ftp': 11, 'kern': 0, 'local0': 16, 'local1': 17, 'local2': 18, 'local3': 19, 'local4': 20, 'local5': 21, 'local6': 22, 'local7': 23, 'lpr': 6, 'mail': 2, 'news': 7, 'ntp': 12, 'security': 13, 'solaris-cron': 15, 'syslog': 5, 'user': 1, 'uucp': 8}

Mapping of Syslog facility names to Syslog facility codes.

mapPriority(levelName)

Deprecated: Return the syslog severity code for a Python logging level name.

This method is of not much use for users and has been deprecated.

Parameters

levelName (str) – Python logging level name. If this is not a valid level name, the WARNING level is assumed.

Returns

Syslog severity value.

Return type

int

severity_names = {'alert': 1, 'crit': 2, 'critical': 2, 'debug': 7, 'emerg': 0, 'err': 3, 'error': 3, 'info': 6, 'notice': 5, 'panic': 0, 'warn': 4, 'warning': 4}

Mapping of Syslog severity names to Syslog severity codes.

2.2. Class SysLogTargetError

class syslog2.SysLogTargetError

Exception indicating that the specified system log target could not be found or used.

Methods

with_traceback

Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes

args

2.3. SysLogHandler Details

2.3.1. Local system log targets

When the “address” parameter is set to “local”, the system log on the local system is automatically targeted:

• On Linux, a UNIX domain socket of datagram type to “/dev/log” is tried first. If that does not work, an Internet domain socket of UDP type to “localhost” on port 514 is tried.

• On UNIX, an Internet domain socket of UDP type to “localhost” on port 514 is used.

• On macOS 10.12 and later, the unified logging system is used by directly interfacing with its API.

• On macOS 10.11 and earlier, a UNIX domain socket of datagram type to “/var/run/syslog” is used (which is handled by the macOS system without requiring any additional syslog demon packages).

• On Windows, the event log is used by directly interfacing with its API.

• On CygWin, a UNIX domain socket of datagram type to “/dev/log” is used. This requires the “syslog-ng” package to be installed on CygWin.

• On other systems, an Internet domain socket of UDP type to “localhost” on port 514 is used.

2.3.2. Use of the syslog facility

The syslog facility is used in the log message dependent on the target system log:

• When targeting the local system log on macOS or Windows, the syslog facility is not used.

• Otherwise the target system log is handled by a syslog server, and the syslog facility is used to encode the priority value that is at the begin of the log message as <PRI>.

2.3.3. Use of the program identifier

The program identifier is used in the log message dependent on the target system log:

• When targeting the local system log on macOS 10.12 or later, the program identifier is used to set the “subsystem” parameter of the log entry.

• When targeting the local system log on macOS 10.11 or earlier, the program identifier is not used.

• When targeting the local system log on Windows, the program identifier is used to set the application name of the log entry.

• Otherwise the target system log is handled by a syslog server, and the program identifier is used dependent on the specified format argument:

  • For format="rfc5424", the program identifier is used for the “APP-NAME” field of the log message.

  • For format="rfc3164", the program identifier is not used in the log message.

  • Other formats are controlled by the logging formatter.