Log Dumpers

Functional Interfaces

General APIs

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

Write Bro/Zeek log file.

Parameters:
Raises:

WriterFormatError – If format is not supported.

Return type:

None

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

Write Bro/Zeek log string.

Parameters:
Raises:

WriterFormatError – If format is not supported.

Return type:

str

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

Write Bro/Zeek log file.

Parameters:
Raises:

WriterFormatError – If format is not supported.

Return type:

None

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

  • filename – Log file name.

  • writer – Writer class.

  • separator – Field separator when writing log lines.

  • empty_field – Placeholder for empty field.

  • unset_field – Placeholder for unset field.

  • set_separator – Separator for set/vector fields.

  • *args – Arbitrary positional arguments.

  • **kwargs – Arbitrary keyword arguments.

Return type:

None

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:
Return type:

str

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:
Return type:

None

JSON Format

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

Write JSON log file.

Parameters:
  • data – Log records as an Iterable of Model per line.

  • filename – Log file name.

  • writer – Writer class.

  • encoder – JSON encoder class.

  • *args – Arbitrary positional arguments.

  • **kwargs – Arbitrary keyword arguments.

Return type:

None

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

Write JSON log string.

Parameters:
Return type:

str

Returns:

The JSON log string.

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

Write JSON log file.

Parameters:
Return type:

None

Predefined Dumpers

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

Bases: BaseWriter

ASCII log writer.

Parameters:
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:
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 (TextIOWrapper) – 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:

ASCIIWriterError – If failed to serialise data as ASCII.

write_head(file, data=None)[source]

Write header fields of ASCII log file.

Parameters:
Return type:

int

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:
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:
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(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:
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 (TextIOWrapper) – 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 (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:

str

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 – Log file name.

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

Returns:

The file offset after writing.

Return type:

int

abstract write_file(file, data)[source]

Write log file.

Parameters:
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 (TextIOWrapper) – 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[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:
Return type:

int

Returns:

The file offset after writing.

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