mirror of
https://github.com/zrepl/zrepl.git
synced 2024-11-24 17:35:01 +01:00
docs: adjust logging to rst
This commit is contained in:
Christian Schwarz
parent
6f7b8ca1af
commit
828c2982f3
@ -1,3 +1,4 @@
|
||||
.. include:: ../global.rst.inc
|
||||
.. _conf-logging:
|
||||
|
||||
Logging
|
||||
@ -5,11 +6,8 @@ Logging
|
||||
|
||||
zrepl uses structured logging to provide users with easily processable log messages.
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
Logging outlets are configured in the `global` section of the [configuration file]({{< relref "install/_index.md#configuration-files" >}}).<br />
|
||||
Check out {{< sampleconflink "random/logging.yml" >}} for an example on how to configure multiple outlets:
|
||||
Logging outlets are configured in the ``global`` section of the |mainconfig|.
|
||||
Check out :sampleconf:`random/logging.yml` for an example on how to configure multiple outlets:
|
||||
|
||||
::
|
||||
|
||||
@ -29,7 +27,7 @@ Check out {{< sampleconflink "random/logging.yml" >}} for an example on how to c
|
||||
jobs: ...
|
||||
|
||||
Default Configuration
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
---------------------
|
||||
|
||||
By default, the following logging configuration is used
|
||||
|
||||
@ -43,7 +41,7 @@ By default, the following logging configuration is used
|
||||
format: "human"
|
||||
|
||||
.. ATTENTION::
|
||||
Output to **stderr** should always be considered a **critical error**.<br />
|
||||
Output to **stderr** should always be considered a **critical error**.
|
||||
Only errors in the logging infrastructure itself, e.g. IO errors when writing to an outlet, are sent to stderr.
|
||||
|
||||
Building Blocks
|
||||
@ -51,100 +49,143 @@ Building Blocks
|
||||
|
||||
The following sections document the semantics of the different log levels, formats and outlet types.
|
||||
|
||||
.. _logging-levels:
|
||||
|
||||
Levels
|
||||
~~~~~~
|
||||
|
||||
::
|
||||
.. list-table::
|
||||
:widths: 10 10 80
|
||||
:header-rows: 1
|
||||
|
||||
| Level | SHORT | Description |
|
||||
|-------|-------|-------------|
|
||||
|`error`|`ERRO` | immediate action required |
|
||||
|`warn` |`WARN` | symptoms for misconfiguration, soon expected failure, etc.|
|
||||
|`info` |`INFO` | explains what happens without too much detail |
|
||||
|`debug`|`DEBG` | tracing information, state dumps, etc. useful for debugging. |
|
||||
* - Level
|
||||
- SHORT
|
||||
- Description
|
||||
* - ``error``
|
||||
- ``ERRO``
|
||||
- immediate action required
|
||||
* - ``warn``
|
||||
- ``WARN``
|
||||
- symptoms for misconfiguration, soon expected failure, etc.
|
||||
* - ``info``
|
||||
- ``INFO``
|
||||
- explains what happens without too much detail
|
||||
* - ``debug``
|
||||
- ``DEBG``
|
||||
- tracing information, state dumps, etc. useful for debugging.
|
||||
|
||||
Incorrectly classified messages are considered a bug and should be reported.
|
||||
|
||||
.. _logging-formats:
|
||||
|
||||
Formats
|
||||
~~~~~~~
|
||||
|
||||
::
|
||||
.. list-table::
|
||||
:widths: 10 90
|
||||
:header-rows: 1
|
||||
|
||||
| Format | Description |
|
||||
|--------|---------|
|
||||
|`human` | emphasized context by putting job, task, step and other context variables into brackets before the actual message, followed by remaining fields in logfmt style|
|
||||
|`logfmt`| [logfmt](https://brandur.org/logfmt) output. zrepl uses [github.com/go-logfmt/logfmt](github.com/go-logfmt/logfmt).|
|
||||
|`json` | JSON formatted output. Each line is a valid JSON document. Fields are marshaled by `encoding/json.Marshal()`, which is particularly useful for processing in log aggregation or when processing state dumps.
|
||||
|
||||
Outlets
|
||||
~~~~~~~
|
||||
* - Format
|
||||
- Description
|
||||
* - ``human``
|
||||
- emphasizes context by putting job, task, step and other context variables into brackets
|
||||
before the actual message, followed by remaining fields in logfmt style|
|
||||
* - ``logfmt``
|
||||
- `logfmt <https://brandur.org/logfmt>`_ output. zrepl uses `this Go package <https://github.com/go-logfmt/logfmt>`_.
|
||||
* - ``json``
|
||||
- JSON formatted output. Each line is a valid JSON document. Fields are marshaled by
|
||||
``encoding/json.Marshal()``, which is particularly useful for processing in
|
||||
log aggregation or when processing state dumps.
|
||||
|
||||
Outlets are ... well ... outlets for log entries into the world.
|
||||
|
||||
**`stdout`**
|
||||
^^^^^^^^^^^^
|
||||
``stdout`` Outlet
|
||||
-----------------
|
||||
|
||||
::
|
||||
.. list-table::
|
||||
:widths: 10 90
|
||||
:header-rows: 1
|
||||
|
||||
| Parameter | Default | Comment |
|
||||
|-----------| --------- | ----------- |
|
||||
|`outlet` | *none* | required |
|
||||
|`level` | *none* | minimum [log level](#levels), required |
|
||||
|`format` | *none* | output [format](#formats), required |
|
||||
* - Parameter
|
||||
- Comment
|
||||
* - ``outlet``
|
||||
-
|
||||
* - ``level``
|
||||
- minimum :ref:`log level <logging-levels>`
|
||||
* - ``format``
|
||||
- output :ref:`format <logging-formats>`
|
||||
|
||||
Writes all log entries with minimum level `level` formatted by `format` to stdout.
|
||||
Writes all log entries with minimum level ``level`` formatted by ``format`` to stdout.
|
||||
|
||||
Can only be specified once.
|
||||
|
||||
**`syslog`**
|
||||
^^^^^^^^^^^^
|
||||
``syslog`` Outlet
|
||||
-----------------
|
||||
.. list-table::
|
||||
:widths: 10 90
|
||||
:header-rows: 1
|
||||
|
||||
::
|
||||
* - Parameter
|
||||
- Comment
|
||||
* - ``outlet``
|
||||
-
|
||||
* - ``level``
|
||||
- minimum :ref:`log level <logging-levels>`
|
||||
* - ``format``
|
||||
- output :ref:`format <logging-formats>`
|
||||
* - ``retry_interval``
|
||||
- Interval between reconnection attempts to syslog (default = 0)
|
||||
|
||||
| Parameter | Default | Comment |
|
||||
|-----------| --------- | ----------- |
|
||||
|`outlet` | *none* | required |
|
||||
|`level` | *none* | minimum [log level](#levels), required, usually `debug` |
|
||||
|`format` | *none* | output [format](#formats), required|
|
||||
|`retry_interval`| 0 | Interval between reconnection attempts to syslog |
|
||||
|
||||
Writes all log entries formatted by `format` to syslog.
|
||||
On normal setups, you should not need to change the `retry_interval`.
|
||||
Writes all log entries formatted by ``format`` to syslog.
|
||||
On normal setups, you should not need to change the ``retry_interval``.
|
||||
|
||||
Can only be specified once.
|
||||
|
||||
**`tcp`**
|
||||
^^^^^^^^^
|
||||
``tcp`` Outlet
|
||||
--------------
|
||||
|
||||
::
|
||||
.. list-table::
|
||||
:widths: 10 90
|
||||
:header-rows: 1
|
||||
|
||||
| Parameter | Default | Comment |
|
||||
|-----------| --------- | ----------- |
|
||||
|`outlet` | *none* | required |
|
||||
|`level` | *none* | minimum [log level](#levels), required |
|
||||
|`format` | *none* | output [format](#formats), required |
|
||||
|`net`|*none*|`tcp` in most cases|
|
||||
|`address`|*none*|remote network, e.g. `logs.example.com:10202`|
|
||||
|`retry_interval`|*none*|Interval between reconnection attempts to `address`|
|
||||
|`tls`|*none*|TLS config (see below)|
|
||||
* - Parameter
|
||||
- Comment
|
||||
* - ``outlet``
|
||||
-
|
||||
* - ``level``
|
||||
- minimum :ref:`log level <logging-levels>`
|
||||
* - ``format``
|
||||
- output :ref:`format <logging-formats>`
|
||||
* - ``net``
|
||||
- ``tcp`` in most cases
|
||||
* - ``address``
|
||||
- remote network, e.g. ``logs.example.com:10202``
|
||||
* - ``retry_interval``
|
||||
- Interval between reconnection attempts to ``address``
|
||||
* - ``tls``
|
||||
- TLS config (see below)
|
||||
|
||||
Establishes a TCP connection to `address` and sends log messages with minimum level `level` formatted by `format`.
|
||||
Establishes a TCP connection to ``address`` and sends log messages with minimum level ``level`` formatted by ``format``.
|
||||
|
||||
If `tls` is not specified, an unencrypted connection is established.
|
||||
If ``tls`` is not specified, an unencrypted connection is established.
|
||||
|
||||
If `tls` is specified, the TCP connection is secured with TLS + Client Authentication.
|
||||
If ``tls`` is specified, the TCP connection is secured with TLS + Client Authentication.
|
||||
This is particularly useful in combination with log aggregation services that run on an other machine.
|
||||
|
||||
::
|
||||
|
||||
|Parameter|Description|
|
||||
|---------|-----------|
|
||||
|`ca`|PEM-encoded certificate authority that signed the remote server's TLS certificate|
|
||||
|`cert`|PEM-encoded client certificate identifying this zrepl daemon toward the remote server|
|
||||
|`key`|PEM-encoded, unencrypted client private key identifying this zrepl daemon toward the remote server|
|
||||
.. list-table::
|
||||
:widths: 10 90
|
||||
:header-rows: 1
|
||||
|
||||
* - Parameter
|
||||
- Description
|
||||
* - ``ca``
|
||||
- PEM-encoded certificate authority that signed the remote server's TLS certificate
|
||||
* - ``cert``
|
||||
- PEM-encoded client certificate identifying this zrepl daemon toward the remote server
|
||||
* - ``key``
|
||||
- PEM-encoded, unencrypted client private key identifying this zrepl daemon toward the remote server
|
||||
|
||||
.. NOTE::
|
||||
|
||||
zrepl uses Go's `crypto/tls` and `crypto/x509` packages and leaves all but the required fields in `tls.Config` at their default values.
|
||||
zrepl uses Go's ``crypto/tls`` and ``crypto/x509`` packages and leaves all but the required fields in ``tls.Config`` at their default values.
|
||||
In case of a security defect in these packages, zrepl has to be rebuilt because Go binaries are statically linked.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user