Loaders

Predefined Loaders

Bro/Zeek log loader.

zlogging.loader.parse(filename, *args, **kwargs)

Parse Bro/Zeek log file.

Parameters

• filename (PathLike[str]) – Log file name.

• *args – See parse_json() and parse_ascii() for more information.

• **kwargs – See parse_json() and parse_ascii() for more information.

• args (Any) –

• kwargs (Any) –

Return type

Union[JSONInfo, ASCIIInfo]

Returns

The parsed JSON log data.

Raises

ParserError – If the format of the log file is unknown.

zlogging.loader.parse_ascii(filename, parser=None, type_hook=None, enum_namespaces=None, bare=False, *args, **kwargs)

Parse ASCII log file.

Parameters

• filename (PathLike[str]) – Log file name.

• parser (ASCIIParser, optional) – Parser class.

• type_hook (dict mapping str and BaseType class, optional) – Bro/Zeek type parser hooks. User may customise subclasses of BaseType to modify parsing behaviours.

• enum_namespaces (List[str], optional) – Namespaces to be loaded.

• bare (bool, optional) – If True, do not load zeek namespace by default.

• *args – Variable length argument list.

• **kwargs – Arbitrary keyword arguments.

• args (Any) –

• kwargs (Any) –

Return type

ASCIIInfo

Returns

The parsed ASCII log data.

zlogging.loader.parse_json(filename, parser=None, model=None, *args, **kwargs)

Parse JSON log file.

Parameters

• filename (PathLike[str]) – Log file name.

• parser (JSONParser, optional) – Parser class.

• model (Model class, optional) – Field declarations for JSONParser, as in JSON logs the field typing information are omitted by the Bro/Zeek logging framework.

• *args – Variable length argument list.

• **kwargs – Arbitrary keyword arguments.

• args (Any) –

• kwargs (Any) –

Return type

JSONInfo

Returns

The parsed JSON log data.

zlogging.loader.loads(data, *args, **kwargs)

Parse Bro/Zeek log string.

Parameters

• data (AnyStr) – Log string as binary or encoded string.

• *args – See loads_json() and loads_ascii() for more information.

• **kwargs – See loads_json() and loads_ascii() for more information.

• args (Any) –

• kwargs (Any) –

Return type

Union[JSONInfo, ASCIIInfo]

Returns

The parsed JSON log data.

Raises

ParserError – If the format of the log file is unknown.

zlogging.loader.loads_ascii(data, parser=None, type_hook=None, enum_namespaces=None, bare=False, *args, **kwargs)

Parse ASCII log string.

Parameters

• data (AnyStr) – Log string as binary or encoded string.

• parser (ASCIIParser, optional) – Parser class.

• type_hook (dict mapping str and BaseType class, optional) – Bro/Zeek type parser hooks. User may customise subclasses of BaseType to modify parsing behaviours.

• enum_namespaces (List[str], optional) – Namespaces to be loaded.

• bare (bool, optional) – If True, do not load zeek namespace by default.

• *args – Variable length argument list.

• **kwargs – Arbitrary keyword arguments.

• args (Any) –

• kwargs (Any) –

Return type

ASCIIInfo

Returns

The parsed ASCII log data.

zlogging.loader.loads_json(data, parser=None, model=None, *args, **kwargs)

Parse JSON log string.

Parameters

• data (AnyStr) – Log string as binary or encoded string.

• parser (JSONParser, optional) – Parser class.

• model (Model class, optional) – Field declarations for JSONParser, as in JSON logs the field typing information are omitted by the Bro/Zeek logging framework.

• *args – Variable length argument list.

• **kwargs – Arbitrary keyword arguments.

• args (Any) –

• kwargs (Any) –

Return type

JSONInfo

Returns

The parsed JSON log data.

zlogging.loader.load(file, *args, **kwargs)

Parse Bro/Zeek log file.

Parameters

• file (BinaryFile) – Log file object opened in binary mode.

• *args – See load_json() and load_ascii() for more information.

• **kwargs – See load_json() and load_ascii() for more information.

• args (Any) –

• kwargs (Any) –

Return type

Union[JSONInfo, ASCIIInfo]

Returns

The parsed JSON log data.

Raises

ParserError – If the format of the log file is unknown.

zlogging.loader.load_ascii(file, parser=None, type_hook=None, enum_namespaces=None, bare=False, *args, **kwargs)

Parse ASCII log file.

Parameters

• file (BinaryFile) – Log file object opened in binary mode.

• parser (ASCIIParser, optional) – Parser class.

• type_hook (dict mapping str and BaseType class, optional) – Bro/Zeek type parser hooks. User may customise subclasses of BaseType to modify parsing behaviours.

• enum_namespaces (List[str], optional) – Namespaces to be loaded.

• bare (bool, optional) – If True, do not load zeek namespace by default.

• *args – Variable length argument list.

• **kwargs – Arbitrary keyword arguments.

• args (Any) –

• kwargs (Any) –

Return type

ASCIIInfo

Returns

The parsed ASCII log data.

zlogging.loader.load_json(file, parser=None, model=None, *args, **kwargs)

Parse JSON log file.

Parameters

• file (BinaryFile) – Log file object opened in binary mode.

• parser (JSONParser, optional) – Parser class.

• model (Model class, optional) – Field declarations for JSONParser, as in JSON logs the field typing information are omitted by the Bro/Zeek logging framework.

• *args – Variable length argument list.

• **kwargs – Arbitrary keyword arguments.

• args (Any) –

• kwargs (Any) –

Return type

JSONInfo

Returns

The parsed JSON log data.

class zlogging.loader.ASCIIParser(type_hook=None, enum_namespaces=None, bare=False)

Bases: zlogging.loader.BaseParser

ASCII log parser.

Parameters

• type_hook (dict mapping str and BaseType class, optional) – Bro/Zeek type parser hooks. User may customise subclasses of BaseType to modify parsing behaviours.

• enum_namespaces (List[str], optional) – Namespaces to be loaded.

• bare (bool, optional) – If True, do not load zeek namespace by default.

Variables

• __type__ (dict mapping str and BaseType class) – Bro/Zeek type parser hooks.

• enum_namespaces (List[str]) – Namespaces to be loaded.

• bare (bool) – If True, do not load zeek namespace by default.

property format

Log file format.

Type

str

Return type

Literal[“ascii”]

parse_file(file, model=None)

Parse log file.

Parameters

• file (BinaryFile) – Log file object opened in binary mode.

• model (Optional[Type[Model]]) – Field declrations of current log. This parameter is only kept for API compatibility with its base class BaseLoader, and will NOT be used at runtime.

Returns

The parsed log as a

Model per line.

Return type

ASCIIInfo

Warns

ASCIIParserWarning – If the ASCII log file exited with error, see ASCIIInfo.exit_with_error for more information.

parse_line(line, lineno=0, model=None, separator=b'\\t', parser=None)

Parse log line as one-line record.

Parameters

• line (bytes) – A simple line of log.

• lineno (Optional[int]) – Line number of current line.

• model (Optional[Type[Model]]) – Field declrations of current log.

• separator (Optional[bytes]) – Data separator.

• parser (List of BaseType, required) – Field data type parsers.

Return type

Model

Returns

The parsed log as a plain dict.

Raises

ASCIIPaserError – If parser is not provided; or failed to serialise line as ASCII.

class zlogging.loader.JSONParser(model=None)

Bases: zlogging.loader.BaseParser

JSON log parser.

Parameters

model (Model class, optional) – Field declrations for JSONParser, as in JSON logs the field typing information are omitted by the Bro/Zeek logging framework.

Variables

model (Model class, optional) – Field declrations for JSONParser, as in JSON logs the field typing information are omitted by the Bro/Zeek logging framework.

Warns

JSONParserWarning – If model is not specified.

property format

Log file format.

Type

str

Return type

Literal[“json”]

parse_file(file, model=None)

Parse log file.

Parameters

• file (BinaryFile) – Log file object opened in binary mode.

• model (Optional[Type[Model]]) – Field declrations of current log.

Returns

The parsed log as a

Model per line.

Return type

JSONInfo

parse_line(line, lineno=0, model=None)

Parse log line as one-line record.

Parameters

• line (bytes) – A simple line of log.

• lineno (Optional[int]) – Line number of current line.

• model (Optional[Type[Model]]) – Field declrations of current log.

Return type

Model

Returns

The parsed log as a plain Model.

Raises

JSONParserError – If failed to serialise the line from JSON.

Abstract Base Loaders

class zlogging.loader.BaseParser

Bases: object

Basic log parser.

abstract property format

Log file format.

Type

str

Return type

str

parse(filename, model=None)

Parse log file.

Parameters

• filename (PathLike[str]) – Log file name.

• model (Optional[Type[Model]]) – Field declrations of current log.

Return type

Info

Returns

The parsed log as an ASCIIInfo or JSONInfo.

abstract parse_file(file, model=None)

Parse log file.

Parameters

• file (BinaryFile) – Log file object opened in binary mode.

• model (Optional[Type[Model]]) – Field declrations of current log.

Returns

The parsed log as a Model per line.

Return type

Info

abstract parse_line(line, lineno=0, model=None)

Parse log line as one-line record.

Parameters

• line (bytes) – A simple line of log.

• lineno (Optional[int]) – Line number of current line.

• model (Optional[Type[Model]]) – Field declrations of current log.

Return type

Model

Returns

The parsed log as a plain Model.

load(file)

Parse log file.

Parameters

file (BinaryFile) – Log file object opened in binary mode.

Returns

The parsed log as a Model per line.

Return type

Info

loads(line, lineno=0)

Parse log line as one-line record.

Parameters

• line (bytes) – A simple line of log.

• lineno (Optional[int]) – Line number of current line.

Return type

Model

Returns

The parsed log as a plain Model.