Log Dumpers ¶

zlogging.dumper.dumps(data, format, *args, **kwargs)[source]¶

Write Bro/Zeek log string.

Parameters:

data (Iterable[Model]) – Log records as an Iterable of Model per line.
format (str) – Log format.
*args (Any) – See dumps_json() and dumps_ascii() for more information.
**kwargs (Any) – See dumps_json() and dumps_ascii() for more information.

Raises:

WriterFormatError – If format is not supported.

Return type:

zlogging.dumper.dump(data, file, format, *args, **kwargs)[source]¶

Write Bro/Zeek log file.

Parameters:

data (Iterable[Model]) – Log records as an Iterable of Model per line.
format (str) – Log format.
file (TextIOWrapper) – Log file object opened in text mode.
*args (Any) – See dump_json() and dump_ascii() for more information.
**kwargs (Any) – See dump_json() and dump_ascii() for more information.

Raises:

WriterFormatError – If format is not supported.

Return type:

ASCII Format¶

zlogging.dumper.write_ascii(data, filename, writer=None, separator=None, empty_field=None, unset_field=None, set_separator=None, *args, **kwargs)[source]¶

Write ASCII log file.

Parameters:

data (Iterable[Model]) – Log records as an Iterable of Model per line.
filename (PathLike[str]) – Log file name.
writer (Optional[Type[ASCIIWriter]]) – Writer class.
separator (Union[str, bytes, None]) – Field separator when writing log lines.
empty_field (Union[str, bytes, None]) – Placeholder for empty field.
unset_field (Union[str, bytes, None]) – Placeholder for unset field.
set_separator (Union[str, bytes, None]) – Separator for set/vector fields.
*args (Any) – Arbitrary positional arguments.
**kwargs (Any) – Arbitrary keyword arguments.

Return type:

zlogging.dumper.dumps_ascii(data=None, writer=None, separator=None, empty_field=None, unset_field=None, set_separator=None, *args, **kwargs)[source]¶

Write ASCII log string.

Parameters:

data (Optional[Iterable[Model]]) – Log records as an Iterable of Model per line.
writer (Optional[Type[ASCIIWriter]]) – Writer class.
separator (Union[str, bytes, None]) – Field separator when writing log lines.
empty_field (Union[str, bytes, None]) – Placeholder for empty field.
unset_field (Union[str, bytes, None]) – Placeholder for unset field.
set_separator (Union[str, bytes, None]) – Separator for set/vector fields.
*args (Any) – Arbitrary positional arguments.
**kwargs (Any) – Arbitrary keyword arguments.

Return type:

Returns:

The JSON log string.

zlogging.dumper.dump_ascii(data, file, writer=None, separator=None, empty_field=None, unset_field=None, set_separator=None, *args, **kwargs)[source]¶

Write ASCII log file.

Parameters:

data (Iterable[Model]) – Log records as an Iterable of Model per line.
file (TextIOWrapper) – Log file object opened in text mode.
writer (Optional[Type[ASCIIWriter]]) – Writer class.
separator (Union[str, bytes, None]) – Field separator when writing log lines.
empty_field (Union[str, bytes, None]) – Placeholder for empty field.
unset_field (Union[str, bytes, None]) – Placeholder for unset field.
set_separator (Union[str, bytes, None]) – Separator for set/vector fields.
*args (Any) – Arbitrary positional arguments.
**kwargs (Any) – Arbitrary keyword arguments.

Return type:

JSON Format¶

zlogging.dumper.write_json(data, filename, writer=None, encoder=None, *args, **kwargs)[source]¶

Write JSON log file.

Parameters:

data (Iterable[Model]) – Log records as an Iterable of Model per line.
filename (PathLike[str]) – Log file name.
writer (Optional[Type[JSONWriter]]) – Writer class.
encoder (Optional[Type[JSONEncoder]]) – JSON encoder class.
*args (Any) – Arbitrary positional arguments.
**kwargs (Any) – Arbitrary keyword arguments.

Return type:

zlogging.dumper.dumps_json(data=None, writer=None, encoder=None, *args, **kwargs)[source]¶

Write JSON log string.

Parameters:

data (Optional[Iterable[Model]]) – Log records as an Iterable of Model per line.
writer (Optional[Type[JSONWriter]]) – Writer class.
encoder (Optional[Type[JSONEncoder]]) – JSON encoder class.
*args (Any) – Arbitrary positional arguments.
**kwargs (Any) – Arbitrary keyword arguments.

Return type:

Returns:

The JSON log string.

zlogging.dumper.dump_json(data, file, writer=None, encoder=None, *args, **kwargs)[source]¶

Write JSON log file.

Parameters:

data (Iterable[Model]) – Log records as an Iterable of Model per line.
file (TextIOWrapper) – Log file object opened in text mode.
writer (Optional[Type[JSONWriter]]) – Writer class.
encoder (Optional[Type[JSONEncoder]]) – JSON encoder class.
*args (Any) – Arbitrary positional arguments.
**kwargs (Any) – Arbitrary keyword arguments.

Return type:

Predefined Dumpers¶

class zlogging.dumper.ASCIIWriter(separator=None, empty_field=None, unset_field=None, set_separator=None)[source]¶

Bases: BaseWriter

ASCII log writer.

Parameters:

separator (Union[str, bytes, None]) – Field separator when writing log lines.
empty_field (Union[str, bytes, None]) – Placeholder for empty field.
unset_field (Union[str, bytes, None]) – Placeholder for unset field.
set_separator (Union[str, bytes, None]) – Separator for set/vector fields.

property format: str¶: Log file format.

separator: bytes¶: Field separator when writing log lines.

empty_field: bytes¶: Placeholder for empty field.

unset_field: bytes¶: Placeholder for unset field.

set_separator: bytes¶: Separator for set/vector fields.

write_file(file, data)[source]¶

Write log file.

Parameters:

file (TextIOWrapper) – Log file object opened in text mode.
data (Iterable[Model]) – Log records as an Iterable of Model per line.

Return type:

Returns:

The file offset after writing.

write_line(file, data, lineno=0)[source]¶

Write log line as one-line record.

Parameters:

file (TextIOWrapper) – Log file object opened in text mode.
data (Model) – Log record.
lineno (Optional[int]) – Line number of current line.

Return type:

Returns:

The file offset after writing.

Raises:

ASCIIWriterError – If failed to serialise data as ASCII.

write_head(file, data=None)[source]¶

Write header fields of ASCII log file.

Parameters:

file (TextIOWrapper) – Log file object opened in text mode.
data (Optional[Model]) – Log record.

Return type:

Returns:

The file offset after writing.

write_tail(file)[source]¶

Write trailing fields of ASCII log file.

Parameters:: file (TextIOWrapper) – Log file object opened in text mode.
Return type:: int
Returns:: The file offset after writing.

dump_file(data=None, name=None)[source]¶

Serialise records to a log line.

Parameters:

data (Optional[Iterable[Model]]) – Log records as an Iterable of Model per line.
name (Optional[str]) – Log file name.

Return type:

Returns:

The converted log string.

dump_line(data, lineno=0)[source]¶

Serialise one-line record to a log line.

Parameters:

data (Model) – Log record.
lineno (Optional[int]) – Line number of current line.

Return type:

Returns:

The converted log string.

Raises:

ASCIIWriterError – If failed to serialise data as ASCII.

dump_head(data=None, name=None)[source]¶

Serialise header fields of ASCII log file.

Parameters:

data (Optional[Model]) – Log record.
name (Optional[str]) – Log file name.

Return type:

Returns:

The converted log string.

dump_tail()[source]¶

Serialise trailing fields of ASCII log file.

Return type:: str
Returns:: The converted log string.

class zlogging.dumper.JSONWriter(encoder=None)[source]¶

Bases: BaseWriter

JSON log writer.

Parameters:: encoder (Optional[Type[JSONEncoder]]) – JSON encoder class.

property format: Literal['json']¶: Log file format.

encoder: Type[JSONEncoder]¶: JSON encoder class.

write_file(file, data)[source]¶

Write log file.

Parameters:

file (TextIOWrapper) – Log file object opened in text mode.
data (Iterable[Model]) – Log records as an Iterable of Model per line.

Return type:

Returns:

The file offset after writing.

write_line(file, data, lineno=0)[source]¶

Write log line as one-line record.

Parameters:

file (TextIOWrapper) – Log file object opened in text mode.
data (Model) – Log record.
lineno (Optional[int]) – Line number of current line.

Return type:

Returns:

The file offset after writing.

Raises:

JSONWriterError – If failed to serialise data as JSON.

dump_file(data=None)[source]¶

Serialise records to a log line.

Parameters:: data (Optional[Iterable[Model]]) – Log records as an Iterable of Model per line.
Return type:: str
Returns:: The converted log string.

dump_line(data, lineno=0)[source]¶

Serialise one-line record to a log line.

Parameters:

data (Model) – Log record.
lineno (Optional[int]) – Line number of current line.

Return type:

Returns:

The converted log string.

Raises:

JSONWriterError – If failed to serialise data as JSON.

Abstract Base Dumper¶

class zlogging.dumper.BaseWriter[source]¶

Bases: object

Basic log writer.

abstract property format: str¶: Log file format.

write(filename, data)[source]¶

Write log file.

Parameters:

filename (PathLike[str]) – Log file name.
data (Iterable[Model]) – Log records as an Iterable of Model per line.

Return type:

Returns:

The file offset after writing.

abstract write_file(file, data)[source]¶

Write log file.

Parameters:

file (TextIOWrapper) – Log file object opened in text mode.
data (Iterable[Model]) – Log records as an Iterable of Model per line.

Return type:

Returns:

The file offset after writing.

abstract write_line(file, data, lineno=0)[source]¶

Write log line as one-line record.

Parameters:

file (TextIOWrapper) – Log file object opened in text mode.
data (Model) – Log record.
lineno (Optional[int]) – Line number of current line.

Return type:

Returns:

The file offset after writing.

abstract dump_file(data)[source]¶

Serialise records to a log line.

Parameters:: data (Iterable[Model]) – Log records as an Iterable of Model per line.
Return type:: str
Returns:: The converted log string.

abstract dump_line(data, lineno=0)[source]¶

Serialise one-line record to a log line.

Parameters:

data (Model) – Log record.
lineno (Optional[int]) – Line number of current line.

Return type:

Returns:

The converted log string.

dump(data, file)[source]¶

Write log file.

Parameters:

data (Iterable[Model]) – Log records as an Iterable of Model per line.
file (TextIOWrapper) – Log file object opened in text mode.

Return type: