base/frameworks/logging/writers/ascii.zeek

LogAscii

Interface for the ASCII log writer. Redefinable options are available to tweak the output format of ASCII logs.

The ASCII writer currently supports one writer-specific per-filter config option: setting tsv to the string T turns the output into “tab-separated-value” mode where only a single header row with the column names is printed out as meta information, with no “# fields” prepended; no other meta data gets included in that mode. Example filter using this:

local f: Log::Filter = [$name = "my-filter",
                        $writer = Log::WRITER_ASCII,
                        $config = table(["tsv"] = "T")];
Namespace

LogAscii

Summary

Redefinable Options

LogAscii::empty_field: string &redef

String to use for empty fields.

LogAscii::enable_leftover_log_rotation: bool &redef

If true, detect log files that did not get properly rotated by a previous Zeek process (e.g.

LogAscii::enable_utf_8: bool &redef

If true, valid UTF-8 sequences will pass through unescaped and be written into logs.

LogAscii::gzip_file_extension: string &redef

Define the file extension used when compressing log files when they are created with the LogAscii::gzip_level option.

LogAscii::gzip_level: count &redef

Define the gzip level to compress the logs.

LogAscii::include_meta: bool &redef

If true, include lines with log meta information such as column names with types, the values of ASCII logging options that are in use, and the time when the file was opened and closed (the latter at the end).

LogAscii::json_include_unset_fields: bool &redef

Handling of optional fields when writing out JSON.

LogAscii::json_timestamps: JSON::TimestampFormat &redef

Format of timestamps when writing out JSON.

LogAscii::logdir: string &redef &deprecated =

Define the default logging directory.

LogAscii::meta_prefix: string &redef

Prefix for lines with meta information.

LogAscii::output_to_stdout: bool &redef

If true, output everything to stdout rather than into files.

LogAscii::separator: string &redef

Separator between fields.

LogAscii::set_separator: string &redef

Separator between set elements.

LogAscii::unset_field: string &redef

String to use for an unset &optional field.

LogAscii::use_json: bool &redef

If true, the default will be to write logs in a JSON format.

Detailed Interface

Redefinable Options

LogAscii::empty_field
Type

string

Attributes

&redef

Default

"(empty)"

String to use for empty fields. This should be different from unset_field to make the output unambiguous.

This option is also available as a per-filter $config option.

LogAscii::enable_leftover_log_rotation
Type

bool

Attributes

&redef

Default

F

If true, detect log files that did not get properly rotated by a previous Zeek process (e.g. due to crash) and rotate them.

This requires a positive rotation interval to be configured to have an effect. E.g. via Log::default_rotation_interval or the interv field of a Log::Filter.

LogAscii::enable_utf_8
Type

bool

Attributes

&redef

Default

T

If true, valid UTF-8 sequences will pass through unescaped and be written into logs.

This option is also available as a per-filter $config option.

LogAscii::gzip_file_extension
Type

string

Attributes

&redef

Default

"gz"

Define the file extension used when compressing log files when they are created with the LogAscii::gzip_level option.

This option is also available as a per-filter $config option.

LogAscii::gzip_level
Type

count

Attributes

&redef

Default

0

Define the gzip level to compress the logs. If 0, then no gzip compression is performed. Enabling compression also changes the log file name extension to include the value of LogAscii::gzip_file_extension.

This option is also available as a per-filter $config option.

LogAscii::include_meta
Type

bool

Attributes

&redef

Default

T

If true, include lines with log meta information such as column names with types, the values of ASCII logging options that are in use, and the time when the file was opened and closed (the latter at the end).

If writing in JSON format, this is implicitly disabled.

LogAscii::json_include_unset_fields
Type

bool

Attributes

&redef

Default

F

Handling of optional fields when writing out JSON. By default the JSON formatter skips key and val when the field is absent. Setting the following field to T includes the key, with a null value.

LogAscii::json_timestamps
Type

JSON::TimestampFormat

Attributes

&redef

Default

JSON::TS_EPOCH

Format of timestamps when writing out JSON. By default, the JSON formatter will use double values for timestamps which represent the number of seconds from the UNIX epoch.

This option is also available as a per-filter $config option.

LogAscii::logdir
Type

string

Attributes

&redef &deprecated = “Remove in v6.1. Use ‘Log::default_logdir’.”

Default

""

Define the default logging directory. If empty, logs are written to the current working directory.

This setting is superseded by Log::default_logdir. The latter applies to all file writers and also interacts better with log rotation.

LogAscii::meta_prefix
Type

string

Attributes

&redef

Default

"#"

Prefix for lines with meta information.

This option is also available as a per-filter $config option.

LogAscii::output_to_stdout
Type

bool

Attributes

&redef

Default

F

If true, output everything to stdout rather than into files. This is primarily for debugging purposes.

This option is also available as a per-filter $config option.

LogAscii::separator
Type

string

Attributes

&redef

Default

"\x09"

Separator between fields.

This option is also available as a per-filter $config option.

LogAscii::set_separator
Type

string

Attributes

&redef

Default

","

Separator between set elements.

This option is also available as a per-filter $config option.

LogAscii::unset_field
Type

string

Attributes

&redef

Default

"-"

String to use for an unset &optional field.

This option is also available as a per-filter $config option.

LogAscii::use_json
Type

bool

Attributes

&redef

Default

F

Redefinition

from policy/tuning/json-logs.zeek

=:

T

If true, the default will be to write logs in a JSON format.

This option is also available as a per-filter $config option.