pyloggr.event

The pyloggr.event module mainly provides the Event class.

Event provides an abstraction of a syslog event.

class Event(procid=u'-', severity=u'', facility=u'', app_name=u'', source=u'', programname=u'', syslogtag=u'', message=u'', uuid=None, hmac=None, timereported=None, timegenerated=None, timehmac=None, custom_fields=None, structured_data=None, tags=None, iut=1, **kwargs)[source]

Bases: object

Represents a syslog event, with optional tags, custom fields and structured data

Variables:
__contains__(key)[source]

Return True if event has the given custom field, and the field is not empty

Parameters:key (str) – custom field key
Return type:bool
__delitem__(key)[source]

Deletes a custom field

Parameters:key (str) – custom field key
__eq__(other)[source]

Two events are equal if they have the same UUID

Return type:bool
__ge__(other)

x.__ge__(y) <==> x>=y

__getitem__(key)[source]

Return a custom field, given its key

Parameters:key (str) – custom field key
__gt__(other)

x.__gt__(y) <==> x>y

__le__(other)

x.__le__(y) <==> x<=y

__lt__(other)[source]

self < other if self.timereported < other.timereported

Return type:bool
__setitem__(key, values)[source]

Sets a custom field

Parameters:
  • key (str) – custom field key
  • values (iterable) – custom field values
_parse_trusted()[source]

Parse the “trusted fields” that rsyslog could generate

add_tags(tags)[source]

Add some tags to the event

Parameters:tags – a list of tags
app_name

Name of application that generated the event

apply_filters(filters)[source]

Apply some filters to the event

Parameters:filters – filters to apply
custom_fields

Small helper to access pyloggr specific custom fields

dump(frmt='JSON', fname=None)[source]

Dump the event

Explicit format: a string with the following possible placeholders: $DATE, $DATETIME, $MESSAGE, $SOURCE, $APP_NAME, $SEVERITY, $FACILITY, $PROCID, $UUID, $TAGS

Parameters:
  • frmt – dumping format (JSON, MSGPACK, RFC5424, RFC3164, RSYSLOG, ES or an explicit format)
  • fname – if not None, write the dumped string to fname file
Returns:

dumped string

Raises OSError:

if file operation fails (when fname is not None)

dump_dict()[source]

Serialize the event as a native python dict

Return type:dict
dump_json()[source]

Dump the event in JSON format

Return type:str
dump_msgpack()[source]

Dump the event using msgpack

dump_rfc3164()[source]

Dump the event into a RFC 3164 old-style syslog string

dump_rfc5424()[source]

Dump the event into a RFC 5424 compliant string

dump_rsyslog()[source]

Dump the event as RSYSLOG_FileFormat

see: http://www.rsyslog.com/doc/v8-stable/configuration/templates.html

dump_sql(cursor)[source]

Dumps the event as a SQL insert statement

Parameters:cursor – SQL cursor
Return type:str
dumps_elastic()[source]

Dumps in JSON suited for Elasticsearch

Return type:str
facility

Event facility

generate_hmac(self, verify_if_exists=True)[source]

Generate a HMAC from the fields: severity, facility, app_name, source, message, timereported

Parameters:verify_if_exists (bool) – verify event HMAC if it has one
Returns:a base 64 encoded HMAC
Return type:str
Raises InvalidSignature:
 if HMAC already exists but is invalid
generate_uuid(new_uuid=None)[source]

Generate a UUID for the current event

Parameters:new_uuid – if given, sets the UUID to new_uuid. if not given generate a UUID.
Returns:new UUID
Return type:str
hmac

Return the event HMAC.

If event doesn’t have a HMAC, return empty string If event has a HMAC and is not dirty, return HMAC If event is dirty, compute the new HMAC and return it

classmethod load(s)[source]

Try to deserialize an Event from a string or a dictionnary. load understands JSON events, RFC 5424 events and RFC 3164 events, or dictionnary events. It automatically detects the type, using regexp tests.

Parameters:s (str or dict or bytes) – string (JSON or RFC 5424 or RFC 3164) or dictionnary
Returns:The parsed event
Return type:Event
Raises ParsingError:
 if deserialization fails
static make_arrow_datetime(dt)[source]

Parse a date-time value and return the corresponding Arrow object

Parameters:dt (Arrow or datetime or str) – date-time
Returns:Arrow object
static make_facility(facility)[source]

Return a normalized facility value

Parameters:facility (int or str or unicode) – syslog facility (integer) or string
static make_severity(severity)[source]

Return a normalized severity value

Parameters:severity (int or str or unicode) – syslog priority (integer) or string
message

Event message

classmethod parse_bytes_to_event(bytes_ev, hmac=False, swallow_exceptions=False)[source]

Parse some bytes into an pyloggr.event.Event object

Parameters:
  • bytes_ev (bytes) – the event as bytes
  • hmac (bool) – generate/verify a HMAC
  • swallow_exceptions (bool) – if True, return None rather than raising validation exceptions
Returns:

the new Event object

Return type:

Event

Raises:
  • ParsingError – if bytes could not be parsed correctly
  • InvalidSignature – if hmac is True and a HMAC already exists, but is invalid
priority

Return the event computed syslog priority

remove_tags(tags)[source]

Remove some tags from the event. If the event does not really have such tag, it is ignored.

Parameters:tags – a list of tags
severity

Event severity

source

Event source hostname

tags

Access the event tags. Returns a set.

timegenerated

event “first seen” datetime

timehmac

datetime, when the event HMAC was created

timereported

event creation datetime

update_cfield(key, values)[source]

Append some values to custom field key

Parameters:
  • key – custom field key
  • values – iterable
update_cfields(d)[source]

Add some custom fields to the event

Parameters:d (dict) – a dictionnary of new fields
update_uuid_and_hmac()[source]

If event is dirty (core fields have been modified), generate UUID and HMAC

uuid

Return the event UUID. If event is dirty, generate a new UUID and return it.

verify_hmac()[source]

Verify event’s HMAC

Throws an InvalidSignature exception if HMAC is invalid

Returns:True
Return type:bool
Raises InvalidSignature:
 if HMAC is invalid
exception ParsingError(*args, **kwargs)[source]

Bases: exceptions.ValueError

Triggered when a string can’t be parsed into an Event