Dumpers

Predefined Dumpers

Bro/Zeek log dumper.

class zlogging.dumper.JSONWriter

Bases: zlogging.dumper.BaseWriter

JSON log writer.

property format

str: Log file format.

write_file(file, data)

Write log file.

Parameters

• file (_io.TextIOWrapper) – Log file object opened in text mode.

• data (Iterable of Model) – Log records as an Iterable of Model per line.

Returns

The file offset after writing.

Return type

int

write_line(file, data, lineno=0)

Write log line as one-line record.

Parameters

• file (_io.TextIOWrapper) – Log file object opened in text mode.

• data (Model) – Log record.

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

Returns

The file offset after writing.

Raises

JSONWriterError – If failed to serialise data as JSON.

Return type

int

dump_file(data)

Serialise records to a log line.

Parameters

data (Iterable of Model) – Log records as an Iterable of Model per line.

Returns

The converted log string.

Return type

str

dump_line(data, lineno=0)

Serialise one-line record to a log line.

Parameters

• data (Model) – Log record.

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

Returns

The converted log string.

Raises

JSONWriterError – If failed to serialise data as JSON.

Return type

str

class zlogging.dumper.ASCIIWriter(separator=None, empty_field=None, unset_field=None, set_separator=None)

Bases: zlogging.dumper.BaseWriter

ASCII log writer.

Parameters

• separator (str or bytes, optional) – Field separator when writing log lines.

• empty_field (bytes or str, optional) – Placeholder for empty field.

• unset_field (bytes or str, optional) – Placeholder for unset field.

• set_separator (bytes or str, optional) – Separator for set/vector fields.

Variables

• separator (bytes) – Field separator when writing log lines.

• str_separator (str) – Field separator when writing log lines.

• empty_field (bytes) – Placeholder for empty field.

• str_empty_field (str) – Placeholder for empty field.

• unset_field (bytes) – Placeholder for unset field.

• str_unset_field (str) – Placeholder for unset field.

• set_separator (bytes) – Separator for set/list fields.

• str_set_separator (str) – Separator for set/list fields.

property format

str: Log file format.

write_file(file, data)

Write log file.

Parameters

• file (_io.TextIOWrapper) – Log file object opened in text mode.

• data (Iterable of Model) – Log records as an Iterable of Model per line.

Returns

The file offset after writing.

Return type

int

write_line(file, data, lineno=0)

Write log line as one-line record.

Parameters

• file (_io.TextIOWrapper) – Log file object opened in text mode.

• data (Model) – Log record.

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

Returns

The file offset after writing.

Raises

ASCIIWriterError – If failed to serialise data as ASCII.

Return type

int

write_head(file, data=None)

Write header fields of ASCII log file.

Parameters

• file (_io.TextIOWrapper) – Log file object opened in text mode.

• data (Model, optional) – Log record.

Returns

The file offset after writing.

Return type

int

write_tail(file)

Write trailing fields of ASCII log file.

Parameters

file (_io.TextIOWrapper) – Log file object opened in text mode.

Returns

The file offset after writing.

Return type

int

dump_file(data, name=None)

Serialise records to a log line.

Parameters

• data (Iterable of Model) – Log records as an Iterable of Model per line.

• name (Optional[str]) – Log file name.

Returns

The converted log string.

Return type

str

dump_line(data, lineno=0)

Serialise one-line record to a log line.

Parameters

• data (Model) – Log record.

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

Returns

The converted log string.

Raises

ASCIIWriterError – If failed to serialise data as ASCII.

Return type

str

dump_head(data=None, name=None)

Serialise header fields of ASCII log file.

Parameters

• data (Model, optional) – Log record.

• name (Optional[str]) – Log file name.

Returns

The converted log string.

Return type

str

dump_tail()

Serialise trailing fields of ASCII log file.

Returns

The converted log string.

Return type

str

zlogging.dumper.write_json(data, filename, writer=None, *args, **kwargs)

Write JSON log file.

Parameters

• data (Iterable of Model) – Log records as an Iterable of Model per line.

• filename (os.PathLike) – Log file name.

• writer (JSONWriter, optional) – Writer class.

• *args – Variable length argument list.

• **kwargs – Arbitrary keyword arguments.

zlogging.dumper.dump_json(data, file, writer=None, *args, **kwargs)

Write JSON log file.

Parameters

• data (Iterable of Model) – Log records as an Iterable of Model per line.

• file (_io.TextIOWrapper) – Log file object opened in text mode.

• writer (JSONWriter, optional) – Writer class.

• *args – Variable length argument list.

• **kwargs – Arbitrary keyword arguments.

zlogging.dumper.dumps_json(data=None, writer=None, *args, **kwargs)

Write JSON log string.

Parameters

• data (Iterable of Model) – Log records as an Iterable of Model per line.

• writer (JSONWriter, optional) – Writer class.

• *args – Variable length argument list.

• **kwargs – Arbitrary keyword arguments.

Returns

The JSON log string.

Return type

str

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

Write ASCII log file.

Parameters

• data (Iterable of Model) – Log records as an Iterable of Model per line.

• filename (os.PathLike) – Log file name.

• writer (ASCIIWriter, optional) – Writer class.

• separator (str or bytes, optional) – Field separator when writing log lines.

• empty_field (bytes or str, optional) – Placeholder for empty field.

• unset_field (bytes or str, optional) – Placeholder for unset field.

• set_separator (bytes or str, optional) – Separator for set/vector fields.

• *args – Variable length argument list.

• **kwargs – Arbitrary keyword arguments.

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

Write ASCII log file.

Parameters

• data (Iterable of Model) – Log records as an Iterable of Model per line.

• file (_io.TextIOWrapper) – Log file object opened in text mode.

• writer (ASCIIWriter, optional) – Writer class.

• separator (str or bytes, optional) – Field separator when writing log lines.

• empty_field (bytes or str, optional) – Placeholder for empty field.

• unset_field (bytes or str, optional) – Placeholder for unset field.

• set_separator (bytes or str, optional) – Separator for set/vector fields.

• *args – Variable length argument list.

• **kwargs – Arbitrary keyword arguments.

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

Write ASCII log string.

Parameters

• data (Iterable of Model) – Log records as an Iterable of Model per line.

• writer (ASCIIWriter, optional) – Writer class.

• separator (str or bytes, optional) – Field separator when writing log lines.

• empty_field (bytes or str, optional) – Placeholder for empty field.

• unset_field (bytes or str, optional) – Placeholder for unset field.

• set_separator (bytes or str, optional) – Separator for set/vector fields.

• *args – Variable length argument list.

• **kwargs – Arbitrary keyword arguments.

Returns

The JSON log string.

Return type

str

zlogging.dumper.write(data, filename, format, *args, **kwargs)

Write Bro/Zeek log file.

Parameters

• data (Iterable of Model) – Log records as an Iterable of Model per line.

• filename (os.PathLike) – Log file name.

• format (str) – Log format.

• *args – See write_json() and write_ascii() for more information.

• **kwargs – See write_json() and write_ascii() for more information.

Raises

WriterFormatError – If format is not supported.

zlogging.dumper.dump(data, file, format, *args, **kwargs)

Write Bro/Zeek log file.

Parameters

• data (Iterable of Model) – Log records as an Iterable of Model per line.

• format (str) – Log format.

• file (_io.TextIOWrapper) – Log file object opened in text mode.

• *args – See dump_json() and dump_ascii() for more information.

• **kwargs – See dump_json() and dump_ascii() for more information.

Raises

WriterFormatError – If format is not supported.

zlogging.dumper.dumps(data, format, *args, **kwargs)

Write Bro/Zeek log string.

Parameters

• data (Iterable of Model) – Log records as an Iterable of Model per line.

• format (str) – Log format.

• *args – See dumps_json() and dumps_ascii() for more information.

• **kwargs – See dumps_json() and dumps_ascii() for more information.

Raises

WriterFormatError – If format is not supported.

Abstract Base Dumpers

class zlogging.dumper.BaseWriter

Bases: object

Basic log writer.

abstract property format

str: Log file format.

write(filename, data)

Write log file.

Parameters

• filename (os.PathLike) – Log file name.

• data (Iterable of Model) – Log records as an Iterable of Model per line.

Returns

The file offset after writing.

Return type

int

abstract write_file(file, data)

Write log file.

Parameters

• file (_io.TextIOWrapper) – Log file object opened in text mode.

• data (Iterable of Model) – Log records as an Iterable of Model per line.

Returns

The file offset after writing.

Return type

int

abstract write_line(file, data, lineno=0)

Write log line as one-line record.

Parameters

• file (_io.TextIOWrapper) – Log file object opened in text mode.

• data (Model) – Log record.

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

Returns

The file offset after writing.

Return type

int

abstract dump_file(data)

Serialise records to a log line.

Parameters

data (Iterable of Model) – Log records as an Iterable of Model per line.

Returns

The converted log string.

Return type

str

abstract dump_line(data, lineno=0)

Serialise one-line record to a log line.

Parameters

• data (Model) – Log record.

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

Returns

The converted log string.

Return type

str

dump(data, file)

Write log file.

Parameters

• data (Iterable of Model) – Log records as an Iterable of Model per line.

• file (_io.TextIOWrapper) – Log file object opened in text mode.

Returns

The file offset after writing.

Return type

int

dumps(data)

Serialise records to a log line.

Parameters

data (Iterable of Model) – Log records as an Iterable of Model per line.

Returns

The converted log string.

Return type

str