Log Loaders

Functional Interfaces

General APIs

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

Parse Bro/Zeek log file.

Parameters:

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

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

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

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(data, *args, **kwargs)

Parse Bro/Zeek log string.

Parameters:

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

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

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

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)

Parse Bro/Zeek log file.

Parameters:

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

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

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

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)

Parse ASCII log file.

Parameters:

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

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

• type_hook (Optional[dict[str, Type[BaseType]]]) – Bro/Zeek type parser hooks. User may customise subclasses of BaseType to modify parsing behaviours.

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

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

• *args (Any) – Arbitrary positional arguments.

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

Return type:

ASCIIInfo

Returns:

The parsed ASCII log data.

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

Parse ASCII log string.

Parameters:

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

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

• type_hook (Optional[dict[str, Type[BaseType]]]) – Bro/Zeek type parser hooks. User may customise subclasses of BaseType to modify parsing behaviours.

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

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

• *args (Any) – Arbitrary positional arguments.

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

Return type:

ASCIIInfo

Returns:

The parsed ASCII log data.

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

Parse ASCII log file.

Parameters:

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

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

• type_hook (Optional[dict[str, Type[BaseType]]]) – Bro/Zeek type parser hooks. User may customise subclasses of BaseType to modify parsing behaviours.

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

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

• *args (Any) – Arbitrary positional arguments.

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

Return type:

ASCIIInfo

Returns:

The parsed ASCII log data.

JSON Format

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

Parse JSON log file.

Parameters:

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

• 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.loads_json(data, parser=None, model=None, *args, **kwargs)

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)

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)

Bases: BaseParser

ASCII log parser.

Parameters:

• type_hook (Optional[dict[str, Type[BaseType]]]) – Bro/Zeek type parser hooks. User may customise subclasses of BaseType to modify parsing behaviours.

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

• bare (bool) – 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)

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)

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 (Optional[list[tuple[str, BaseType]]]) – Field data type parsers.

Return type:

Model

Returns:

The parsed log as a plain dict.

Raises:

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

class zlogging.loader.JSONParser(model=None)

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)

Parse log file.

Parameters:

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

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

Return type:

JSONInfo

Returns:

The parsed log as a Model per line.

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 Loader

class zlogging.loader.BaseParser

Bases: object

Basic log parser.

abstract property format: str

Log file format.

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 (BufferedReader) – 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 (BufferedReader) – 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.