Dumpers

Predefined Dumpers

Bro/Zeek log dumper.

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

Write Bro/Zeek log file.

Parameters

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

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

  • format (str) – Log format.

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

  • args (Any) –

  • kwargs (Any) –

Keyword Arguments

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

Raises

WriterFormatError – If format is not supported.

Return type

None

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 of Model) – Log records as an Iterable of Model per line.

  • filename (PathLike[str]) – 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.

  • args (Any) –

  • kwargs (Any) –

Keyword Arguments

**kwargs – Arbitrary keyword arguments.

Return type

None

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

Write JSON log file.

Parameters

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

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

  • writer (JSONWriter, optional) – Writer class.

  • *args – Variable length argument list.

  • args (Any) –

  • kwargs (Any) –

Keyword Arguments

**kwargs – Arbitrary keyword arguments.

Return type

None

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

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.

  • args (Any) –

  • kwargs (Any) –

Keyword Arguments

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

Raises

WriterFormatError – If format is not supported.

Return type

str

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

  • args (Any) –

  • kwargs (Any) –

Return type

str

Returns

The JSON log string.

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

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.

  • args (Any) –

  • kwargs (Any) –

Keyword Arguments

**kwargs – Arbitrary keyword arguments.

Return type

str

Returns

The JSON log string.

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

Write Bro/Zeek log file.

Parameters

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

  • format (str) – Log format.

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

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

  • args (Any) –

  • kwargs (Any) –

Keyword Arguments

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

Raises

WriterFormatError – If format is not supported.

Return type

None

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 of Model) – Log records as an Iterable of Model per line.

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

  • args (Any) –

  • kwargs (Any) –

Keyword Arguments

**kwargs – Arbitrary keyword arguments.

Return type

None

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

Write JSON log file.

Parameters

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

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

  • writer (JSONWriter, optional) – Writer class.

  • *args – Variable length argument list.

  • args (Any) –

  • kwargs (Any) –

Keyword Arguments

**kwargs – Arbitrary keyword arguments.

Return type

None

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

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

Log file format.

Type

str

Return type

str

write_file(file, data)[source]

Write log file.

Parameters

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

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

Return type

int

Returns

The file offset after writing.

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

Write log line as one-line record.

Args:

file: Log file object opened in text mode. data (Model): Log record. lineno: Line number of current line.

Returns:

The file offset after writing.

Raises:

ASCIIWriterError: If failed to serialise data as ASCII.

w

Return type

int

Parameters

  • file (TextFile) –

  • data (Model) –

  • lineno (Optional[int]) –

write_head(file, data=None)[source]

Write header fields of ASCII log file.

Parameters

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

  • data (Model, optional) – Log record.

Return type

int

Returns

The file offset after writing.

write_tail(file)[source]

Write trailing fields of ASCII log file.

Parameters

file (TextFile) – 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 (Iterable of Model) – Log records as an Iterable of Model per line.

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

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

str

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 (Model, optional) – Log record.

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

Return type

str

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

Bases: zlogging.dumper.BaseWriter

JSON log writer.

property format

Log file format.

Type

str

Return type

Literal[“json”]

write_file(file, data)[source]

Write log file.

Parameters

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

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

Return type

int

Returns

The file offset after writing.

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

Write log line as one-line record.

Parameters

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

  • data (Model) – Log record.

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

Return type

int

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 (Iterable of 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

str

Returns

The converted log string.

Raises

JSONWriterError – If failed to serialise data as JSON.

Abstract Base Dumpers

class zlogging.dumper.BaseWriter[source]

Bases: object

Basic log writer.

abstract property format

Log file format.

Type

str

Return type

str

write(filename, data)[source]

Write log file.

Parameters

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

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

Return type

int

Returns

The file offset after writing.

abstract write_file(file, data)[source]

Write log file.

Parameters

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

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

Return type

int

Returns

The file offset after writing.

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

Write log line as one-line record.

Parameters

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

  • data (Model) – Log record.

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

Return type

int

Returns

The file offset after writing.

abstract dump_file(data)[source]

Serialise records to a log line.

Parameters

data (Iterable of 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

str

Returns

The converted log string.

dump(data, file)[source]

Write log file.

Parameters

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

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

Return type

int

Returns

The file offset after writing.

dumps(data)[source]

Serialise records to a log line.

Parameters

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

Return type

str

Returns

The converted log string.