Skip to content

docs: one per-request log line with the response status (v3) #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
joseluisq merged 3 commits into from
Nov 2, 2026
Merged

docs: one per-request log line with the response status (v3) #17

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
748f54b
docs: one per-request log line with the response status (v3)
frenzzy Oct 26, 2026
fec5fb7
Merge remote-tracking branch 'origin/master' into docs/log-response-s…
joseluisq Nov 2, 2026
785f7aa
docs: sync per-request logging with the merged code (v3)
joseluisq Nov 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/v3/configuration/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ Options:
--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. 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 the remote address of each request, if available [env: SERVER_LOG_REMOTE_ADDRESS=] [default: false] [possible values: true, false]
--log-x-real-ip [<LOG_X_REAL_IP>]
Log the X-Real-IP header for remote IP information [env: SERVER_LOG_X_REAL_IP=] [default: false] [possible values: true, false]
--log-forwarded-for [<LOG_FORWARDED_FOR>]
Expand Down
2 changes: 1 addition & 1 deletion src/v3/configuration/env.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -181,7 +181,7 @@ Custom access log format using the `%{token}` syntax. When set, SWS logs one lin

## SERVER_LOG_REMOTE_ADDRESS

Log incoming requests information along with its remote address if available using the `info` log level. Default `false`.
Log the remote address of each request, if available. Default `false`.

## SERVER_LOG_X_REAL_IP

Expand Down
25 changes: 15 additions & 10 deletions src/v3/features/logging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ static-web-server -p 8787 -d ./public/ -g info --log-format pretty
```log
2026-05-29T23:44:04.703047+02:00 INFO static_web_server::server: starting Static Web Server name="static-web-server" version="2.42.0"
2026-05-29T23:44:04.704137+02:00 INFO static_web_server::compression: auto compression enabled=true formats=deflate,gzip,brotli,zstd compression_level=Default
2026-05-29T23:44:05.724579+02:00 INFO static_web_server::log_addr: incoming request method=GET uri=/
2026-05-29T23:44:05.724579+02:00 INFO static_web_server::log_addr: response method=GET uri=/ status=200
```

## Log Date-Timestamp
Expand Down Expand Up @@ -90,20 +90,21 @@ static-web-server -p 8788 -d ./public/ -g trace --log-format pretty --log-with-a

## Per-request logging

When the level is `info` or lower, SWS logs each request with the `incoming request` message. Requests to the [health endpoints](./health-endpoint.md) (`/livez` and `/readyz`) are logged at `debug` level instead, to avoid noise from frequent probes.
When the level is `info` or lower, SWS logs one line per request with the `response` message, once the response body is sent or aborted. The line carries the request method, the URI as sent by the client (before [URL Rewrites](./url-rewrites)) and the response `status`, including for responses that end the request early, such as redirects or `405 Method Not Allowed`. Requests to the [health endpoints](./health-endpoint.md) (`/livez` and `/readyz`) are logged at `debug` level instead, to avoid noise from frequent probes.

```json
{
"timestamp": "2026-05-29T23:43:47.151533+02:00",
"level": "INFO",
"message": "incoming request",
"message": "response",
"method": "GET",
"uri": "/",
"status": 200,
"target": "static_web_server::log_addr"
}
```

The `remote_addr`, `x_real_ip` and `real_remote_ip` fields are added when the corresponding logging options are enabled and a value is available. Fields without a value are omitted.
No line is logged when SWS fails to build a response. The `remote_addr`, `x_real_ip` and `real_remote_ip` fields are added when the corresponding logging options are enabled and a value is available. Fields without a value are omitted.

## Log Remote Addresses

Expand All @@ -117,7 +118,7 @@ static-web-server -a "0.0.0.0" -p 8080 -d docker/public/ -g info --log-remote-ad

```json
{"timestamp":"2026-05-29T23:43:47.071681+02:00","level":"INFO","message":"log requests with remote IP addresses","enabled":true,"target":"static_web_server::log_addr"}
{"timestamp":"2026-05-29T23:43:47.151533+02:00","level":"INFO","message":"incoming request","method":"GET","uri":"/","remote_addr":"192.168.1.126","target":"static_web_server::log_addr"}
{"timestamp":"2026-05-29T23:43:47.151533+02:00","level":"INFO","message":"response","method":"GET","uri":"/","status":200,"remote_addr":"192.168.1.126","target":"static_web_server::log_addr"}
```

## Logging Client IP from X-Real-IP header
Expand All @@ -130,9 +131,10 @@ Enable logging of the `X-Real-IP` header with the `--log-x-real-ip` option or th
{
"timestamp": "2026-05-29T23:43:47.151533+02:00",
"level": "INFO",
"message": "incoming request",
"message": "response",
"method": "GET",
"uri": "/",
"status": 200,
"x_real_ip": "203.0.113.195",
"target": "static_web_server::log_addr"
}
Expand Down Expand Up @@ -178,9 +180,10 @@ The request log includes the `real_remote_ip` field:
{
"timestamp": "2026-05-29T23:43:47.151533+02:00",
"level": "INFO",
"message": "incoming request",
"message": "response",
"method": "GET",
"uri": "/",
"status": 200,
"real_remote_ip": "203.0.113.195",
"target": "static_web_server::log_addr"
}
Expand All @@ -200,9 +203,10 @@ the log omits `real_remote_ip`:
{
"timestamp": "2026-05-29T23:43:47.151533+02:00",
"level": "INFO",
"message": "incoming request",
"message": "response",
"method": "GET",
"uri": "/",
"status": 200,
"target": "static_web_server::log_addr"
}
```
Expand All @@ -223,9 +227,10 @@ curl "http://[::1]:8080" --header "X-Forwarded-For: <iframe src=//malware.attack
{
"timestamp": "2026-05-29T23:43:47.151533+02:00",
"level": "INFO",
"message": "incoming request",
"message": "response",
"method": "GET",
"uri": "/",
"status": 200,
"target": "static_web_server::log_addr"
}
```
Expand All @@ -234,7 +239,7 @@ curl "http://[::1]:8080" --header "X-Forwarded-For: <iframe src=//malware.attack

**`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).
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 `response` line described in [Per-request logging](#per-request-logging).

```sh
static-web-server -p 8787 -d ./public/ -g info \
Expand Down