29.4 Request Tracing

Problem

You need to correlate NGINX logs with application logs to have an

end-to-end understanding of a request.

问题

需要结合 NGINX 日志和应用日志，查看请求调用栈。

Solution

Use the request identifying variable and pass it to your application

to log as well:

log_format trace '$remote_addr - $remote_user [$time_local] '
                '"$request" $status $body_bytes_sent '
                '"$http_referer" "$http_user_agent" '
                '"$http_x_forwarded_for" $request_id';
upstream backend {
    server 10.0.0.42;
}
server {
    listen 80;

    add\_header X-Request-ID $request\_id; \# Return to client

    location / {    
        proxy_pass http://backend;    
        proxy_set_header X-Request-ID $request_id; \#Pass to app    
        access_log /var/log/nginx/access_trace.log trace;    
    }
}

In this example configuration, a log_format named trace is set up,

and the variable $request_id is used in the log. This $request_id

variable is also passed to the upstream application by use of the

proxy_set_header directive to add the request ID to a header when

making the upstream request. The request ID is also passed back to

the client through use of the add_header directive setting the

request ID in a response header.

解决方案

使用 request 标识，并将标识写入到应用日志里：

log_format trace '$remote_addr - $remote_user [$time_local] '
                '"$request" $status $body_bytes_sent '
                '"$http_referer" "$http_user_agent" '
                '"$http_x_forwarded_for" $request_id';
upstream backend {
    server 10.0.0.42;
}
server {
    listen 80;

    add\_header X-Request-ID $request\_id; \# Return to client

    location / {    
        proxy_pass http://backend;    
        proxy_set_header X-Request-ID $request_id; \#Pass to app    
        access_log /var/log/nginx/access_trace.log trace;    
    }
}

示例中，配置了名为 trace 的访问日志格式，并在日志中使用 $request_id

参数。同时，通过 proxy_set_header 指令将 request 标记(request ID)设

置到请求头里，当请求匹配到 location / 前缀，请求被转发到 upstream

模块，这样同一个 request 标识就能记录到应用服务器日志里；此外，通过

add_header 指令将 reqeust 标识设置到响应消息头，供客户端使用。

Discussion

Made available in NGINX Plus R10 and NGINX version 1.11.0, the

$request_id provides a randomly generated string of 32 hexadeci‐

mal characters that can be used to uniquely identify requests. By

passing this identifier to the client as well as to the application, you

can correlate your logs with the requests you make. From the front‐

end client, you will receive this unique string as a response header

and can use it to search your logs for the entries that correspond.

You will need to instruct your application to capture and log this

header in its application logs to create a true end-to-end relationship

between the logs. With this advancement, NGINX makes it possible

to trace requests through your application stack.

结论

该功能在 NGINX Plus R10 版本和 NGINX 开源版的 1.11.0 版本可用，

$request_id 提供了一个随机生成的 32 个十六进制字符的字符串，这些

字符可以用来唯一地标识请求。通过将此标识符传递给客户端和应用服务器，

可以将日志与请求关联起来。客户端会收到唯一的 request 标识，服务端

也能使用该标识进行日志筛选。应用服务器使用时，需要获取这个消息头，

以建立日之间的关联。基于这个特性，NGINX 能够构建从客户端请求到应用

服务器做出响应的整个请求调用周期的所有日志信息之间的关联。