From 828c2982f3757526495ec9abc701acade114716d Mon Sep 17 00:00:00 2001 From: Christian Schwarz Date: Fri, 10 Nov 2017 13:10:47 +0100 Subject: [PATCH] docs: adjust logging to rst --- docs/configuration/logging.rst | 175 ++++++++++++++++++++------------- 1 file changed, 108 insertions(+), 67 deletions(-) diff --git a/docs/configuration/logging.rst b/docs/configuration/logging.rst index 60d8359..2be7d1d 100644 --- a/docs/configuration/logging.rst +++ b/docs/configuration/logging.rst @@ -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" >}}).
-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**.
+ 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 `_ output. zrepl uses `this Go package `_. + * - ``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 ` + * - ``format`` + - output :ref:`format ` -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 ` + * - ``format`` + - output :ref:`format ` + * - ``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 ` + * - ``format`` + - output :ref:`format ` + * - ``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.