Merge pull request #2197 from darh/json_log_format

Add more control over log_format config directive

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:

nginx.tmpl

@@ -402,7 +402,24 @@ map $proxy_x_forwarded_proto $proxy_x_forwarded_ssl {
 
 gzip_types text/plain text/css application/javascript application/json application/x-javascript text/xml application/xml application/xml+rss text/javascript;
 
-log_format vhost '{{ or $globals.Env.LOG_FORMAT "$host $remote_addr - $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" \"$upstream_addr\"" }}';
+
+{{- /* See https://nginx.org/en/docs/http/ngx_http_log_module.html#log_format for details and variables
+     * LOG_FORMAT_ESCAPE sets the escape part of the log format
+     * LOG_FORMAT        sets the log format
+     */}}
+{{- $logEscape := printf "escape=%s" (or $globals.Env.LOG_FORMAT_ESCAPE "default") }}
+{{- $logFormat := or $globals.Env.LOG_FORMAT `$host $remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$upstream_addr"` }}
+
+{{- if parseBool (or $globals.Env.LOG_JSON "false") }}
+    {{- /* LOG_JSON is a shorthand
+        * that sets logging defaults to JSON format
+        */}}
+# JSON Logging enabled (via LOG_JSON env variable)
+    {{- $logEscape = printf "escape=%s" (or $globals.Env.LOG_FORMAT_ESCAPE "json") }}
+    {{- $logFormat = or $globals.Env.LOG_FORMAT `{"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"}` }}
+{{- end }}
+
+log_format vhost {{ $logEscape }} '{{ or $globals.Env.LOG_FORMAT $logFormat }}';
 
 access_log off;
 

test/test_log_json.py

@@ -0,0 +1,14 @@
+import pytest
+
+def test_log_json(docker_compose, nginxproxy):
+    log_conf = [line for line in nginxproxy.get_conf().decode('ASCII').splitlines() if "log_format vhost escape=" in line]
+    assert "{\"time_local\":\"$time_iso8601\"," in log_conf[0]
+
+    r = nginxproxy.get("http://nginx-proxy.test/port")
+    assert r.status_code == 200
+    assert r.text == "answer from port 81\n"
+    sut_container = docker_compose.containers.get("sut")
+    docker_logs = sut_container.logs(stdout=True, stderr=True, stream=False, follow=False)
+    docker_logs = docker_logs.decode("utf-8").splitlines()
+    docker_logs = [line for line in docker_logs if "{\"time_local\":" in line]
+    assert "GET /port" in docker_logs[0]

test/test_log_json.yml

@@ -0,0 +1,18 @@
+version: "2"
+
+services:
+  web1:
+    image: web
+    expose:
+      - "81"
+    environment:
+      WEB_PORTS: 81
+      VIRTUAL_HOST: nginx-proxy.test
+
+  sut:
+    container_name: sut
+    image: nginxproxy/nginx-proxy:test
+    volumes:
+      - /var/run/docker.sock:/tmp/docker.sock:ro
+    environment:
+      LOG_JSON: 1

test/test_log_json_format.py

@@ -0,0 +1,14 @@
+import pytest
+
+def test_log_json_format(docker_compose, nginxproxy):
+    log_conf = [line for line in nginxproxy.get_conf().decode('ASCII').splitlines() if "log_format vhost escape=" in line]
+    assert "{\"time_local\":\"$time_iso8601\"," in log_conf[0]
+
+    r = nginxproxy.get("http://nginx-proxy.test/port")
+    assert r.status_code == 200
+    assert r.text == "answer from port 81\n"
+    sut_container = docker_compose.containers.get("sut")
+    docker_logs = sut_container.logs(stdout=True, stderr=True, stream=False, follow=False)
+    docker_logs = docker_logs.decode("utf-8").splitlines()
+    docker_logs = [line for line in docker_logs if "{\"time_local\":" in line]
+    assert "GET /port" in docker_logs[0]

test/test_log_json_format.yml

@@ -0,0 +1,18 @@
+version: "2"
+
+services:
+  web1:
+    image: web
+    expose:
+      - "81"
+    environment:
+      WEB_PORTS: 81
+      VIRTUAL_HOST: nginx-proxy.test
+
+  sut:
+    container_name: sut
+    image: nginxproxy/nginx-proxy:test
+    volumes:
+      - /var/run/docker.sock:/tmp/docker.sock:ro
+    environment:
+      LOG_FORMAT: '{"time_local":"$$time_iso8601","remote_addr":"$$remote_addr","request":"$$request","upstream_addr":"$$upstream_addr"}'