Traefik 日志文档
日志与访问日志
日志
日志涉及 Traefik 本身发生的一切（启动、配置、事件、关闭等）。
配置示例
YAML
log:
filePath: "/path/to/log-file.log"
format: json
level: INFOTOML
[log]
filePath = "/path/to/log-file.log"
format = "json"
level = "INFO"CLI
--log.filePath=/path/to/log-file.log
--log.format=json
--log.level=INFO配置选项
| 字段 | 描述 | 默认值 | 必填 |
|---|---|---|---|
log.filePath | 日志文件路径。默认写入标准输出。 | - | 否 |
log.format | 日志格式（common 或 json）。common 格式的字段不可自定义。 | "common" | 否 |
log.level | 日志级别（TRACE、DEBUG、INFO、WARN、ERROR、FATAL、PANIC）。 | ERROR | 否 |
log.noColor | 使用 common 格式时，禁用彩色输出。 | false | 否 |
log.maxSize | 日志轮转前最大大小（MB）。 | 100MB | 否 |
log.maxAge | 保留旧日志文件的最大天数。 | 0 | 否 |
log.maxBackups | 保留旧日志文件的最大数量。 | 0 | 否 |
log.compress | 轮转后 gzip 压缩日志文件。 | false | 否 |
OpenTelemetry
Traefik 支持 OpenTelemetry 日志记录。要启用 OpenTelemetry，需要在静态配置中设置：
experimental:
otlpLogs: true[experimental]
otlpLogs = true--experimental.otlpLogs=true警告
这是一个实验性功能。
Stdio 日志仍然可用
启用 OTLP 日志记录后，标准输出（stdio）日志仍然可用，并将与 OTLP 导出一起继续写入。
配置示例
experimental:
otlpLogs: true
log:
otlp:
http:
endpoint: https://collector:4318/v1/logs
headers:
Authorization: Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL配置选项
| 字段 | 描述 | 默认值 | 必填 |
|---|---|---|---|
log.otlp.serviceName | 所选后端中使用的 service 名称。 | "traefik" | 否 |
log.otlp.resourceAttributes | 发送到 collector 的其它 resource 属性。 | [] | 否 |
log.otlp.http | 指示导出器使用 HTTP 发送日志。 | 否 | |
log.otlp.http.endpoint | OpenTelemetry Collector 端点（格式 <scheme>://<host>:<port><path>）。 | https://localhost:4318/v1/logs | 否 |
log.otlp.http.headers | 其它请求头。 | [] | 否 |
log.otlp.http.tls | 客户端 TLS 配置。 | 否 | |
log.otlp.grpc | 指示导出器使用 gRPC 发送日志。 | 否 | |
log.otlp.grpc.endpoint | gRPC 端点（格式 <host>:<port>）。 | localhost:4317 | 否 |
log.otlp.grpc.headers | 其它请求头。 | [] | 否 |
log.otlp.grpc.insecure | 指示使用不安全协议。 | false | 否 |
log.otlp.grpc.tls | 客户端 TLS 配置。 | 否 |
resourceAttributes
resourceAttributes 选项允许设置与 traces 一起发送的 resource 属性。Traefik 也支持 OTEL_RESOURCE_ATTRIBUTES 环境变量来设置 resource 属性。
Kubernetes Resource Attributes Detection
此外，在 Kubernetes 集群中运行时，Traefik 会自动发现以下 Kubernetes resource attributes：
k8s.namespace.namek8s.pod.uidk8s.pod.name请注意，这种自动检测可能会失败，例如当 Traefik pod 以 host network 模式运行时。在这种情况下，你应使用该选项或环境变量提供属性。
访问日志
访问日志涉及 Traefik 处理的请求所发生的一切。
Stdio 日志在 OTLP 导出旁边默认未启用
如果你希望 Stdio 访问日志可用，请使用 accessLog.dualOutput 选项。
配置示例
accessLog:
# JSON 格式
format: json
# 过滤状态码、重试次数和最小时长
filters:
statusCodes:
- "200"
- "300-302"
retryAttempts: true
minDuration: "10ms"
fields:
# 默认保留所有字段
defaultMode: keep
names:
# 删除 ClientUserName 字段
ClientUsername: drop
headers:
# 默认保留所有 headers
defaultMode: keep
names:
# 隐藏 User-Agent header 值
User-Agent: redact
# 删除 Authorization header 值
Authorization: drop
queryParameters:
# 删除所有查询参数
defaultMode: drop[accessLog]
format = "json"
[accessLog.filters]
statusCodes = [ "200", "300-302" ]
retryAttempts = true
minDuration = "10ms"
[accessLog.fields]
defaultMode = "keep"
[accessLog.fields.names]
ClientUsername = "drop"
[accessLog.fields.headers]
defaultMode = "keep"
[accessLog.fields.headers.names]
User-Agent = "redact"
Authorization = "drop"
[accessLog.fields.queryParameters]
defaultMode = "drop"配置选项
| 字段 | 描述 | 默认值 | 必填 |
|---|---|---|---|
accesslog.filePath | 访问日志文件路径。 | 否 | |
accesslog.dualOutput | 即使配置了 OTLP，也强制使用 Stdio 日志记录。 | false | 否 |
accesslog.format | 日志格式：common（Traefik 扩展 CLF）、genericCLF（标准 CLF）或 json。 | "common" | 否 |
accesslog.bufferingSize | 异步写入日志时在内存中保留的日志行数。 | 0 | 否 |
accesslog.addInternals | 启用内部资源的访问日志。 | false | 否 |
accesslog.filters.statusCodes | 限制为指定状态码范围的请求。 | [] | 否 |
accesslog.filters.retryAttempts | 至少发生一次重试时保留访问日志。 | false | 否 |
accesslog.filters.minDuration | 保留请求耗时超过指定时长的访问日志。 | 0 | 否 |
accesslog.fields.defaultMode | 访问日志字段的默认模式（keep、redact 或 drop）。 | keep | 否 |
accesslog.fields.names | 在访问日志中显示的字段列表（格式 name:mode）。 | [] | 否 |
accesslog.fields.headers.defaultMode | headers 的默认模式。 | drop | 否 |
accesslog.fields.headers.names | 在访问日志中显示的 headers 列表。 | [] | 否 |
accesslog.fields.queryParameters.defaultMode | 查询参数的默认模式（keep 或 drop）。 | keep | 否 |
OpenTelemetry
Traefik 支持 OpenTelemetry 访问日志记录。
experimental:
otlpLogs: true
accesslog:
# 在 OTEL 日志记录旁边保留 Stdio 日志
dualOutput: true
otlp:
http:
endpoint: https://collector:4318/v1/logs
headers:
Authorization: Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL访问日志的 OTLP 配置选项与日志相同（service name、resource attributes、http/grpc endpoint、TLS 等）。
日志格式
Traefik CLF 格式字段
Traefik 提供的默认格式：
<remote_IP_address> - <client_user_name_if_available> [<timestamp>]
"<request_method> <request_path> <request_protocol>" <HTTP_status> <content-length>
"<request_referrer>" "<request_user_agent>" <number_of_requests_received_since_Traefik_started>
"<Traefik_router_name>" "<Traefik_server_URL>" <request_duration_in_ms>ms通用 CLF 格式字段
<remote_IP_address> - <client_user_name_if_available> [<timestamp>]
"<request_method> <request_path> <request_protocol>" <HTTP_status> <content-length>
"<request_referrer>" "<request_user_agent>"JSON 格式字段
JSON 格式下可用的字段包括：StartUTC、StartLocal、Duration、RouterName、ServiceName、ServiceURL、ServiceAddr、ClientAddr、ClientHost、ClientPort、ClientUsername、RequestAddr、RequestHost、RequestPort、RequestMethod、RequestPath、RequestProtocol、RequestScheme、RequestLine、RequestContentSize、OriginDuration、OriginContentSize、OriginStatus、OriginStatusLine、DownstreamStatus、DownstreamStatusLine、DownstreamContentSize、RequestCount、GzipRatio、Overhead、RetryAttempts、TLSVersion、TLSCipher、TLSClientSubject、KubernetesIngressNamespace、KubernetesIngressName、KubernetesServiceName、KubernetesServicePort。
日志轮转
收到 USR1 信号时，Traefik 关闭并重新打开其日志文件（假设已配置）。这允许由外部程序（如 logrotate）轮转和处理日志。
警告
由于 Windows 缺少 USR 信号，这在 Windows 上不起作用。
时区
默认情况下，Traefik 以 UTC 时间记录每条日志行的时间戳。
可以通过在环境中进行以下配置来配置 Traefik 使用特定时区：
向
/etc/localtime或/usr/share/zoneinfo提供时区数据（根据你的发行版），或设置 TZ 环境变量为所需的时区。通过删除名为
StartUTC的字段来指定StartLocal字段（在默认的通用日志格式 (CLF) 和 JSON 中都可用）：accesslog.fields.names.StartUTC=drop。
使用 Docker Compose 的示例：
services:
traefik:
image: traefik:v3.7
environment:
- TZ=US/Alaska
command:
- --accesslog.fields.names.StartUTC=drop
- --providers.docker
ports:
- 80:80
volumes:
- /var/run/docker.sock:/var/run/docker.sock在生产环境使用 Traefik OSS？
如果你在工作中使用 Traefik，可以考虑为其添加企业级 API 网关能力或获取 Traefik OSS 的商业支持。