What is the difference between $uri and $request_uri?

$request_uri is the full original request URI including the query string and exactly as the client sent it. $uri is the current normalised URI without the query string, and it can change during internal redirects and rewrites, so the two often differ after a rewrite.

How do I read an arbitrary request header?

Use the $http_ prefix followed by the header name lowercased with hyphens turned into underscores. For example the User-Agent header is available as $http_user_agent and X-Forwarded-For as $http_x_forwarded_for.

Which variables are most useful in log_format?

Common choices are $remote_addr, $request, $status, $body_bytes_sent, $http_referer, $http_user_agent, $request_time and the upstream timing variables like $upstream_response_time, which together give a full picture of each request.

What does $proxy_add_x_forwarded_for do?

It returns the incoming X-Forwarded-For header with the current $remote_addr appended. Setting proxy_set_header X-Forwarded-For with this variable correctly chains the client IP when nginx sits behind or in front of other proxies.

Are the $upstream_ variables available before the upstream responds?

They are populated as the upstream interaction progresses, so they are most reliable in log_format after the response completes. Variables like $upstream_addr, $upstream_status and $upstream_response_time reflect the server that handled the request.

nginx Built-in Variables Reference

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

nginx built-in variables

nginx exposes a large set of $variables you can reference in directives like log_format, proxy_set_header, return, map and if. They expose request metadata, proxy and upstream details, and TLS information. This reference groups the common ones by source module and explains each.

How it works

Variables are evaluated per request. Some are fixed names ($remote_addr, $status); others follow a dynamic pattern where part of the name is supplied by you:

log_format main '$remote_addr "$request" $status '
                '$body_bytes_sent "$http_user_agent" '
                'rt=$request_time urt=$upstream_response_time';

location /api/ {
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_pass http://backend;
}

The dynamic prefixes are $http_NAME (request headers), $sent_http_NAME (response headers), $arg_NAME (query arguments) and $cookie_NAME (cookies), where NAME is lowercased with hyphens replaced by underscores.

Tips and notes

$request_uri keeps the query string and original form; $uri is normalised and rewrite-aware.
Use $proxy_add_x_forwarded_for to correctly append the client IP when chaining proxies.
Upstream timing variables ($upstream_response_time, $upstream_connect_time) are great for latency logs.
The $ssl_ family only has values on HTTPS server blocks with TLS negotiated.