:tocdepth: 3

base/frameworks/logging/writers/ascii.zeek
==========================================
.. zeek:namespace:: 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
###################
===================================================================================================== =====================================================================
:zeek:id:`LogAscii::empty_field`: :zeek:type:`string` :zeek:attr:`&redef`                             String to use for empty fields.
:zeek:id:`LogAscii::enable_leftover_log_rotation`: :zeek:type:`bool` :zeek:attr:`&redef`              If true, detect log files that did not get properly rotated
                                                                                                      by a previous Zeek process (e.g.
:zeek:id:`LogAscii::enable_utf_8`: :zeek:type:`bool` :zeek:attr:`&redef`                              If true, valid UTF-8 sequences will pass through unescaped and be
                                                                                                      written into logs.
:zeek:id:`LogAscii::gzip_file_extension`: :zeek:type:`string` :zeek:attr:`&redef`                     Define the file extension used when compressing log files when
                                                                                                      they are created with the :zeek:see:`LogAscii::gzip_level` option.
:zeek:id:`LogAscii::gzip_level`: :zeek:type:`count` :zeek:attr:`&redef`                               Define the gzip level to compress the logs.
:zeek:id:`LogAscii::include_meta`: :zeek:type:`bool` :zeek:attr:`&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).
:zeek:id:`LogAscii::json_include_unset_fields`: :zeek:type:`bool` :zeek:attr:`&redef`                 Handling of optional fields when writing out JSON.
:zeek:id:`LogAscii::json_timestamps`: :zeek:type:`JSON::TimestampFormat` :zeek:attr:`&redef`          Format of timestamps when writing out JSON.
:zeek:id:`LogAscii::logdir`: :zeek:type:`string` :zeek:attr:`&redef` :zeek:attr:`&deprecated` = *...* Define the default logging directory.
:zeek:id:`LogAscii::meta_prefix`: :zeek:type:`string` :zeek:attr:`&redef`                             Prefix for lines with meta information.
:zeek:id:`LogAscii::output_to_stdout`: :zeek:type:`bool` :zeek:attr:`&redef`                          If true, output everything to stdout rather than
                                                                                                      into files.
:zeek:id:`LogAscii::separator`: :zeek:type:`string` :zeek:attr:`&redef`                               Separator between fields.
:zeek:id:`LogAscii::set_separator`: :zeek:type:`string` :zeek:attr:`&redef`                           Separator between set elements.
:zeek:id:`LogAscii::unset_field`: :zeek:type:`string` :zeek:attr:`&redef`                             String to use for an unset &optional field.
:zeek:id:`LogAscii::use_json`: :zeek:type:`bool` :zeek:attr:`&redef`                                  If true, the default will be to write logs in a JSON format.
===================================================================================================== =====================================================================


Detailed Interface
~~~~~~~~~~~~~~~~~~
Redefinable Options
###################
.. zeek:id:: LogAscii::empty_field
   :source-code: base/frameworks/logging/writers/ascii.zeek 103 103

   :Type: :zeek:type:`string`
   :Attributes: :zeek:attr:`&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.

.. zeek:id:: LogAscii::enable_leftover_log_rotation
   :source-code: base/frameworks/logging/writers/ascii.zeek 35 35

   :Type: :zeek:type:`bool`
   :Attributes: :zeek:attr:`&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 :zeek:see:`Log::default_rotation_interval`
   or the *interv* field of a :zeek:see:`Log::Filter`.

.. zeek:id:: LogAscii::enable_utf_8
   :source-code: base/frameworks/logging/writers/ascii.zeek 41 41

   :Type: :zeek:type:`bool`
   :Attributes: :zeek:attr:`&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.

.. zeek:id:: LogAscii::gzip_file_extension
   :source-code: base/frameworks/logging/writers/ascii.zeek 55 55

   :Type: :zeek:type:`string`
   :Attributes: :zeek:attr:`&redef`
   :Default: ``"gz"``

   Define the file extension used when compressing log files when
   they are created with the :zeek:see:`LogAscii::gzip_level` option.
   
   This option is also available as a per-filter ``$config`` option.

.. zeek:id:: LogAscii::gzip_level
   :source-code: base/frameworks/logging/writers/ascii.zeek 49 49

   :Type: :zeek:type:`count`
   :Attributes: :zeek:attr:`&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
   :zeek:see:`LogAscii::gzip_file_extension`.
   
   This option is also available as a per-filter ``$config`` option.

.. zeek:id:: LogAscii::include_meta
   :source-code: base/frameworks/logging/writers/ascii.zeek 82 82

   :Type: :zeek:type:`bool`
   :Attributes: :zeek:attr:`&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.

.. zeek:id:: LogAscii::json_include_unset_fields
   :source-code: base/frameworks/logging/writers/ascii.zeek 75 75

   :Type: :zeek:type:`bool`
   :Attributes: :zeek:attr:`&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.

.. zeek:id:: LogAscii::json_timestamps
   :source-code: base/frameworks/logging/writers/ascii.zeek 70 70

   :Type: :zeek:type:`JSON::TimestampFormat`
   :Attributes: :zeek:attr:`&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.

.. zeek:id:: LogAscii::logdir
   :source-code: base/frameworks/logging/writers/ascii.zeek 63 63

   :Type: :zeek:type:`string`
   :Attributes: :zeek:attr:`&redef` :zeek:attr:`&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 :zeek:see:`Log::default_logdir`. The
   latter applies to all file writers and also interacts better with
   log rotation.

.. zeek:id:: LogAscii::meta_prefix
   :source-code: base/frameworks/logging/writers/ascii.zeek 87 87

   :Type: :zeek:type:`string`
   :Attributes: :zeek:attr:`&redef`
   :Default: ``"#"``

   Prefix for lines with meta information.
   
   This option is also available as a per-filter ``$config`` option.

.. zeek:id:: LogAscii::output_to_stdout
   :source-code: base/frameworks/logging/writers/ascii.zeek 22 22

   :Type: :zeek:type:`bool`
   :Attributes: :zeek:attr:`&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.

.. zeek:id:: LogAscii::separator
   :source-code: base/frameworks/logging/writers/ascii.zeek 92 92

   :Type: :zeek:type:`string`
   :Attributes: :zeek:attr:`&redef`
   :Default: ``"\x09"``

   Separator between fields.
   
   This option is also available as a per-filter ``$config`` option.

.. zeek:id:: LogAscii::set_separator
   :source-code: base/frameworks/logging/writers/ascii.zeek 97 97

   :Type: :zeek:type:`string`
   :Attributes: :zeek:attr:`&redef`
   :Default: ``","``

   Separator between set elements.
   
   This option is also available as a per-filter ``$config`` option.

.. zeek:id:: LogAscii::unset_field
   :source-code: base/frameworks/logging/writers/ascii.zeek 108 108

   :Type: :zeek:type:`string`
   :Attributes: :zeek:attr:`&redef`
   :Default: ``"-"``

   String to use for an unset &optional field.
   
   This option is also available as a per-filter ``$config`` option.

.. zeek:id:: LogAscii::use_json
   :source-code: base/frameworks/logging/writers/ascii.zeek 27 27

   :Type: :zeek:type:`bool`
   :Attributes: :zeek:attr:`&redef`
   :Default: ``F``
   :Redefinition: from :doc:`/scripts/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.