extern/zrepl
1
0
Fork 0
mirror of https://github.com/zrepl/zrepl.git synced 2025-06-23 11:11:40 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: adjust logging to rst

Browse Source
This commit is contained in:
Christian Schwarz 2017-11-10 13:10:47 +01:00
parent 6f7b8ca1af
commit 828c2982f3
1 changed files with 108 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

175
docs/configuration/logging.rst
View File

@ -1,3 +1,4 @@
.. include:: ../global.rst.inc
.. _conf-logging: .. _conf-logging:
Logging Logging
@ -5,11 +6,8 @@ Logging
zrepl uses structured logging to provide users with easily processable log messages. zrepl uses structured logging to provide users with easily processable log messages.
Configuration 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:
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:
:: ::
@ -29,7 +27,7 @@ Check out {{< sampleconflink "random/logging.yml" >}} for an example on how to c
jobs: ... jobs: ...
Default Configuration Default Configuration
~~~~~~~~~~~~~~~~~~~~~ ---------------------
By default, the following logging configuration is used By default, the following logging configuration is used
@ -43,7 +41,7 @@ By default, the following logging configuration is used
format: "human" format: "human"
.. ATTENTION:: .. 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. Only errors in the logging infrastructure itself, e.g. IO errors when writing to an outlet, are sent to stderr.
Building Blocks Building Blocks
@ -51,100 +49,143 @@ Building Blocks
The following sections document the semantics of the different log levels, formats and outlet types. The following sections document the semantics of the different log levels, formats and outlet types.
.. _logging-levels:
Levels Levels
~~~~~~ ~~~~~~
:: .. list-table::
:widths: 10 10 80
:header-rows: 1
| Level | SHORT | Description | * - Level
|-------|-------|-------------| - SHORT
|`error`|`ERRO` | immediate action required | - Description
|`warn` |`WARN` | symptoms for misconfiguration, soon expected failure, etc.| * - ``error``
|`info` |`INFO` | explains what happens without too much detail | - ``ERRO``
|`debug`|`DEBG` | tracing information, state dumps, etc. useful for debugging. | - 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. Incorrectly classified messages are considered a bug and should be reported.
.. _logging-formats:
Formats Formats
~~~~~~~ ~~~~~~~
:: .. list-table::
:widths: 10 90
:header-rows: 1
| Format | Description | * - 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| * - ``human``
|`logfmt`| [logfmt](https://brandur.org/logfmt) output. zrepl uses [github.com/go-logfmt/logfmt](github.com/go-logfmt/logfmt).| - emphasizes context by putting job, task, step and other context variables into brackets
|`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. before the actual message, followed by remaining fields in logfmt style|
* - ``logfmt``
Outlets - `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. Outlets are ... well ... outlets for log entries into the world.
**`stdout`** ``stdout`` Outlet
^^^^^^^^^^^^ -----------------
:: .. list-table::
:widths: 10 90
:header-rows: 1
| Parameter | Default | Comment | * - Parameter
|-----------| --------- | ----------- | - Comment
|`outlet` | *none* | required | * - ``outlet``
|`level` | *none* | minimum [log level](#levels), required | -
|`format` | *none* | output [format](#formats), required | * - ``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. 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 | Writes all log entries formatted by ``format`` to syslog.
|-----------| --------- | ----------- | On normal setups, you should not need to change the ``retry_interval``.
|`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`.
Can only be specified once. Can only be specified once.
**`tcp`** ``tcp`` Outlet
^^^^^^^^^ --------------
:: .. list-table::
:widths: 10 90
:header-rows: 1
| Parameter | Default | Comment | * - Parameter
|-----------| --------- | ----------- | - Comment
|`outlet` | *none* | required | * - ``outlet``
|`level` | *none* | minimum [log level](#levels), required | -
|`format` | *none* | output [format](#formats), required | * - ``level``
|`net`|*none*|`tcp` in most cases| - minimum :ref:`log level <logging-levels>`
|`address`|*none*|remote network, e.g. `logs.example.com:10202`| * - ``format``
|`retry_interval`|*none*|Interval between reconnection attempts to `address`| - output :ref:`format <logging-formats>`
|`tls`|*none*|TLS config (see below)| * - ``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. This is particularly useful in combination with log aggregation services that run on an other machine.
:: .. list-table::
:widths: 10 90
|Parameter|Description| :header-rows: 1
|---------|-----------|
|`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|
* - 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:: .. 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. In case of a security defect in these packages, zrepl has to be rebuilt because Go binaries are statically linked.