Log Loaders

Functional Interfaces

General APIs

zlogging.loader.parse(filename, *args, **kwargs)[source]

Parse Bro/Zeek log file.

Parameters:
Returns:

The parsed JSON log data.

Raises:

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

Return type:

Union[JSONInfo, ASCIIInfo]

zlogging.loader.loads(data, *args, **kwargs)[source]

Parse Bro/Zeek log string.

Parameters:
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(file, *args, **kwargs)[source]

Parse Bro/Zeek log file.

Parameters:
Return type:

Union[JSONInfo, ASCIIInfo]

Returns:

The parsed JSON log data.

Raises:

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

ASCII Format

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

Parse ASCII log file.

Parameters:
  • filename – Log file name.

  • parser – Parser class.

  • type_hook – Bro/Zeek type parser hooks. User may customise subclasses of BaseType to modify parsing behaviours.

  • enum_namespaces – Namespaces to be loaded.

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

  • *args – Arbitrary positional arguments.

  • **kwargs – Arbitrary keyword arguments.

Returns:

The parsed ASCII log data.

Return type:

ASCIIInfo

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

Parse ASCII log string.

Parameters:
  • data – Log string as binary or encoded string.

  • parser – Parser class.

  • type_hook – Bro/Zeek type parser hooks. User may customise subclasses of BaseType to modify parsing behaviours.

  • enum_namespaces – Namespaces to be loaded.

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

  • *args – Arbitrary positional arguments.

  • **kwargs – Arbitrary keyword arguments.

Returns:

The parsed ASCII log data.

Return type:

ASCIIInfo

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

Parse ASCII log file.

Parameters:
  • file – Log file object opened in binary mode.

  • parser – Parser class.

  • type_hook – Bro/Zeek type parser hooks. User may customise subclasses of BaseType to modify parsing behaviours.

  • enum_namespaces – Namespaces to be loaded.

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

  • *args – Arbitrary positional arguments.

  • **kwargs – Arbitrary keyword arguments.

Returns:

The parsed ASCII log data.

Return type:

ASCIIInfo

JSON Format

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

Parse JSON log file.

Parameters:
  • filename – Log file name.

  • parser – Parser class.

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

  • *args – Arbitrary positional arguments.

  • **kwargs – Arbitrary keyword arguments.

Returns:

The parsed JSON log data.

Return type:

JSONInfo

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

Parse JSON log string.

Parameters:
  • data (Union[str, bytes]) – Log string as binary or encoded string.

  • parser (Optional[Type[JSONParser]]) – Parser class.

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

  • *args (Any) – Arbitrary positional arguments.

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

Return type:

JSONInfo

Returns:

The parsed JSON log data.

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

Parse JSON log file.

Parameters:
  • file (BufferedReader) – Log file object opened in binary mode.

  • parser (Optional[Type[JSONParser]]) – Parser class.

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

  • *args (Any) – Arbitrary positional arguments.

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

Return type:

JSONInfo

Returns:

The parsed JSON log data.

Predefined Loaders

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

Bases: BaseParser

ASCII log parser.

Parameters:
  • type_hook – Bro/Zeek type parser hooks. User may customise subclasses of BaseType to modify parsing behaviours.

  • enum_namespaces – Namespaces to be loaded.

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

property format: Literal['ascii']

Log file format.

enum_namespaces: list[str]

Namespaces to be loaded.

bare: bool

If True, do not load zeek namespace by default.

parse_file(file, model=None)[source]

Parse log file.

Parameters:
  • file (BufferedReader) – 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.

Return type:

ASCIIInfo

Returns:

The parsed log as a Model per line.

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)[source]

Parse log line as one-line record.

Parameters:
  • line – A simple line of log.

  • lineno – Line number of current line.

  • model – Field declrations of current log.

  • separator – Data separator.

  • parser – Field data type parsers.

Returns:

The parsed log as a plain dict.

Raises:

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

Return type:

Model

class zlogging.loader.JSONParser(model=None)[source]

Bases: BaseParser

JSON log parser.

Parameters:

model (Optional[Type[Model]]) – 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: Literal['json']

Log file format.

model: Optional[Type[Model]]

~zlogging.loader.JSONParser, as in JSON logs the field typing information are omitted by the Bro/Zeek logging framework.

Type:

Field declrations for

Type:

class

parse_file(file, model=None)[source]

Parse log file.

Parameters:
Return type:

JSONInfo

Returns:

The parsed log as a Model per line.

parse_line(line, lineno=0, model=None)[source]

Parse log line as one-line record.

Parameters:
Return type:

Model

Returns:

The parsed log as a plain Model.

Raises:

JSONParserError – If failed to serialise the line from JSON.

Abstract Base Loader

class zlogging.loader.BaseParser[source]

Bases: object

Basic log parser.

abstract property format: str

Log file format.

parse(filename, model=None)[source]

Parse log file.

Parameters:
  • filename – Log file name.

  • model – Field declrations of current log.

Returns:

The parsed log as an ASCIIInfo or JSONInfo.

Return type:

Info

abstract parse_file(file, model=None)[source]

Parse log file.

Parameters:
Returns:

The parsed log as a Model per line.

Return type:

Info

abstract parse_line(line, lineno=0, model=None)[source]

Parse log line as one-line record.

Parameters:
Return type:

Model

Returns:

The parsed log as a plain Model.

load(file)[source]

Parse log file.

Parameters:

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

Returns:

The parsed log as a Model per line.

Return type:

Info

loads(line, lineno=0)[source]

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.