Data Model

Bro/Zeek log data model.

class zlogging.model.Model(*args, **kwargs)

Bases: object

Log data model.

Variables

  • __fields__ (OrderedDict mapping str and BaseType) – Fields of the data model.

  • __record_fields__ (OrderedDict mapping str and RecordType) – Fields of record data type in the data model.

  • __empty_field__ (bytes) – Placeholder for empty field.

  • __unset_field__ (bytes) – Placeholder for unset field.

  • __set_separator__ (bytes) – Separator for set/vector fields.

Warns

BroDeprecationWarning – Use of bro_* type annotations.

Raises

  • ModelValueError – In case of inconsistency between field data types, or values of unset_field, empty_field and set_separator.

  • ModelTypeError – Wrong parameters when initialisation.

Note

Customise the Model.__post_init__ method in your subclassed data model to implement your own ideas.

Example

Define a custom log data model using the prefines Bro/Zeek data types, or subclasses of BaseType:

class MyLog(Model):
    field_one = StringType()
    field_two = SetType(element_type=PortType)

Or you may use type annotations as PEP 484 introduced when declaring data models. All available type hints can be found in typing:

class MyLog(Model):
    field_one: zeek_string
    field_two: zeek_set[zeek_port]

However, when mixing annotations and direct assignments, annotations will take proceedings, i.e. the Model class shall process first annotations then assignments. Should there be any conflicts, ModelError will be raised.

See also

See _aux_expand_typing() for more information about processing the fields.

property fields

OrderedDict mapping str and BaseType: fields of the data model

property unset_field

bytes: placeholder for empty field

property empty_field

bytes: placeholder for unset field

property set_separator

bytes: separator for set/vector fields

__post_init__()

Post-processing customisation.

__call__(format)

Serialise data model with given format.

Parameters

format (str) – Serialisation format.

Returns

The serialised data.

Raises

ModelFormatError – If format is not supproted, i.e. Mode.to{format}() does not exist.

Return type

Any

tojson()

Serialise data model as JSON log format.

Returns

An OrderedDict mapping each field and serialised JSON serialisable data.

Return type

OrderedDict[str, Any]

toascii()

Serialise data model as ASCII log format.

Returns

An OrderedDict mapping each field and serialised text data.

Return type

OrderedDict[str, str]

asdict(dict_factory=None)

Convert data model as a dictionary mapping field names to field values.

Parameters

dict_factory (Optional[type]) – If given, dict_factory will be used instead of built-in dict.

Returns

A dictionary mapping field names to field values.

Return type

Dict[str, Any]

astuple(tuple_factory=None)

Convert data model as a tuple of field values.

Parameters

tuple_factory (Optional[type]) – If given, tuple_factory will be used instead of built-in tuple.

Returns

A tuple of field values.

Return type

Tuple[Any]

zlogging.model.new_model(name, **fields)

Create a data model dynamically with the appropriate fields.

Parameters

  • name (str) – data model name

  • **fields – defined fields of the data model

  • Any] fields (Dict[str,) –

Returns

created data model

Return type

Model

Examples

Typically, we define a data model by subclassing the Model class, as following:

class MyLog(Model):
    field_one = StringType()
    field_two = SetType(element_type=PortType)

when defining dynamically with new_model(), the definition above can be rewrote to:

MyLog = new_model('MyLog', field_one=StringType(), field_two=SetType(element_type=PortType))