docs(logging): environment variables (#8833)
- Document IPFS_LOGGING deprecation as alias to GOLOG_LOG_LEVEL and expand doc to include per-subsystem log levels. - Document IPFS_LOGGING_FMT deprecation as alias to GOLOG_LOG_FMT.
Justin Johnson committed
Apr 6, 2022 at 10:24 UTC
7b2c7c7f166f33f18a995e103acbe3774ddf1408
1 file changed
+42
-15
docs/environment-variables.md
+42
-15
@@ -17,28 +17,55 @@ Default: ~/.ipfs
17
18
## `IPFS_LOGGING`
19
20
-Sets the log level for go-ipfs. It can be set to one of:
20
+Specifies the log level for go-ipfs.
21
22
-* `CRITICAL`
23
-* `ERROR`
24
-* `WARNING`
25
-* `NOTICE`
26
-* `INFO`
27
-* `DEBUG`
22
+`IPFS_LOGGING` is a deprecated alias for the `GOLOG_LOG_LEVEL` environment variable. See below.
23
29
-Logging can also be configured (on a subsystem by subsystem basis) at runtime
30
-with the `ipfs log` command.
24
+## `IPFS_LOGGING_FMT`
25
32
-Default: `ERROR`
26
+Specifies the log message format.
27
34
-## `IPFS_LOGGING_FMT`
28
+`IPFS_LOGGING_FMT` is a deprecated alias for the `GOLOG_LOG_FMT` environment variable. See below.
29
+
30
+## `GOLOG_LOG_LEVEL`
31
+
32
+Specifies the log-level, both globally and on a per-subsystem basis. Level can be one of:
33
+
34
+* `debug`
35
+* `info`
36
+* `warn`
37
+* `error`
38
+* `dpanic`
39
+* `panic`
40
+* `fatal`
41
+
42
+Per-subsystem levels can be specified with `subsystem=level`. One global level and one or more per-subsystem levels
43
+can be specified by separating them with commas.
44
+
45
+Default: `error`
46
+
47
+Example:
48
+
49
+```console
50
+GOLOG_LOG_LEVEL="error,core/server=debug" ipfs daemon
51
+```
52
36
-Sets the log message format. Can be one of:
53
+Logging can also be configured at runtime, both globally and on a per-subsystem basis, with the `ipfs log` command.
54
38
-* `color`
39
-* `nocolor`
55
+## `GOLOG_LOG_FMT`
56
41
-Default: `color`
57
+Specifies the log message format. It supports the following values:
58
+
59
+- `color` -- human readable, colorized (ANSI) output
60
+- `nocolor` -- human readable, plain-text output.
61
+- `json` -- structured JSON.
62
+
63
+For example, to log structured JSON (for easier parsing):
64
+
65
+```bash
66
+export GOLOG_LOG_FMT="json"
67
+```
68
+The logging format defaults to `color` when the output is a terminal, and `nocolor` otherwise.
69
70
## `GOLOG_FILE`
71