Data Model

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

Bases: object

Log data model.

Parameters:

• *args (Any) – Arbitrary positional arguments.

• **kwargs (Any) – Arbitrary keyword arguments.

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.

Return type:

Model

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 zlogging.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 expand_typing() for more information about processing the fields.

property fields: OrderedDict[str, _SimpleType | _GenericType]

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.

Return type:

None

__call__(format)

Serialise data model with given format.

Parameters:

format (str) – Serialisation format.

Return type:

Any

Returns:

The serialised data.

Raises:

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

tojson()

Serialise data model as JSON log format.

Return type:

OrderedDict[str, Any]

Returns:

An OrderedDict mapping each field and serialised JSON serialisable data.

toascii()

Serialise data model as ASCII log format.

Return type:

OrderedDict[str, str]

Returns:

An OrderedDict mapping each field and serialised text data.

asdict(dict_factory=None)

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

Parameters:

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

Return type:

dict[str, Any]

Returns:

A dictionary mapping field names to field values.

astuple(tuple_factory=None)

Convert data model as a tuple of field values.

Parameters:

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

Return type:

tuple[Any, ...]

Returns:

A tuple of field values.

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

Create a data model dynamically with the appropriate fields.

Parameters:

• name (str) – data model name

• **fields (Any) – defined fields of the data model

Return type:

Type[Model]

Returns:

Created data 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))