Log Loaders¶

Functional Interfaces¶

General APIs¶

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

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.

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

data (Union[str, bytes]) – 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.

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

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

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 (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.

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

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

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 (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.

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 – Arbitrary positional arguments.
**kwargs – 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 – Arbitrary positional arguments.
**kwargs – 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 (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.

Return type: Literal[‘ascii’]

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 (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.

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.

Return type: Literal[‘json’]

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

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

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

Bases: object

Basic log parser.

abstract property format: str¶

Log file format.

Return type: str

parse(filename, model=None)[source]¶

Parse log file.

Parameters

filename (PathLike[str]) – Log file name.
model (Optional[Type[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

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

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)[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.

Log Loaders¶

Functional Interfaces¶

General APIs¶

ASCII Format¶

JSON Format¶

Predefined Loaders¶

Abstract Base Loader¶

ZLogging

Navigation

Related Topics