docs: initial port of hugo to sphinx, including rtd theme

2017-11-09 20:33:09 +01:00
parent c3af267f48
commit df181108b4
13 changed files with 1009 additions and 11 deletions
@@ -0,0 +1,148 @@
+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:
+
+::
+
+    global:
+      logging:
+    
+        - outlet: OUTLET_TYPE
+          level: MINIMUM_LEVEL
+          format: FORMAT
+    
+        - outlet: OUTLET_TYPE
+          level: MINIMUM_LEVEL
+          format: FORMAT
+    
+        ...
+    
+    jobs: ...
+
+Default Configuration
+~~~~~~~~~~~~~~~~~~~~~
+
+By default, the following logging configuration is used
+
+::
+
+    global:
+      logging:
+    
+        - outlet: "stdout"
+          level:  "warn"
+          format: "human"
+
+.. ATTENTION::
+    Output to **stderr** should always be considered a **critical error**.<br />
+    Only errors in the logging infrastructure itself, e.g. IO errors when writing to an outlet, are sent to stderr.
+
+Building Blocks
+---------------
+
+The following sections document the semantics of the different log levels, formats and outlet types.
+
+Levels
+~~~~~~
+
+::
+
+    | 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.
+
+Formats
+~~~~~~~
+
+::
+
+    | 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
+~~~~~~~
+
+Outlets are ... well ... outlets for log entries into the world.
+
+**`stdout`**
+^^^^^^^^^^^^
+
+::
+
+    | Parameter | Default   | Comment |
+    |-----------| --------- | ----------- |
+    |`outlet`   | *none*    | required |
+    |`level`    | *none*    | minimum [log level](#levels), required |
+    |`format`   | *none*    | output [format](#formats), required |
+
+Writes all log entries with minimum level `level` formatted by `format` to stdout.
+
+Can only be specified once.
+
+**`syslog`**
+^^^^^^^^^^^^
+
+::
+
+    | 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`.
+
+Can only be specified once.
+
+**`tcp`**
+^^^^^^^^^
+
+::
+
+    | 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)|
+
+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 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|
+
+
+.. 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.
+    In case of a security defect in these packages, zrepl has to be rebuilt because Go binaries are statically linked.