From 2578c6250f59fdd3e10ac1438dd294ce9d29915b Mon Sep 17 00:00:00 2001
From: Vladimir Kutepov <frenzzy.man@gmail.com>
Date: Mon, 26 Oct 2026 09:47:29 +0700
Subject: [PATCH 1/8] docs: access log format (v3)

---
 src/v3/configuration/cli.md  |  2 ++
 src/v3/configuration/env.md  |  4 +++
 src/v3/configuration/file.md |  3 +++
 src/v3/features/logging.md   | 50 ++++++++++++++++++++++++++++++++++++
 4 files changed, 59 insertions(+)

diff --git a/src/v3/configuration/cli.md b/src/v3/configuration/cli.md
index 4642d32..8094dcd 100644
--- a/src/v3/configuration/cli.md
+++ b/src/v3/configuration/cli.md
@@ -100,6 +100,8 @@ Options:
           Defines a grace period in seconds after a `SIGTERM` signal is caught which will delay the server before to shut it down gracefully. The maximum value is 255 seconds [env: SERVER_GRACE_PERIOD=] [default: 0]
   -w, --config-file <CONFIG_FILE>
           Server TOML configuration file path [env: SERVER_CONFIG_FILE=] [default: ./sws.toml]
+      --access-log-format <ACCESS_LOG_FORMAT>
+          Custom access log format string using %{token} syntax. When set, replaces the default request logging with a configurable format that includes response data. Tokens: method, uri, status, bytes, duration, remote_addr, x_real_ip, forwarded_for, host, user_agent, referer, timestamp, version. Example: '%{remote_addr} "%{method} %{uri}" %{status} %{bytes}' [env: SERVER_ACCESS_LOG_FORMAT=] [default: ""]
       --log-remote-address [<LOG_REMOTE_ADDRESS>]
           Log incoming requests information along with its remote address if available using the `info` log level [env: SERVER_LOG_REMOTE_ADDRESS=] [default: false] [possible values: true, false]
       --log-x-real-ip [<LOG_X_REAL_IP>]
diff --git a/src/v3/configuration/env.md b/src/v3/configuration/env.md
index 1a85782..e2b721c 100644
--- a/src/v3/configuration/env.md
+++ b/src/v3/configuration/env.md
@@ -171,6 +171,10 @@ Defines a grace period in seconds after a `SIGTERM` signal is caught which will
 
 Server TOML configuration file path. See [The TOML Configuration File](../configuration/file). Default `./sws.toml`.
 
+## SERVER_ACCESS_LOG_FORMAT
+
+Custom access log format using the `%{token}` syntax. When set, SWS logs one line per request after the response in this format, instead of the default request line. See [Access Log Format](../features/logging#access-log-format). Default empty (disabled).
+
 ## SERVER_LOG_REMOTE_ADDRESS
 
 Log incoming requests information along with its remote address if available using the `info` log level. Default `false`.
diff --git a/src/v3/configuration/file.md b/src/v3/configuration/file.md
index 38ab096..69691a8 100644
--- a/src/v3/configuration/file.md
+++ b/src/v3/configuration/file.md
@@ -80,6 +80,9 @@ grace-period = 0
 #### Page fallback for 404s
 # page-fallback = ""
 
+#### Custom access log format (replaces the default request line when set)
+# access-log-format = '%{remote_addr} - [%{timestamp}] "%{method} %{uri} %{version}" %{status} %{bytes} "%{referer}" "%{user_agent}"'
+
 #### Log request Remote Address if available
 log-remote-address = false
 
diff --git a/src/v3/features/logging.md b/src/v3/features/logging.md
index 781ebee..1d9a4eb 100644
--- a/src/v3/features/logging.md
+++ b/src/v3/features/logging.md
@@ -230,6 +230,56 @@ curl "http://[::1]:8080" --header "X-Forwarded-For: <iframe src=//malware.attack
 }
 ```
 
+## Access Log Format
+
+**`SWS`** can write one access log line per request in a format you define, for example the nginx or NCSA combined format. The line is written after the response, so it carries the status code, the response size and the duration.
+
+This feature is disabled by default. Set a format with the `--access-log-format` option, the equivalent [SERVER_ACCESS_LOG_FORMAT](./../configuration/env#server_access_log_format) env or the `access-log-format` key under `[general]` in the [TOML file](./../configuration/file). When a format is set, it replaces the `incoming request` line described in [Per-request logging](#per-request-logging).
+
+```sh
+static-web-server -p 8787 -d ./public/ -g info \
+    --access-log-format '%{remote_addr} - [%{timestamp}] "%{method} %{uri} %{version}" %{status} %{bytes} "%{referer}" "%{user_agent}"'
+```
+
+```toml
+[general]
+access-log-format = '%{remote_addr} - [%{timestamp}] "%{method} %{uri} %{version}" %{status} %{bytes} "%{referer}" "%{user_agent}"'
+```
+
+### Tokens
+
+A token is written as `%{name}`. `%%` writes a literal `%`. Any other text is copied as is. SWS validates the format at startup and refuses to start on an unknown token, an unclosed `%{` or a `%` followed by another character.
+
+| Token              | Value                                                                                               |
+| ------------------ | --------------------------------------------------------------------------------------------------- |
+| `%{method}`        | Request method, e.g. `GET`                                                                          |
+| `%{uri}`           | Request URI as sent by the client, before [URL Rewrites](./url-rewrites)                            |
+| `%{version}`       | HTTP version, e.g. `HTTP/1.1`                                                                       |
+| `%{status}`        | Response status code                                                                                |
+| `%{bytes}`         | Response `Content-Length`, or `-` when the response has none (e.g. compressed on the fly)           |
+| `%{duration}`      | Time to build the response in seconds, with microsecond precision                                   |
+| `%{remote_addr}`   | Client IP address                                                                                   |
+| `%{x_real_ip}`     | `X-Real-IP` address, see [Logging Client IP from X-Real-IP header](#logging-client-ip-from-x-real-ip-header) |
+| `%{forwarded_for}` | First `X-Forwarded-For` address, see [Logging Client IP from X-Forwarded-For header](#logging-client-ip-from-x-forwarded-for-header) |
+| `%{host}`          | `Host` header                                                                                       |
+| `%{user_agent}`    | `User-Agent` header                                                                                 |
+| `%{referer}`       | `Referer` header                                                                                    |
+| `%{timestamp}`     | Local time in the `%d/%b/%Y:%H:%M:%S %z` format, e.g. `29/May/2026:23:43:47 +0200`, honoring `TZ`  |
+
+A token without a value is written as `-`. `%{x_real_ip}` and `%{forwarded_for}` follow the `--log-x-real-ip`, `--log-forwarded-for` and `--trusted-proxies` options.
+
+### Output
+
+The rendered line is the `message` of a log entry with the `static_web_server::access_logs` target, at the `info` level, so it needs `--log-level info` or lower. Requests to the health endpoint are logged at the `debug` level. With the `json` format:
+
+```json
+{"timestamp":"2026-05-29T23:43:47.151533+02:00","level":"INFO","message":"192.168.1.126 - [29/May/2026:23:43:47 +0200] \"GET / HTTP/1.1\" 200 1250 \"-\" \"curl/8.7.1\"","target":"static_web_server::access_logs"}
+```
+
+### Escaping
+
+The URI and the `Host`, `User-Agent` and `Referer` headers come from the client. SWS writes bytes outside printable ASCII, `"` and `\` in them as `\xHH`, so a client cannot close a quoted field or inject a fake log line. For example, the `User-Agent` value `x" 200 "forged` is logged as `x\x22 200 \x22forged`.
+
 ## File Logging
 
 By default **SWS** writes log records to standard error. The `--log-file` option additionally streams every record to a file on disk, in **addition** to `stderr`. This is useful for production deployments where `stderr` is captured by a service manager but a durable on-disk copy is also required.

From c51df5ff107f800bfb26f402f4c7c2fa408376c0 Mon Sep 17 00:00:00 2001
From: Vladimir Kutepov <frenzzy.man@gmail.com>
Date: Mon, 26 Oct 2026 10:02:37 +0700
Subject: [PATCH 2/8] docs: note that failed requests have no access log line

---
 src/v3/features/logging.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/v3/features/logging.md b/src/v3/features/logging.md
index 1d9a4eb..0a5556f 100644
--- a/src/v3/features/logging.md
+++ b/src/v3/features/logging.md
@@ -270,7 +270,7 @@ A token without a value is written as `-`. `%{x_real_ip}` and `%{forwarded_for}`
 
 ### Output
 
-The rendered line is the `message` of a log entry with the `static_web_server::access_logs` target, at the `info` level, so it needs `--log-level info` or lower. Requests to the health endpoint are logged at the `debug` level. With the `json` format:
+The rendered line is the `message` of a log entry with the `static_web_server::access_logs` target, at the `info` level, so it needs `--log-level info` or lower. Requests to the health endpoint are logged at the `debug` level. A request that fails before SWS builds a response is not logged. With the `json` format:
 
 ```json
 {"timestamp":"2026-05-29T23:43:47.151533+02:00","level":"INFO","message":"192.168.1.126 - [29/May/2026:23:43:47 +0200] \"GET / HTTP/1.1\" 200 1250 \"-\" \"curl/8.7.1\"","target":"static_web_server::access_logs"}

From 6ae082ed60540a4459c7ca1c65d49ca01c48675a Mon Sep 17 00:00:00 2001
From: Vladimir Kutepov <frenzzy.man@gmail.com>
Date: Sat, 31 Oct 2026 18:48:31 +0700
Subject: [PATCH 3/8] docs(logging): proxy tokens follow --trusted-proxies only

---
 src/v3/configuration/cli.md | 2 +-
 src/v3/features/logging.md  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/v3/configuration/cli.md b/src/v3/configuration/cli.md
index 8094dcd..eb52925 100644
--- a/src/v3/configuration/cli.md
+++ b/src/v3/configuration/cli.md
@@ -101,7 +101,7 @@ Options:
   -w, --config-file <CONFIG_FILE>
           Server TOML configuration file path [env: SERVER_CONFIG_FILE=] [default: ./sws.toml]
       --access-log-format <ACCESS_LOG_FORMAT>
-          Custom access log format string using %{token} syntax. When set, replaces the default request logging with a configurable format that includes response data. Tokens: method, uri, status, bytes, duration, remote_addr, x_real_ip, forwarded_for, host, user_agent, referer, timestamp, version. Example: '%{remote_addr} "%{method} %{uri}" %{status} %{bytes}' [env: SERVER_ACCESS_LOG_FORMAT=] [default: ""]
+          Custom access log format string using %{token} syntax. When set, replaces the default request logging with a configurable format that includes response data. Tokens: method, uri, status, bytes, duration, remote_addr, x_real_ip, forwarded_for, host, user_agent, referer, timestamp, version. x_real_ip and forwarded_for are logged only for requests from --trusted-proxies, if set. Example: '%{remote_addr} "%{method} %{uri}" %{status} %{bytes}' [env: SERVER_ACCESS_LOG_FORMAT=] [default: ""]
       --log-remote-address [<LOG_REMOTE_ADDRESS>]
           Log incoming requests information along with its remote address if available using the `info` log level [env: SERVER_LOG_REMOTE_ADDRESS=] [default: false] [possible values: true, false]
       --log-x-real-ip [<LOG_X_REAL_IP>]
diff --git a/src/v3/features/logging.md b/src/v3/features/logging.md
index 0a5556f..9d6d1db 100644
--- a/src/v3/features/logging.md
+++ b/src/v3/features/logging.md
@@ -266,7 +266,7 @@ A token is written as `%{name}`. `%%` writes a literal `%`. Any other text is co
 | `%{referer}`       | `Referer` header                                                                                    |
 | `%{timestamp}`     | Local time in the `%d/%b/%Y:%H:%M:%S %z` format, e.g. `29/May/2026:23:43:47 +0200`, honoring `TZ`  |
 
-A token without a value is written as `-`. `%{x_real_ip}` and `%{forwarded_for}` follow the `--log-x-real-ip`, `--log-forwarded-for` and `--trusted-proxies` options.
+A token without a value is written as `-`. `%{x_real_ip}` and `%{forwarded_for}` need no `--log-x-real-ip` or `--log-forwarded-for`: those options only change the default request line. When `--trusted-proxies` is set, the two tokens are logged only for requests from those IPs and are `-` otherwise.
 
 ### Output
 

From e9e3c359587fbe11dd34e734496accbf7ce187a2 Mon Sep 17 00:00:00 2001
From: Jose Quintana <joseluisquintana20@gmail.com>
Date: Sun, 1 Nov 2026 11:30:23 +0100
Subject: [PATCH 4/8] docs(logging): host token, health probes and value cut

- `%{host}` is the host sent by the client, before URL rewrites: the
  request URI authority, else the `Host` header.
- Health probes are `/livez` and `/readyz`.
- Escaped values longer than 4 KiB are cut and end with `...`.
---
 src/v3/features/logging.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/v3/features/logging.md b/src/v3/features/logging.md
index 9d6d1db..1006f5e 100644
--- a/src/v3/features/logging.md
+++ b/src/v3/features/logging.md
@@ -261,7 +261,7 @@ A token is written as `%{name}`. `%%` writes a literal `%`. Any other text is co
 | `%{remote_addr}`   | Client IP address                                                                                   |
 | `%{x_real_ip}`     | `X-Real-IP` address, see [Logging Client IP from X-Real-IP header](#logging-client-ip-from-x-real-ip-header) |
 | `%{forwarded_for}` | First `X-Forwarded-For` address, see [Logging Client IP from X-Forwarded-For header](#logging-client-ip-from-x-forwarded-for-header) |
-| `%{host}`          | `Host` header                                                                                       |
+| `%{host}`          | Host as sent by the client, before [URL Rewrites](./url-rewrites): the request URI authority (HTTP/2 `:authority` or an absolute-form request target) without user info, else the `Host` header |
 | `%{user_agent}`    | `User-Agent` header                                                                                 |
 | `%{referer}`       | `Referer` header                                                                                    |
 | `%{timestamp}`     | Local time in the `%d/%b/%Y:%H:%M:%S %z` format, e.g. `29/May/2026:23:43:47 +0200`, honoring `TZ`  |
@@ -270,7 +270,7 @@ A token without a value is written as `-`. `%{x_real_ip}` and `%{forwarded_for}`
 
 ### Output
 
-The rendered line is the `message` of a log entry with the `static_web_server::access_logs` target, at the `info` level, so it needs `--log-level info` or lower. Requests to the health endpoint are logged at the `debug` level. A request that fails before SWS builds a response is not logged. With the `json` format:
+The rendered line is the `message` of a log entry with the `static_web_server::access_logs` target, at the `info` level, so it needs `--log-level info` or lower. Requests to the [health endpoints](./health-endpoint) (`/livez` and `/readyz`) are logged at the `debug` level. A request that fails before SWS builds a response is not logged. With the `json` format:
 
 ```json
 {"timestamp":"2026-05-29T23:43:47.151533+02:00","level":"INFO","message":"192.168.1.126 - [29/May/2026:23:43:47 +0200] \"GET / HTTP/1.1\" 200 1250 \"-\" \"curl/8.7.1\"","target":"static_web_server::access_logs"}
@@ -280,6 +280,8 @@ The rendered line is the `message` of a log entry with the `static_web_server::a
 
 The URI and the `Host`, `User-Agent` and `Referer` headers come from the client. SWS writes bytes outside printable ASCII, `"` and `\` in them as `\xHH`, so a client cannot close a quoted field or inject a fake log line. For example, the `User-Agent` value `x" 200 "forged` is logged as `x\x22 200 \x22forged`.
 
+An escaped value longer than 4 KiB is cut and ends with `...`, so a large header cannot produce a large log line.
+
 ## File Logging
 
 By default **SWS** writes log records to standard error. The `--log-file` option additionally streams every record to a file on disk, in **addition** to `stderr`. This is useful for production deployments where `stderr` is captured by a service manager but a durable on-disk copy is also required.

From 38fd0b00b8b8fa3e011527de5bbc21ada944f30d Mon Sep 17 00:00:00 2001
From: Jose Quintana <joseluisquintana20@gmail.com>
Date: Sun, 1 Nov 2026 12:04:44 +0100
Subject: [PATCH 5/8] docs(logging): bytes and duration cover the sent body,
 name health probes

---
 src/v3/features/logging.md          | 8 ++++----
 src/v3/features/maintenance-mode.md | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/v3/features/logging.md b/src/v3/features/logging.md
index 1006f5e..e077335 100644
--- a/src/v3/features/logging.md
+++ b/src/v3/features/logging.md
@@ -232,7 +232,7 @@ curl "http://[::1]:8080" --header "X-Forwarded-For: <iframe src=//malware.attack
 
 ## Access Log Format
 
-**`SWS`** can write one access log line per request in a format you define, for example the nginx or NCSA combined format. The line is written after the response, so it carries the status code, the response size and the duration.
+**`SWS`** can write one access log line per request in a format you define, for example the nginx or NCSA combined format. The line is written once the response body is sent, so it carries the status code, the bytes sent and the duration.
 
 This feature is disabled by default. Set a format with the `--access-log-format` option, the equivalent [SERVER_ACCESS_LOG_FORMAT](./../configuration/env#server_access_log_format) env or the `access-log-format` key under `[general]` in the [TOML file](./../configuration/file). When a format is set, it replaces the `incoming request` line described in [Per-request logging](#per-request-logging).
 
@@ -256,8 +256,8 @@ A token is written as `%{name}`. `%%` writes a literal `%`. Any other text is co
 | `%{uri}`           | Request URI as sent by the client, before [URL Rewrites](./url-rewrites)                            |
 | `%{version}`       | HTTP version, e.g. `HTTP/1.1`                                                                       |
 | `%{status}`        | Response status code                                                                                |
-| `%{bytes}`         | Response `Content-Length`, or `-` when the response has none (e.g. compressed on the fly)           |
-| `%{duration}`      | Time to build the response in seconds, with microsecond precision                                   |
+| `%{bytes}`         | Response body bytes sent, after compression, or `-` when no body is sent (e.g. `HEAD`, `304`)      |
+| `%{duration}`      | Time until the response body is sent in seconds, with microsecond precision                         |
 | `%{remote_addr}`   | Client IP address                                                                                   |
 | `%{x_real_ip}`     | `X-Real-IP` address, see [Logging Client IP from X-Real-IP header](#logging-client-ip-from-x-real-ip-header) |
 | `%{forwarded_for}` | First `X-Forwarded-For` address, see [Logging Client IP from X-Forwarded-For header](#logging-client-ip-from-x-forwarded-for-header) |
@@ -270,7 +270,7 @@ A token without a value is written as `-`. `%{x_real_ip}` and `%{forwarded_for}`
 
 ### Output
 
-The rendered line is the `message` of a log entry with the `static_web_server::access_logs` target, at the `info` level, so it needs `--log-level info` or lower. Requests to the [health endpoints](./health-endpoint) (`/livez` and `/readyz`) are logged at the `debug` level. A request that fails before SWS builds a response is not logged. With the `json` format:
+The rendered line is the `message` of a log entry with the `static_web_server::access_logs` target, at the `info` level, so it needs `--log-level info` or lower. Requests to the [health endpoints](./health-endpoint) (`/livez` and `/readyz`) are logged at the `debug` level. A request that fails before SWS builds a response is not logged. An aborted download is logged with the bytes sent so far. With the `json` format:
 
 ```json
 {"timestamp":"2026-05-29T23:43:47.151533+02:00","level":"INFO","message":"192.168.1.126 - [29/May/2026:23:43:47 +0200] \"GET / HTTP/1.1\" 200 1250 \"-\" \"curl/8.7.1\"","target":"static_web_server::access_logs"}
diff --git a/src/v3/features/maintenance-mode.md b/src/v3/features/maintenance-mode.md
index 91cbf07..2207a17 100644
--- a/src/v3/features/maintenance-mode.md
+++ b/src/v3/features/maintenance-mode.md
@@ -8,7 +8,7 @@ The feature is disabled by default and can be controlled by the boolean `--maint
 
 ## How it works
 
-When the feature is enabled, SWS will respond _always_ with the specified (or default) status code and HTML content to every request ignoring all SWS features. Except the [Health check](./health-endpoint.md), [CORS](./cors.md) and [Basic Authentication](./basic-authentication.md) features.
+When the feature is enabled, SWS will respond _always_ with the specified (or default) status code and HTML content to every request ignoring all SWS features. Except the [health endpoints](./health-endpoint.md) (`/livez` and `/readyz`), [CORS](./cors.md) and [Basic Authentication](./basic-authentication.md) features.
 
 ## HTTP Status Code
 

From ba927bc464cc335c8f075808249c987424e65cc0 Mon Sep 17 00:00:00 2001
From: Vladimir Kutepov <frenzzy.man@gmail.com>
Date: Sun, 1 Nov 2026 21:11:50 +0700
Subject: [PATCH 6/8] docs(logging): align the access log format with the
 merged behavior and table style

---
 src/v3/features/logging.md | 43 +++++++++++++++++++++-----------------
 1 file changed, 24 insertions(+), 19 deletions(-)

diff --git a/src/v3/features/logging.md b/src/v3/features/logging.md
index e077335..f9e4052 100644
--- a/src/v3/features/logging.md
+++ b/src/v3/features/logging.md
@@ -232,7 +232,7 @@ curl "http://[::1]:8080" --header "X-Forwarded-For: <iframe src=//malware.attack
 
 ## Access Log Format
 
-**`SWS`** can write one access log line per request in a format you define, for example the nginx or NCSA combined format. The line is written once the response body is sent, so it carries the status code, the bytes sent and the duration.
+**`SWS`** can write one access log line per request in a format you define, for example the nginx or NCSA combined format. The line is written once the response is built, so it carries the status code, the response size and the duration.
 
 This feature is disabled by default. Set a format with the `--access-log-format` option, the equivalent [SERVER_ACCESS_LOG_FORMAT](./../configuration/env#server_access_log_format) env or the `access-log-format` key under `[general]` in the [TOML file](./../configuration/file). When a format is set, it replaces the `incoming request` line described in [Per-request logging](#per-request-logging).
 
@@ -250,35 +250,40 @@ access-log-format = '%{remote_addr} - [%{timestamp}] "%{method} %{uri} %{version
 
 A token is written as `%{name}`. `%%` writes a literal `%`. Any other text is copied as is. SWS validates the format at startup and refuses to start on an unknown token, an unclosed `%{` or a `%` followed by another character.
 
-| Token              | Value                                                                                               |
-| ------------------ | --------------------------------------------------------------------------------------------------- |
-| `%{method}`        | Request method, e.g. `GET`                                                                          |
-| `%{uri}`           | Request URI as sent by the client, before [URL Rewrites](./url-rewrites)                            |
-| `%{version}`       | HTTP version, e.g. `HTTP/1.1`                                                                       |
-| `%{status}`        | Response status code                                                                                |
-| `%{bytes}`         | Response body bytes sent, after compression, or `-` when no body is sent (e.g. `HEAD`, `304`)      |
-| `%{duration}`      | Time until the response body is sent in seconds, with microsecond precision                         |
-| `%{remote_addr}`   | Client IP address                                                                                   |
-| `%{x_real_ip}`     | `X-Real-IP` address, see [Logging Client IP from X-Real-IP header](#logging-client-ip-from-x-real-ip-header) |
-| `%{forwarded_for}` | First `X-Forwarded-For` address, see [Logging Client IP from X-Forwarded-For header](#logging-client-ip-from-x-forwarded-for-header) |
+| Token              | Value                                                                                                                                                                                           |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `%{method}`        | Request method, e.g. `GET`                                                                                                                                                                      |
+| `%{uri}`           | Path and query of the request URI as sent by the client, before [URL Rewrites](./url-rewrites), without scheme or authority                                                                     |
+| `%{version}`       | HTTP version, e.g. `HTTP/1.1`                                                                                                                                                                   |
+| `%{status}`        | Response status code                                                                                                                                                                            |
+| `%{bytes}`         | Value of the response `Content-Length` header, or `-` when the header is absent or zero (e.g. compressed or chunked responses, `HEAD`, `304`)                                                   |
+| `%{duration}`      | Time from the start of request handling until the response is built, in seconds with microsecond precision                                                                                      |
+| `%{remote_addr}`   | Client IP address                                                                                                                                                                               |
+| `%{x_real_ip}`     | `X-Real-IP` address, see [Logging Client IP from X-Real-IP header](#logging-client-ip-from-x-real-ip-header)                                                                                    |
+| `%{forwarded_for}` | First `X-Forwarded-For` address, see [Logging Client IP from X-Forwarded-For header](#logging-client-ip-from-x-forwarded-for-header)                                                            |
 | `%{host}`          | Host as sent by the client, before [URL Rewrites](./url-rewrites): the request URI authority (HTTP/2 `:authority` or an absolute-form request target) without user info, else the `Host` header |
-| `%{user_agent}`    | `User-Agent` header                                                                                 |
-| `%{referer}`       | `Referer` header                                                                                    |
-| `%{timestamp}`     | Local time in the `%d/%b/%Y:%H:%M:%S %z` format, e.g. `29/May/2026:23:43:47 +0200`, honoring `TZ`  |
+| `%{user_agent}`    | `User-Agent` header                                                                                                                                                                             |
+| `%{referer}`       | `Referer` header                                                                                                                                                                                |
+| `%{timestamp}`     | Local time in the `%d/%b/%Y:%H:%M:%S %z` format, e.g. `29/May/2026:23:43:47 +0200`, honoring `TZ`                                                                                               |
 
-A token without a value is written as `-`. `%{x_real_ip}` and `%{forwarded_for}` need no `--log-x-real-ip` or `--log-forwarded-for`: those options only change the default request line. When `--trusted-proxies` is set, the two tokens are logged only for requests from those IPs and are `-` otherwise.
+A token without a value, or with an empty one, is written as `-`. `%{x_real_ip}` and `%{forwarded_for}` need no `--log-x-real-ip` or `--log-forwarded-for`: those options only change the default request line. When `--trusted-proxies` is set, the two tokens are logged only for requests from those IPs and are `-` otherwise.
 
 ### Output
 
-The rendered line is the `message` of a log entry with the `static_web_server::access_logs` target, at the `info` level, so it needs `--log-level info` or lower. Requests to the [health endpoints](./health-endpoint) (`/livez` and `/readyz`) are logged at the `debug` level. A request that fails before SWS builds a response is not logged. An aborted download is logged with the bytes sent so far. With the `json` format:
+The rendered line is the `message` of a log entry with the `static_web_server::access_logs` target, at the `info` level, so it needs `--log-level info` or lower. Requests to the [health endpoints](./health-endpoint) (`/livez` and `/readyz`) are logged at the `debug` level. A request that fails before SWS builds a response is not logged. With the `json` format:
 
 ```json
-{"timestamp":"2026-05-29T23:43:47.151533+02:00","level":"INFO","message":"192.168.1.126 - [29/May/2026:23:43:47 +0200] \"GET / HTTP/1.1\" 200 1250 \"-\" \"curl/8.7.1\"","target":"static_web_server::access_logs"}
+{
+  "timestamp": "2026-05-29T23:43:47.151533+02:00",
+  "level": "INFO",
+  "message": "192.168.1.126 - [29/May/2026:23:43:47 +0200] \"GET / HTTP/1.1\" 200 1250 \"-\" \"curl/8.7.1\"",
+  "target": "static_web_server::access_logs"
+}
 ```
 
 ### Escaping
 
-The URI and the `Host`, `User-Agent` and `Referer` headers come from the client. SWS writes bytes outside printable ASCII, `"` and `\` in them as `\xHH`, so a client cannot close a quoted field or inject a fake log line. For example, the `User-Agent` value `x" 200 "forged` is logged as `x\x22 200 \x22forged`.
+The URI and the `Host`, `User-Agent` and `Referer` headers come from the client. SWS writes bytes outside printable ASCII, `"` and `\` in them as `\xHH` (uppercase hex), so a client cannot close a quoted field or inject a fake log line. For example, the `User-Agent` value `x" 200 "forged` is logged as `x\x22 200 \x22forged`.
 
 An escaped value longer than 4 KiB is cut and ends with `...`, so a large header cannot produce a large log line.
 

From a13ffc4141eca3e82e4cdeb67ea303792338a96b Mon Sep 17 00:00:00 2001
From: Vladimir Kutepov <frenzzy.man@gmail.com>
Date: Sun, 1 Nov 2026 21:18:04 +0700
Subject: [PATCH 7/8] docs(logging): log the access line when the response body
 finishes

---
 src/v3/features/logging.md | 34 +++++++++++++++++-----------------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/src/v3/features/logging.md b/src/v3/features/logging.md
index f9e4052..04ca06c 100644
--- a/src/v3/features/logging.md
+++ b/src/v3/features/logging.md
@@ -232,7 +232,7 @@ curl "http://[::1]:8080" --header "X-Forwarded-For: <iframe src=//malware.attack
 
 ## Access Log Format
 
-**`SWS`** can write one access log line per request in a format you define, for example the nginx or NCSA combined format. The line is written once the response is built, so it carries the status code, the response size and the duration.
+**`SWS`** can write one access log line per request in a format you define, for example the nginx or NCSA combined format. The line is written when the response body is finished, so it carries the status code, the number of body bytes sent and the duration of the whole transfer.
 
 This feature is disabled by default. Set a format with the `--access-log-format` option, the equivalent [SERVER_ACCESS_LOG_FORMAT](./../configuration/env#server_access_log_format) env or the `access-log-format` key under `[general]` in the [TOML file](./../configuration/file). When a format is set, it replaces the `incoming request` line described in [Per-request logging](#per-request-logging).
 
@@ -250,27 +250,27 @@ access-log-format = '%{remote_addr} - [%{timestamp}] "%{method} %{uri} %{version
 
 A token is written as `%{name}`. `%%` writes a literal `%`. Any other text is copied as is. SWS validates the format at startup and refuses to start on an unknown token, an unclosed `%{` or a `%` followed by another character.
 
-| Token              | Value                                                                                                                                                                                           |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `%{method}`        | Request method, e.g. `GET`                                                                                                                                                                      |
-| `%{uri}`           | Path and query of the request URI as sent by the client, before [URL Rewrites](./url-rewrites), without scheme or authority                                                                     |
-| `%{version}`       | HTTP version, e.g. `HTTP/1.1`                                                                                                                                                                   |
-| `%{status}`        | Response status code                                                                                                                                                                            |
-| `%{bytes}`         | Value of the response `Content-Length` header, or `-` when the header is absent or zero (e.g. compressed or chunked responses, `HEAD`, `304`)                                                   |
-| `%{duration}`      | Time from the start of request handling until the response is built, in seconds with microsecond precision                                                                                      |
-| `%{remote_addr}`   | Client IP address                                                                                                                                                                               |
-| `%{x_real_ip}`     | `X-Real-IP` address, see [Logging Client IP from X-Real-IP header](#logging-client-ip-from-x-real-ip-header)                                                                                    |
-| `%{forwarded_for}` | First `X-Forwarded-For` address, see [Logging Client IP from X-Forwarded-For header](#logging-client-ip-from-x-forwarded-for-header)                                                            |
-| `%{host}`          | Host as sent by the client, before [URL Rewrites](./url-rewrites): the request URI authority (HTTP/2 `:authority` or an absolute-form request target) without user info, else the `Host` header |
-| `%{user_agent}`    | `User-Agent` header                                                                                                                                                                             |
-| `%{referer}`       | `Referer` header                                                                                                                                                                                |
-| `%{timestamp}`     | Local time in the `%d/%b/%Y:%H:%M:%S %z` format, e.g. `29/May/2026:23:43:47 +0200`, honoring `TZ`                                                                                               |
+| Token              | Value                                                                                                                                                                                            |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `%{method}`        | Request method, e.g. `GET`                                                                                                                                                                       |
+| `%{uri}`           | Path and query of the request URI as sent by the client, before [URL Rewrites](./url-rewrites), without scheme or authority                                                                      |
+| `%{version}`       | HTTP version, e.g. `HTTP/1.1`                                                                                                                                                                    |
+| `%{status}`        | Response status code                                                                                                                                                                             |
+| `%{bytes}`         | Number of response body bytes sent, after on-the-fly compression, without the headers. `-` when no body bytes were sent, always for `HEAD`, `204` and `304` (like `%b` in the Common Log Format) |
+| `%{duration}`      | Time from the start of request handling until the response body is finished, in seconds with microsecond precision                                                                               |
+| `%{remote_addr}`   | Client IP address                                                                                                                                                                                |
+| `%{x_real_ip}`     | `X-Real-IP` address, see [Logging Client IP from X-Real-IP header](#logging-client-ip-from-x-real-ip-header)                                                                                     |
+| `%{forwarded_for}` | First `X-Forwarded-For` address, see [Logging Client IP from X-Forwarded-For header](#logging-client-ip-from-x-forwarded-for-header)                                                             |
+| `%{host}`          | Host as sent by the client, before [URL Rewrites](./url-rewrites): the request URI authority (HTTP/2 `:authority` or an absolute-form request target) without user info, else the `Host` header  |
+| `%{user_agent}`    | `User-Agent` header                                                                                                                                                                              |
+| `%{referer}`       | `Referer` header                                                                                                                                                                                 |
+| `%{timestamp}`     | Local time when the line is written, in the Common Log Format, e.g. `29/May/2026:23:43:47 +0200`, honoring `TZ`                                                                                  |
 
 A token without a value, or with an empty one, is written as `-`. `%{x_real_ip}` and `%{forwarded_for}` need no `--log-x-real-ip` or `--log-forwarded-for`: those options only change the default request line. When `--trusted-proxies` is set, the two tokens are logged only for requests from those IPs and are `-` otherwise.
 
 ### Output
 
-The rendered line is the `message` of a log entry with the `static_web_server::access_logs` target, at the `info` level, so it needs `--log-level info` or lower. Requests to the [health endpoints](./health-endpoint) (`/livez` and `/readyz`) are logged at the `debug` level. A request that fails before SWS builds a response is not logged. With the `json` format:
+The rendered line is the `message` of a log entry with the `static_web_server::access_logs` target, at the `info` level, so it needs `--log-level info` or lower. Requests to the [health endpoints](./health-endpoint) (`/livez` and `/readyz`) are logged at the `debug` level. A request that fails before SWS builds a response is not logged. If the client closes the connection before the body is fully sent, the line is still written, with the bytes sent so far and the time until the transfer ended. With the `json` format:
 
 ```json
 {

From 5a4442b99171dcbb9108b48d4c375b110b7d22b3 Mon Sep 17 00:00:00 2001
From: Jose Quintana <joseluisquintana20@gmail.com>
Date: Sun, 1 Nov 2026 17:24:30 +0100
Subject: [PATCH 8/8] docs(logging): %{uri} logs the CONNECT target, name the
 default log level

static-web-server/static-web-server#794 logs the authority-form `CONNECT`
target in `%{uri}` instead of `/`, and skips the access line when its level
is filtered, which the default `-g error` does.
---
 src/v3/features/logging.md | 32 ++++++++++++++++----------------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/src/v3/features/logging.md b/src/v3/features/logging.md
index c0a4cc8..069fe2d 100644
--- a/src/v3/features/logging.md
+++ b/src/v3/features/logging.md
@@ -250,27 +250,27 @@ access-log-format = '%{remote_addr} - [%{timestamp}] "%{method} %{uri} %{version
 
 A token is written as `%{name}`. `%%` writes a literal `%`. Any other text is copied as is. SWS validates the format at startup and refuses to start on an unknown token, an unclosed `%{` or a `%` followed by another character.
 
-| Token              | Value                                                                                                                                                                                            |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `%{method}`        | Request method, e.g. `GET`                                                                                                                                                                       |
-| `%{uri}`           | Path and query of the request URI as sent by the client, before [URL Rewrites](./url-rewrites), without scheme or authority                                                                      |
-| `%{version}`       | HTTP version, e.g. `HTTP/1.1`                                                                                                                                                                    |
-| `%{status}`        | Response status code                                                                                                                                                                             |
-| `%{bytes}`         | Number of response body bytes sent, after on-the-fly compression, without the headers. `-` when no body bytes were sent, always for `HEAD`, `204` and `304` (like `%b` in the Common Log Format) |
-| `%{duration}`      | Time from the start of request handling until the response body is finished, in seconds with microsecond precision                                                                               |
-| `%{remote_addr}`   | Client IP address                                                                                                                                                                                |
-| `%{x_real_ip}`     | `X-Real-IP` address, see [Logging Client IP from X-Real-IP header](#logging-client-ip-from-x-real-ip-header)                                                                                     |
-| `%{forwarded_for}` | First `X-Forwarded-For` address, see [Logging Client IP from X-Forwarded-For header](#logging-client-ip-from-x-forwarded-for-header)                                                             |
-| `%{host}`          | Host as sent by the client, before [URL Rewrites](./url-rewrites): the request URI authority (HTTP/2 `:authority` or an absolute-form request target) without user info, else the `Host` header  |
-| `%{user_agent}`    | `User-Agent` header                                                                                                                                                                              |
-| `%{referer}`       | `Referer` header                                                                                                                                                                                 |
-| `%{timestamp}`     | Local time when the line is written, in the Common Log Format, e.g. `29/May/2026:23:43:47 +0200`, honoring `TZ`                                                                                  |
+| Token              | Value                                                                                                                                                                                                   |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `%{method}`        | Request method, e.g. `GET`                                                                                                                                                                              |
+| `%{uri}`           | Path and query of the request URI as sent by the client, before [URL Rewrites](./url-rewrites), without scheme or authority. For a `CONNECT` request, the authority-form target, e.g. `example.com:443` |
+| `%{version}`       | HTTP version, e.g. `HTTP/1.1`                                                                                                                                                                           |
+| `%{status}`        | Response status code                                                                                                                                                                                    |
+| `%{bytes}`         | Number of response body bytes sent, after on-the-fly compression, without the headers. `-` when no body bytes were sent, always for `HEAD`, `204` and `304` (like `%b` in the Common Log Format)        |
+| `%{duration}`      | Time from the start of request handling until the response body is finished, in seconds with microsecond precision                                                                                      |
+| `%{remote_addr}`   | Client IP address                                                                                                                                                                                       |
+| `%{x_real_ip}`     | `X-Real-IP` address, see [Logging Client IP from X-Real-IP header](#logging-client-ip-from-x-real-ip-header)                                                                                            |
+| `%{forwarded_for}` | First `X-Forwarded-For` address, see [Logging Client IP from X-Forwarded-For header](#logging-client-ip-from-x-forwarded-for-header)                                                                    |
+| `%{host}`          | Host as sent by the client, before [URL Rewrites](./url-rewrites): the request URI authority (HTTP/2 `:authority` or an absolute-form request target) without user info, else the `Host` header         |
+| `%{user_agent}`    | `User-Agent` header                                                                                                                                                                                     |
+| `%{referer}`       | `Referer` header                                                                                                                                                                                        |
+| `%{timestamp}`     | Local time when the line is written, in the Common Log Format, e.g. `29/May/2026:23:43:47 +0200`, honoring `TZ`                                                                                         |
 
 A token without a value, or with an empty one, is written as `-`. `%{x_real_ip}` and `%{forwarded_for}` need no `--log-x-real-ip` or `--log-forwarded-for`: those options only change the default request line. When `--trusted-proxies` is set, the two tokens are logged only for requests from those IPs and are `-` otherwise.
 
 ### Output
 
-The rendered line is the `message` of a log entry with the `static_web_server::access_logs` target, at the `info` level, so it needs `--log-level info` or lower. Requests to the [health endpoints](./health-endpoint) (`/livez` and `/readyz`) are logged at the `debug` level. A request that fails before SWS builds a response is not logged. If the client closes the connection before the body is fully sent, the line is still written, with the bytes sent so far and the time until the transfer ended. With the `json` format:
+The rendered line is the `message` of a log entry with the `static_web_server::access_logs` target, at the `info` level. The default log level is `error`, so pass `--log-level info` (or `debug`, `trace`) to see it. Requests to the [health endpoints](./health-endpoint) (`/livez` and `/readyz`) are logged at the `debug` level. A request that fails before SWS builds a response is not logged. If the client closes the connection before the body is fully sent, the line is still written, with the bytes sent so far and the time until the transfer ended. With the `json` format:
 
 ```json
 {