1# Logging
2
3Boulder can log to stdout/stderr, syslog, or both. Boulder components
4generally have a `syslog` portion of their JSON config that indicates the
5maximum level of log that should be sent to a given destination. For instance,
6in `test/config/wfe2.json`:
7
8```
9 "syslog": {
10 "stdoutlevel": 4,
11 "sysloglevel": 6
12 },
13```
14
15This indicates that logs of level 4 or below (error and warning) should be
16emitted to stdout/stderr, and logs of level 6 or below (error, warning, notice, and
17info) should be emitted to syslog, using the local Unix socket method. The
18highest meaningful value is 7, which enables debug logging.
19
20The stdout/stderr logger uses ANSI escape codes to color warnings as yellow
21and errors as red, if stdout is detected to be a terminal.
22
23The default value for these fields is 6 (INFO) for syslogLevel and 0 (no logs)
24for stdoutLevel. To turn off syslog logging entirely, set syslogLevel to -1.
25
26In Boulder's development environment, we enable stdout logging because that
27makes it easier to see what's going on quickly. In production, we disable stdout
28logging because it would duplicate the syslog logging. We preferred the syslog
29logging because it provides things like severity level in a consistent way with
30other components. But we may move to stdout/stderr logging to make it easier to
31containerize Boulder.
32
33Boulder has a number of adapters to take other packages' log APIs and send them
34to syslog as expected. For instance, we provide a custom logger for mysql, grpc,
35and prometheus that forwards to syslog. This is configured in StatsAndLogging in
36cmd/shell.go.
37
38There are some cases where we output to stdout regardless of the JSON config
39settings:
40
41 - Panics are always emitted to stdout
42 - Packages that Boulder relies on may occasionally emit to stdout (though this
43 is generally not ideal and we try to get it changed).
44
45Typically these output lines will be collected by systemd and forwarded to
46syslog.
47
48## Verification
49
50We attach a simple checksum to each log line. This is not a cryptographically
51secure hash, but is intended to let us catch corruption in the log system. This
52is a short chunk of base64 encoded data near the beginning of the log line. It
53is consumed by cmd/log-validator.
View as plain text