Log Dumpers¶

Functional Interfaces¶

General APIs¶

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

Write Bro/Zeek log file.

Parameters

data (Iterable[Model]) – Log records as an Iterable of Model per line.
filename (PathLike[str]) – Log file name.
format (str) – Log format.
*args (Any) – See write_json() and write_ascii() for more information.
**kwargs (Any) – See write_json() and write_ascii() for more information.

Raises

WriterFormatError – If format is not supported.

Return type

None

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

Return type

str

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

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 (Iterable[Model]) – Log records as an Iterable of Model per line.
filename (PathLike[str]) – Log file name.
writer (Optional[Type[ASCIIWriter]]) – Writer class.
separator (Optional[AnyStr]) – Field separator when writing log lines.
empty_field (Optional[AnyStr]) – Placeholder for empty field.
unset_field (Optional[AnyStr]) – Placeholder for unset field.
set_separator (Optional[AnyStr]) – Separator for set/vector fields.
*args (Any) – Arbitrary positional arguments.
**kwargs (Any) – 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

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

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

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

Return type

None

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

None

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

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

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

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

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.

Return type: str

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

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

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

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

data (Optional[Iterable[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 (Optional[Model]) – 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(encoder=None)[source]¶

Bases: BaseWriter

JSON log writer.

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

property format: Literal['json']¶

Log file format.

Return type: Literal[‘json’]

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

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.

Return type: str

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.

Returns

The file offset after writing.

Return type

int

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

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

data (Iterable[Model]) – Log records as an Iterable of Model per line.
file (TextIOWrapper) – 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[Model]) – Log records as an Iterable of Model per line.
Return type: str
Returns: The converted log string.

Log Dumpers¶

Functional Interfaces¶

General APIs¶

ASCII Format¶

JSON Format¶

Predefined Dumpers¶

Abstract Base Dumper¶

ZLogging

Navigation

Related Topics