29.1 Confguring Access Logs

Problem

You need to configure access log formats to add embedded variables

to your request logs.

问题

需要配置自定义格式的访问日志(access log)

Solution

Configure an access log format:

http {
    log_format geoproxy
    '[$time_local] $remote_addr '
    '$realip_remote_addr $remote_user '
    '$request_method $server_protocol '
    '$scheme $server_name $uri $status '
    '$request_time $body_bytes_sent '
    '$geoip_city_country_code3 $geoip_region '
    '"$geoip_city" $http_x_forwarded_for '
    '$upstream_status $upstream_response_time '
    '"$http_referer" "$http_user_agent"';
    ...
}

This log format configuration is named geoproxy and uses a num‐

ber of embedded variables to demonstrate the power of NGINX log‐

ging. This configuration shows the local time on the server when the

request was made, the IP address that opened the connection, and

the IP of the client as NGINX understands it per geoip_proxy or

realip_header instructions. $remote_user shows the username of

the user authenticated by basic authentication, followed by the

request method and protocol, as well as the scheme, such as HTTP

or HTTPS. The server name match is logged as well as the request

URI and the return status code. Statistics logged include the pro‐

cessing time in milliseconds and the size of the body sent to the cli‐

ent. Information about the country, region, and city are logged. The

HTTP header X-Forwarded-For is included to show if the request is

being forwarded by another proxy. The upstream module enables

some embedded variables that we’ve used that show the status

returned from the upstream server and how long the upstream

request takes to return. Lastly we’ve logged some information about

where the client was referred from and what browser the client is

using. The log_format directive is only valid within the HTTP con‐

text.

解决方案

配置访问日志格式：

http {
    log_format geoproxy
    '[$time_local] $remote_addr '
    '$realip_remote_addr $remote_user '
    '$request_method $server_protocol '
    '$scheme $server_name $uri $status '
    '$request_time $body_bytes_sent '
    '$geoip_city_country_code3 $geoip_region '
    '"$geoip_city" $http_x_forwarded_for '
    '$upstream_status $upstream_response_time '
    '"$http_referer" "$http_user_agent"';
    ...
}

这个日志配置被命名为 geoproxy，它使用许多 NGINX 变量来演示 NGINX 日志记录

功能。接下来详细讲解配置选项中各个变量的具体含义：当用户发起请求时，会记

录服务器时间( $time_local )、用于 NGINX 处理 geoip_proxy 和 realip_header

指令的打开连接的 IP 地址和客户端 IP 地址；$remote_user 值为通过基本授权的用

户名称；之后记录 HTTP 请求方法( $request_method )、协议( $server_protocol )

和 HTTP 方法( $scheme：http 或 https ) ；当然还有服务器名称( $server_name )

、请求的 URI 和响应状态码。除基本信息外，还有一些统计的结果数据：包括请求

处理的毫秒级时间($request_time)、服务器响应的数据块大小( $body_bytes_sent )。

此外，客户端所在国家( $geoip_city_country_code3 )、地区( $geoip_region )和城

市信息( $geoip_city )也被记录在内。变量 $http_x_forwarded_for

用于记录由其它代理服务器发起的请求的 X-Forwarded-For 头消息。upstream 模

块中一些数据也被记录到日志里：被代理服务器的响应状态码( $upstream_status )

和服务器处理时间( $upstream_response_time )。请求来源( $http_referer )和用

户代理( $http_user_agent ) 也有被记录在日志里。从上面可以看出 NGINX 日

志记录功能还是非常强大和灵活的，不过用于定义日志格式的 log_format 指

令仅适用于 http 块级指令内，这一点需要注意。

This log configuration renders a log entry that looks like the follow‐

ing:

[25/Nov/2016:16:20:42 +0000] 10.0.1.16 192.168.0.122 Derek
GET HTTP/1.1 http www.example.com / 200 0.001 370 USA MI
"Ann Arbor" - 200 0.001 "-" "curl/7.47.0"

To use this log format, use the access_log directive, providing a

logfile path and the format name geoproxy as parameters:

server {
    access_log /var/log/nginx/access.log geoproxy;
    ...
}

The access_log directive takes a logfile path and the format name

as parameters. This directive is valid in many contexts and in each

context can have a different log path and or log format.

这个日志的每个日志记录结果类似下面示例：

[25/Nov/2016:16:20:42 +0000] 10.0.1.16 192.168.0.122 Derek
GET HTTP/1.1 http www.example.com / 200 0.001 370 USA MI
"Ann Arbor" - 200 0.001 "-" "curl/7.47.0"

如果需要使用这个日志配置，需要结合使用 access_log 指令，access_log

指令接收一个日志目录和使用的配置名作为参数：

server {
    access_log /var/log/nginx/access.log geoproxy;
    ...
}

access_log 能在多个上下文使用，每个上下文中可以定义各自的日志目录

和日志记录格式。

Discussion

The log module in NGINX allows you to configure log formats for

many different scenarios to log to numerous logfiles as you see fit.

You may find it useful to configure a different log format for each

context, where you use different modules and employ those mod‐

ules’ embedded variables, or a single, catchall format that provides

all necessary information you could ever want. It’s also possible to

structure format to log in JSON or XML. These logs will aid you in

understanding your traffic patterns, client usage, who your clients

are, and where they’re coming from. Access logs can also aid you in

finding lag in responses and issues with upstream servers or particu‐

lar URIs. Access logs can be used to parse and play back traffic pat‐

terns in test environments to mimic real user interaction. There’s

limitless possibility to logs when troubleshooting, debugging, or

analyzing your application or market.

结论

NGINX 中的日志模块允许您为不同的场景配置日志格式，以便查看不同的日志文件。

在实际运用中，为不同上下文配置不同的日志会非常有用，记录的日志内容可以简单

的信息，也可以事无巨细的记录所有必要信息。不仅如此，日志内容除了支持文本

也能记录 JSON 格式和 XML 格式数据。实际上 NGINX 日志有助于您了解服务器流量、

客户端使用情况和客户端来源等信息。此外，访问日志还可以帮助您定位与上游服务

器或特定 uri 相关的响应和问题；对于测试来讲，访问日志同样有用，它可以用于

分析流量情况，模拟真实的用户交互场景。日志在故障排除、调试、应用分析及业

务调整中作用是不可或缺的。