From 62f55b4428a1133e5f44a75dde310271fef28c60 Mon Sep 17 00:00:00 2001
From: Nicolas Duchon <nicolas.duchon@gmail.com>
Date: Sat, 10 Feb 2024 19:03:13 +0100
Subject: [PATCH] docs: add logging documentation

---
 docs/README.md | 65 +++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 51 insertions(+), 14 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index 32d432c..e381b7f 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -181,12 +181,61 @@ If you would like to connect to FastCGI backend, set `VIRTUAL_PROTO=fastcgi` on
 
 If you use fastcgi,you can set `VIRTUAL_ROOT=xxx`  for your root directory
 
-### Custom log format
+### Logging
 
-If you want to use a custom log format, you can set `LOG_FORMAT=xxx` on the proxy container. 
+The default nginx access log format is
+
+```
+$host $remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$upstream_addr"
+```
+
+#### Custom log format
+
+If you want to use a custom access log format, you can set `LOG_FORMAT=xxx` on the proxy container.
 
 With docker compose take care to escape the `$` character with `$$` to avoid variable interpolation. Example: `$remote_addr` becomes `$$remote_addr`.
 
+#### JSON log format
+
+If you want access logs in JSON format, you can set `LOG_JSON=true`. This will correctly set the escape character to `json` and the log format to :
+
+```json
+{
+  "time_local": "$time_iso8601",
+  "client_ip": "$http_x_forwarded_for",
+  "remote_addr": "$remote_addr",
+  "request": "$request",
+  "status": "$status",
+  "body_bytes_sent": "$body_bytes_sent",
+  "request_time": "$request_time",
+  "upstream_response_time": "$upstream_response_time",
+  "upstream_addr": "$upstream_addr",
+  "http_referrer": "$http_referer",
+  "http_user_agent": "$http_user_agent",
+  "request_id": "$request_id"
+}
+```
+
+#### Log format escaping
+
+If you want to manually set nginx `log_format`'s `escape`, set the `LOG_FORMAT_ESCAPE` variable to [a value supported by nginx](https://nginx.org/en/docs/http/ngx_http_log_module.html#log_format).
+
+#### Disable access logs
+
+To disable nginx access logs entirely, set the `DISABLE_ACCESS_LOGS` environment variable to any value.
+
+#### Disabling colors in the container log output
+
+To remove colors from the container log output, set the [`NO_COLOR` environment variable to any value other than an empty string](https://no-color.org/) on the nginx-proxy container.
+
+```console
+docker run --detach \
+  --publish 80:80 \
+  --env NO_COLOR=1 \
+  --volume /var/run/docker.sock:/tmp/docker.sock:ro \
+  nginxproxy/nginx-proxy
+```
+
 ### Default Host
 
 To set the default host for nginx use the env var `DEFAULT_HOST=foo.bar.com` for example
@@ -679,18 +728,6 @@ By default the nginx configuration `upstream` blocks will use this block's corre
 
 Please note that using regular expressions in `VIRTUAL_HOST` will always result in a corresponding `upstream` block with an SHA1 name.
 
-### Disabling colors in the log output
-
-To remove colors from the log output, set the [`NO_COLOR` environment variable to any value other than an empty string](https://no-color.org/) on the nginx-proxy container.
-
-```console
-docker run --detach \
-  --publish 80:80 \
-  --env NO_COLOR=1 \
-  --volume /var/run/docker.sock:/tmp/docker.sock:ro \
-  nginxproxy/nginx-proxy
-```
-
 ### Troubleshooting
 
 If you can't access your `VIRTUAL_HOST`, inspect the generated nginx configuration: