The pysros.syslog
module provides functionality for obtaining and
manipulating a syslog event.
Note
This module is available when executing on SR OS only. On a remote machine, the syslog function is not supported.
Important
The pysros.syslog
module is designed to be used
with the SR OS syslog functionality at high processing rates.
It cannot be used with the pysros.management
module, SR OS filesystem access, or the EHS, CRON, or pyexec execution
pathways.
Two methods are available to modify the syslog message being sent:
The
pysros.syslog.get_event()
function retrieves the syslog event that is in the queue to be sent out and allows for its attributes to be modified. When the Python application terminates successfully, the newly modified attributes are reformatted using the default syslog format.The
pysros.syslog.Event.override_payload()
method allows for an entirely new payload to be crafted based on the data from the original event but choosing a customer format and which data to include.
Note
The maximum length of a syslog message on SR OS is 1023 bytes. When modifying the payload to become larger than this maximum value, one of the following occurs:
When using
pysros.syslog.Event.override_payload()
, an exception is raised. The length can be checked prior to executing thepysros.syslog.Event.override_payload()
method.When modifying the event parameters, the resulting payload is truncated as the resulting length cannot be known in advance. When this occurs, the last character is marked with an asterisk (*).
- pysros.syslog.get_event()¶
Obtain the syslog event queued to be sent out.
- Returns
The event object or None.
- Return type
pysros.syslog.Event
orNone
- generate_pri(facility, severity)¶
Converts the event severity into a syslog severity and combines it with the facility to generate the syslog PRI value (See RFC 5424 for details) that can be used when formatting a new syslog payload.
- Parameters
facility (int) – Syslog facility value.
severity (str) – Event severity name.
- Returns
Syslog PRI value.
- Return type
str
- Raises
ValueError – for invalid facilities, see
pysros.syslog.Event.facility
ValueError – for invalid severities, see
pysros.syslog.Event.severity
- severity_to_name(severity)¶
Converts an event severity name into a syslog severity name.
- Parameters
severity (str) – Event severity name.
- Returns
Syslog severity name.
- Return type
str
- Raises
ValueError – for invalid severities, see
pysros.syslog.Event.severity
- get_system_name()¶
Retrieves the system name. This function is provided directly as part of the
pysros.syslog
module to provide enhanced performance for the syslog execution pathway.- Returns
SR OS system name.
- Return type
str
- class pysros.syslog.Event¶
The syslog
Event
class provides access to the header-fields of the messages, the individual fields of the event and the syslog-specific attributes.Note
The header-fields can be modified unless stated otherwise.
Any changes are reflected in the actual syslog-packet being sent out.
If a change of message format is required, for example, the ordering or the value of the field needs to change,
override_payload()
should be used to override the complete message. In this case, the actual message first needs to be formatted using theformat_msg()
function before it is passed to theoverride_payload()
function.- name¶
The name of the event.
- Type
str
- appid¶
The name of the application that generated the event.
- Type
str
- eventid¶
The event ID number of the application.
- Type
int
- Raises
ValueError – for negative values.
- severity¶
The severity level of the event. Valid values are:
none
cleared
indeterminate
critical
major
minor
warning
- Type
str
- sequence¶
The sequence number of the event in the syslog collector.
- Type
int
- Raises
ValueError – for negative values.
- subject¶
The subject or affected object of the event.
- Type
str
- router_name¶
The name of the SR OS router-instance (For example,
Base
) in which this event was triggered.- Type
str
- gentime¶
The time, in ISO 8601 format, that the event was generated.
Note
Changes to
timestamp
are reflected in this attribute.- Type
str, read-only
- timestamp¶
The time, in seconds, that the event was generated.
- Type
float
- hostname¶
The hostname field of the syslog message. This can be an IP address, fully-qualified domain name (FQDN), or hostname.
- Type
str
- log_prefix¶
The log-prefix inserted into the event message.
- Type
str
- facility¶
The syslog facility code. A list of named values is provided in
pysros.syslog.Facility
.- Type
int
- Raises
ValueError – for values outside of the valid range [0..31]
- text¶
The event specific body formatted as a string. By default, this is generated from the
eventparameters
.This attribute can be modified to provide new event text.
This message may include values from the
eventparameters
function.- Type
str
- eventparameters¶
The additional parameters specific to the event that caused the Python application to execute.
Note
The parameters returned cannot be modified to alter the generated event text. Instead, a new event text should be generated from the values and assigned to the
text
attribute.- Returns
Event specific parameters. The parameters in this class are read-only.
- Return type
- format_msg()¶
Return a string representation of the SR OS formatted log message.
- Returns
SR OS formatted log message.
- Return type
str
- format_syslog_msg()¶
Return a string representation of the SR OS formatted log message as it appears in the syslog packet. When any of the writable attributes on this event have been modified, the output of this function contains these changes.
- Returns
SR OS formatted syslog message.
- Return type
str
- override_payload(payload)¶
Provide a custom syslog message as it appears in the packet. This includes header information (facility, timestamp, etc.) and body data (the actual message).
Attributes from this event can be used to construct a completely new message format. Any prior changes to the values of these attributes are used.
- Parameters
payload (str) – New syslog payload.
- Raises
ValueError – when payload is larger than the maximum of 1023 bytes.
- drop()¶
Drop the syslog message from the send queue.
- class pysros.syslog.EventParams¶
The additional parameters of the specific
pysros.syslog.Event
. This class is read-only. Specific additional parameters may be accessed using standard Python subscript syntax.- keys()¶
Obtain the additional parameter names.
- Returns
Additional parameter names for the event.
- Return type
tuple(str)
- params[key]
Return the value of the parameter key. If the parameter does not exist, a
KeyError
is raised. key is of type str.
- iter(params)
Return an iterator for the key value pairs of parameters.
Where an iterator is expected, this object can be passed and the iterator is used implicitly. This can be used to collect all
pysros.syslog.Event.eventparameters
into a standard Python dict.>>> list(event.eventparameters) [('key1', 'value1'), ('key2', 'value2'), ('key3', 'value3')] >>> params = dict(event.eventparameters) >>> type(params) <class 'dict'> >>> params {'key1': 'value1', 'key2': 'value2', 'key3': 'value3'}
- class Facility¶
Class similar to an Enum that defines constants that can be used as values for the
pysros.syslog.Event.facility
attribute.Note
No instances of this class can be instantiated.
- KERNEL = 0¶
- USER = 1¶
- MAIL = 2¶
- SYSTEMD = 3¶
- AUTH = 4¶
- SYSLOGD = 5¶
- PRINTER = 6¶
- NETNEWS = 7¶
- UUCP = 8¶
- CRON = 9¶
- AUTHPRIV = 10¶
- FTP = 11¶
- NTP = 12¶
- LOGAUDIT = 13¶
- LOGALERT = 14¶
- CRON2 = 15¶
- LOCAL0 = 16¶
- LOCAL1 = 17¶
- LOCAL2 = 18¶
- LOCAL3 = 19¶
- LOCAL4 = 20¶
- LOCAL5 = 21¶
- LOCAL6 = 22¶
- LOCAL7 = 23¶