Kubernetes Ingress-Nginx 日志格式配置详解

王海高Eudora

于 2025-06-02 09:02:13 发布

阅读量255

点赞数 3

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00957/article/details/148374988

Kubernetes Ingress-Nginx 日志格式配置详解

ingress-nginx Ingress-NGINX Controller for Kubernetes 项目地址: https://gitcode.com/gh_mirrors/in/ingress-nginx

前言

在 Kubernetes 集群中使用 Ingress-Nginx 作为入口控制器时，日志记录是监控和故障排查的重要依据。本文将深入解析 Ingress-Nginx 的日志格式配置，帮助运维人员和开发者更好地理解和利用日志信息。

默认日志格式解析

Ingress-Nginx 使用自定义的日志格式 upstreaminfo，相比标准 Nginx 日志格式，它包含了更多与 Kubernetes 和上游服务相关的信息。以下是默认配置的详细解析：

log_format upstreaminfo
    '$remote_addr - $remote_user [$time_local] "$request" '
    '$status $body_bytes_sent "$http_referer" "$http_user_agent" '
    '$request_length $request_time [$proxy_upstream_name] [$proxy_alternative_upstream_name] $upstream_addr '
    '$upstream_response_length $upstream_response_time $upstream_status $req_id';

日志字段详解

基础请求信息

| 字段 | 说明 | 示例 | |------|------|------| | $remote_addr | 客户端 IP 地址 | 192.168.1.100 | | $remote_user | 通过 Basic 认证的用户名 | admin | | $time_local | 本地时间(通用日志格式) | 10/Oct/2023:13:55:36 +0800 | | $request | 完整的原始请求行 | GET /api/v1/users HTTP/1.1 | | $status | HTTP 响应状态码 | 200 | | $body_bytes_sent | 发送给客户端的响应体字节数(不含响应头) | 1024 |

客户端信息

| 字段 | 说明 | 示例 | |------|------|------| | $http_referer | Referer 请求头值 | https://example.com | | $http_user_agent | User-Agent 请求头值 | Mozilla/5.0 |

请求处理指标

| 字段 | 说明 | 示例 | |------|------|------| | $request_length | 请求总长度(包括请求行、头部和请求体) | 512 | | $request_time | 从读取客户端第一个字节开始的总处理时间 | 0.123 |

Kubernetes 相关字段

| 字段 | 说明 | 示例 | |------|------|------| | $proxy_upstream_name | 上游服务名称格式: upstream-<命名空间>-<服务名>-<端口> | upstream-default-myapp-8080 | | $proxy_alternative_upstream_name | 备选上游服务名称(格式同上) | upstream-default-myapp-backup-8080 | | $upstream_addr | 上游服务器地址(可能多个) | 10.244.1.2:8080, 10.244.1.3:8080 |

上游服务响应信息

| 字段 | 说明 | 示例 | |------|------|------| | $upstream_response_length | 上游服务响应体长度 | 2048 | | $upstream_response_time | 从上游服务接收响应的时间(毫秒精度) | 0.045 | | $upstream_status | 上游服务的响应状态码 | 200 | | $req_id | 请求 ID(来自 X-Request-ID 头或自动生成) | abc123def456 |

其他可用变量

除了默认日志格式中的变量，Ingress-Nginx 还提供了以下与 Kubernetes 相关的变量：

| 变量 | 说明 | 示例 | |------|------|------| | $namespace | Ingress 所属命名空间 | default | | $ingress_name | Ingress 资源名称 | my-ingress | | $service_name | 服务名称 | my-service | | $service_port | 服务端口 | 8080 |

实际应用场景

1. 性能分析

通过 $request_time 和 $upstream_response_time 可以分析请求处理时间分布，找出性能瓶颈：

如果 $request_time 远大于 $upstream_response_time，可能 Nginx 处理或网络传输存在问题
如果 $upstream_response_time 较大，说明上游服务处理较慢

2. 流量路由验证

通过 $proxy_upstream_name 可以确认请求是否被路由到正确的后端服务，特别在以下场景很有用：

金丝雀部署验证
A/B 测试流量分配
多版本服务路由检查

3. 请求追踪

$req_id 可用于跨服务追踪请求，建议：

在客户端生成唯一 ID 并通过 X-Request-ID 头传递
在所有相关服务的日志中记录此 ID
使用日志聚合工具进行关联分析

自定义日志格式

虽然默认格式已经相当全面，但您可以根据需要自定义日志格式。例如，添加 Kubernetes 命名空间信息：

log_format custom_format
    '$remote_addr - $remote_user [$time_local] "$request" '
    '$status $body_bytes_sent "$http_referer" "$http_user_agent" '
    '$namespace $ingress_name $service_name $service_port '
    '$request_time $upstream_response_time $upstream_status';