mirror of
https://github.com/zrepl/zrepl.git
synced 2024-11-25 09:54:47 +01:00
149 lines
4.7 KiB
ReStructuredText
149 lines
4.7 KiB
ReStructuredText
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.
|