Merge pull request #882 from openziti/refine-logging

add logging ref
openziti · May 22, 2024 · f3f6732 · f3f6732
2 parents f82ac4b + fe9b870
commit f3f6732
Show file tree

Hide file tree

Showing 3 changed files with 70 additions and 14 deletions.
diff --git a/docusaurus/docs/guides/deployments/10-linux/10-controller/10-deploy.mdx b/docusaurus/docs/guides/deployments/10-linux/10-controller/10-deploy.mdx
@@ -125,27 +125,34 @@ View the service's output.
 journalctl -u ziti-controller.service
 ```
 
+<br />
+
+Learn more in [the logging reference](/reference/40-logging.mdx).
+
+<br />
+
 <Tabs>
-<TabItem value="goformats" label="Log Formats">
 
-Choose the logging format (default: text) as an argument for the `run --log-formatter` option. The available formats are:
+<TabItem value="goformats" label="Log Formats">
 
-- `pfxlog` - a human-readable format leveraging ANSI escape codes to colorize log levels
-- `json` - a machine-readable format targeting automated processes for log aggregation
-- `text` - a human-readable format using plain text (no ANSI escape codes)
+Set a different format in the override file's `ExecStart` directive.
 
-Run options must be set in the service's override file in the `ExecStart` directive.
+<br />
 
 ```text title=/etc/systemd/system/ziti-controller.service.d/override.conf
 [Service]
 ExecStart=
 ExecStart=/opt/openziti/etc/controller/entrypoint.bash run config.yml --log-formatter text
 ```
 
+<br />
+
 </TabItem>
 <TabItem value="golevels" label="Log Levels">
 
-The default log level is `INFO`. This means that log messages `INFO`, `WARNING`, `ERROR`, and `FATAL` will all be emitted. Enable verbose logging by adding `--verbose or -v` to the command being executed. Verbose mode will additionally emit `DEBUG` log level messages.
+Enable DEBUG log level with the `--verbose` flag in the override file's `ExecStart` directive.
+
+<br />
 
 ```text title=/etc/systemd/system/ziti-controller.service.d/override.conf
 [Service]

diff --git a/docusaurus/docs/guides/deployments/10-linux/20-router/10-deploy.mdx b/docusaurus/docs/guides/deployments/10-linux/20-router/10-deploy.mdx
@@ -121,27 +121,34 @@ View the service's output.
 journalctl -u ziti-router.service
 ```
 
+<br />
+
+Learn more in [the logging reference](/reference/40-logging.mdx).
+
+<br />
+
 <Tabs>
-<TabItem value="goformats" label="Log Formats">
 
-Choose the logging format (default: text) as an argument for the `run --log-formatter` option. The available formats are:
+<TabItem value="goformats" label="Log Formats">
 
-- `pfxlog` - a human-readable format leveraging ANSI escape codes to colorize log levels
-- `json` - a machine-readable format targeting automated processes for log aggregation
-- `text` - a human-readable format using plain text (no ANSI escape codes)
+Set a different format in the override file's `ExecStart` directive.
 
-Run options must be set in the service's override file in the `ExecStart` directive.
+<br />
 
 ```text title=/etc/systemd/system/ziti-router.service.d/override.conf
 [Service]
 ExecStart=
 ExecStart=/opt/openziti/etc/router/entrypoint.bash run config.yml --log-formatter text
 ```
 
+<br />
+
 </TabItem>
 <TabItem value="golevels" label="Log Levels">
 
-The default log level is `INFO`. This means that log messages `INFO`, `WARNING`, `ERROR`, and `FATAL` will all be emitted. Enable verbose logging by adding `--verbose or -v` to the command being executed. Verbose mode will additionally emit `DEBUG` log level messages.
+Enable DEBUG log level with the `--verbose` flag in the override file's `ExecStart` directive.
+
+<br />
 
 ```text title=/etc/systemd/system/ziti-router.service.d/override.conf
 [Service]

diff --git a/docusaurus/docs/reference/40-logging.mdx b/docusaurus/docs/reference/40-logging.mdx
@@ -0,0 +1,42 @@
+---
+title: Logging
+---
+
+This article is about log messages from the `ziti` CLI that is used to run the controller and router. See [the Linux tunneler reference](/reference/tunnelers/60-linux/50-linux-tunnel-troubleshooting.mdx) for details about messages from `ziti-edge-tunnel`.
+
+## Levels
+
+The default log level is `INFO`. This means that log messages `INFO`, `WARNING`, `ERROR`, and `FATAL` will all be emitted. Enable verbose logging by adding `--verbose or -v` to the command being executed. Verbose mode will additionally emit `DEBUG` messages.
+
+## Formats
+
+Adjust the log format with option `--log-formatter` (`json`, `text`, `pfxlog`). 
+
+The default log format is `json` when is running in the background (no tty).
+
+<br />
+
+```text
+{"file":"github.com/openziti/ziti/controller/network/network.go:927","func":"github.com/openziti/ziti/controller/network.(*Network).Run","level":"info","msg":"started","time":"2024-05-22T09:20:06.423Z"}
+```
+
+<br />
+
+The `text` format has the same level of detail and is the default when running in the foreground (with tty).
+
+<br />
+
+```text
+time="2024-05-22T09:23:27-04:00" level=info msg=started func="github.com/openziti/ziti/controller/network.(*Network).Run" file="github.com/openziti/ziti/controller/network/network.go:927"
+```
+
+<br />
+
+The simplified, human-friendly format is `pfxlog`. This format can also be enabled by setting environment variable `PFXLOG_NO_JSON=true`.
+
+<br />
+
+
+```text
+INFO ziti/controller/network.(*Network).Run: started
+```