Logs & AccessLogs

日志¶

日志记录 Traefik 自身发生的一切（启动、配置、事件、关闭等）。

配置示例¶

文件 (YAML)

log:
  filePath: "/path/to/log-file.log"
  format: json
  level: INFO

文件 (TOML)

[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

配置选项¶

以下部分介绍如何使用静态配置来配置 Traefik 日志。

字段	说明	默认值	必填
`log.filePath`	默认将日志写入标准输出。可以通过 `filePath` 选项配置文件路径。指定 `filePath` 后，Traefik 只将日志写入该文件（不写入标准输出）。	-	否
`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`	根据文件名中编码的时间戳，保留旧日志文件的最长天数。一天定义为 24 小时，由于夏令时、闰秒等原因，可能并不完全对应日历日。默认不按存放时间删除文件。	0	否
`log.maxBackups`	保留的旧日志文件的最大数量。默认保留所有旧日志文件。	0	否
`log.compress`	轮转后以 gzip 压缩日志文件。启用日志轮转时始终启用压缩；此字段不生效。	false	否

OpenTelemetry¶

Traefik 支持使用 OpenTelemetry 记录日志。若要启用 OpenTelemetry，需要在静态配置中设置以下内容：

文件 (YAML)

experimental:
  otlpLogs: true

文件 (TOML)

[experimental]
  otlpLogs = true

CLI

--experimental.otlpLogs=true

警告

这是一个实验性功能。

Stdio 日志仍然可用

启用 OTLP 日志后，标准输出（stdio）日志仍然可用，并会继续与 OTLP 导出同时写入。

配置示例¶

文件 (YAML)

experimental:
  otlpLogs: true

log:
  otlp:
    http:
      endpoint: https://collector:4318/v1/logs
      headers:
        Authorization: Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL

文件 (TOML)

[experimental]
  otlpLogs = true

[log.otlp]
  http.endpoint = "https://collector:4318/v1/logs"
  http.headers.Authorization = "Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL"

CLI

--experimental.otlpLogs=true
--log.otlp.http.endpoint=https://collector:4318/v1/logs
--log.otlp.http.headers.Authorization=Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL

配置选项¶

字段	说明	默认值	必填
`log.otlp.serviceName`	所选后端使用的服务名称。	"traefik"	否
`log.otlp.resourceAttributes`	定义发送到收集器的附加资源属性。详情参见 resourceAttributes。	[]	否
`log.otlp.http`	指示导出器通过 HTTP 将日志发送到 OpenTelemetry Collector。		否
`log.otlp.http.endpoint`	OpenTelemetry Collector 的端点。（格式为 `<scheme>://<host>:<port><path>`）	`https://localhost:4318`	否
`log.otlp.http.headers`	导出器随日志发送到 OpenTelemetry Collector 的附加请求头。	[ ]	否
`log.otlp.http.tls`	定义导出器将日志发送到 OpenTelemetry Collector 时使用的客户端 TLS 配置。		否
`log.otlp.http.tls.ca`	用于安全连接到 OpenTelemetry Collector 的证书颁发机构文件路径，默认为系统证书包。		否
`log.otlp.http.tls.cert`	OpenTelemetry Collector 使用的证书路径。		否
`log.otlp.http.tls.key`	OpenTelemetry Collector 使用的密钥路径。		否
`log.otlp.http.tls.insecureSkipVerify`	指示 OpenTelemetry Collector 接受服务器提供的任何证书，无论证书中的主机名为何。	false	否
`log.otlp.grpc`	指示导出器通过 gRPC 将日志发送到 OpenTelemetry Collector。		否
`log.otlp.grpc.endpoint`	OpenTelemetry Collector 的端点。（格式为 `<host>:<port>`）	`localhost:4317`	否
`log.otlp.grpc.headers`	导出器随日志发送到 OpenTelemetry Collector 的附加请求头。	[ ]	否
`log.otlp.grpc.insecure`	指示导出器通过不安全的协议将日志发送到 OpenTelemetry Collector。	false	否
`log.otlp.grpc.tls`	定义导出器将日志发送到 OpenTelemetry Collector 时使用的客户端 TLS 配置。		否
`log.otlp.grpc.tls.ca`	用于安全连接到 OpenTelemetry Collector 的证书颁发机构文件路径，默认为系统证书包。		否
`log.otlp.grpc.tls.cert`	OpenTelemetry Collector 使用的证书路径。		否
`log.otlp.grpc.tls.key`	OpenTelemetry Collector 使用的密钥路径。		否
`log.otlp.grpc.tls.insecureSkipVerify`	指示 OpenTelemetry Collector 接受服务器提供的任何证书，无论证书中的主机名为何。	false	否

resourceAttributes¶

resourceAttributes 选项允许设置随链路追踪发送的资源属性。 Traefik 也支持通过 OTEL_RESOURCE_ATTRIBUTES 环境变量设置资源属性。

Kubernetes 资源属性检测

此外，在 Kubernetes 集群中运行时，Traefik 会自动发现以下 Kubernetes 资源属性：

k8s.namespace.name
k8s.pod.uid
k8s.pod.name

请注意，自动检测可能失败，例如 Traefik Pod 运行在主机网络模式时。此时，应通过该选项或环境变量提供这些属性。

访问日志¶

访问日志记录 Traefik 处理的请求中发生的一切。

OTLP 导出时默认不同时启用 Stdio 日志

若希望同时使用 Stdio 访问日志，请使用 accessLog.dualOutput 选项。

配置示例¶

文件 (YAML)

accessLog:
  # JSON format
  format: json
  # Filter on status codes, retry attempts and minimal duration
  filters:
    statusCodes:
      - "200"
      - "300-302"
    retryAttempts: true
    minDuration: "10ms"
  fields:
    # Keep all the fields by default
    defaultMode: keep
    names:
      # Drop the Field ClientUserName
      ClientUsername: drop
    headers:
      # Keep all the headers by default
      defaultMode: keep
      names:
        # Redact the User-Agent header value
        User-Agent: redact
        # Drop the Authorization header value
        Authorization: drop
    queryParameters:
      # Drop all query parameters
      defaultMode: drop

文件 (TOML)

[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"

CLI

--accesslog=true
--accesslog.dualoutput=true
--accesslog.format=json
--accesslog.filters.statuscodes=200,300-302
--accesslog.filters.retryattempts
--accesslog.filters.minduration=10ms
--accesslog.fields.defaultmode=keep
--accesslog.fields.names.ClientUsername=drop
--accesslog.fields.headers.defaultmode=keep
--accesslog.fields.headers.names.User-Agent=redact
--accesslog.fields.headers.names.Authorization=drop
--accesslog.fields.queryparameters.defaultmode=drop

配置选项¶

以下部分介绍如何使用静态配置来配置 Traefik 访问日志。

字段	说明	默认值	必填
`accesslog.filePath`	默认将访问日志写入标准输出。可以通过 `filePath` 选项配置文件路径。		否
`accesslog.dualOutput`	即使配置了 OTLP，也强制使用 Stdio 日志。出于性能考虑，启用 OTLP 时默认禁用 Stdio 日志。	false	否
`accesslog.format`	默认使用 Traefik 通用日志格式（CLF）写入日志。可用格式：`common`（Traefik 扩展 CLF）、`genericCLF`（与分析器兼容的标准 CLF）或 `json`。给定格式不受支持时，使用默认值（`common`）。	"common"	否
`accesslog.bufferingSize`	若要异步处理访问日志，请将 `bufferingSize` 设为大于零的值。此值指定内存队列的容量，单位为日志行数。 Traefik 会持续写入队列中的日志行，不会等待队列填满。更大的队列可降低访问日志在高负载下阻塞请求的概率。	0	否
`accesslog.addInternals`	为内部资源（例如 `ping@internal`）启用访问日志。	false	否
`accesslog.filters.statusCodes`	仅记录状态码在指定范围内的请求的访问日志。	[ ]	否
`accesslog.filters.retryAttempts`	保留至少发生过一次重试的访问日志。	false	否
`accesslog.filters.minDuration`	保留请求耗时超过指定时长的访问日志（以秒或有效时长格式提供，参见 time.ParseDuration）。	0	否
`accesslog.fields.defaultMode`	默认应用于访问日志字段的模式（`keep` 或 `drop`）。	keep	否
`accesslog.fields.names`	设置访问日志中显示的字段列表（格式为 `name:mode`）。可用字段列表参见此处。	[ ]	否
`accesslog.fields.headers.defaultMode`	默认应用于访问日志请求头的模式（`keep`、`redact` 或 `drop`）。	drop	否
`accesslog.fields.headers.names`	设置访问日志中显示的请求头列表（格式为 `name:mode`）。	[ ]	否
`accesslog.fields.queryParameters.defaultMode`	默认应用于访问日志查询参数的模式（`keep` 或 `drop`）	keep	否

OpenTelemetry¶

Traefik 支持使用 OpenTelemetry 记录访问日志。若要启用 OpenTelemetry，需要在静态配置中设置以下内容：

文件 (YAML)

experimental:
  otlpLogs: true

文件 (TOML)

[experimental]
  otlpLogs = true

CLI

--experimental.otlpLogs=true

警告

这是一个实验性功能。

配置示例¶

文件 (YAML)

experimental:
  otlpLogs: true

accesslog:
  # Keep Stdio logs alongside OTEL logging
  dualOutput: true
  otlp:
    http:
      endpoint: https://collector:4318/v1/logs
      headers:
        Authorization: Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL

文件 (TOML)

[experimental]
  otlpLogs = true

[accessLog]
  dualOutput = true

[accesslog.otlp]
  http.endpoint = "https://collector:4318/v1/logs"
  http.headers.Authorization = "Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL"

CLI

--experimental.otlpLogs=true
--accesslog.otlp.http.endpoint=https://collector:4318/v1/logs
--accesslog.otlp.http.headers.Authorization=Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL

配置选项¶

字段	说明	默认值	必填
`accesslog.otlp.serviceName`	定义服务名称资源属性。	"traefik"	否
`accesslog.otlp.resourceAttributes`	定义发送到收集器的附加资源属性。详情参见 resourceAttributes。	[]	否
`accesslog.otlp.http`	指示导出器通过 HTTP 将访问日志发送到 OpenTelemetry Collector。		否
`accesslog.otlp.http.endpoint`	OpenTelemetry Collector 的端点。（格式为 `<scheme>://<host>:<port><path>`）	`https://localhost:4318`	否
`accesslog.otlp.http.headers`	导出器随访问日志发送到 OpenTelemetry Collector 的附加请求头。	[ ]	否
`accesslog.otlp.http.tls`	定义导出器将访问日志发送到 OpenTelemetry Collector 时使用的客户端 TLS 配置。		否
`accesslog.otlp.http.tls.ca`	用于安全连接到 OpenTelemetry Collector 的证书颁发机构文件路径，默认为系统证书包。		否
`accesslog.otlp.http.tls.cert`	OpenTelemetry Collector 使用的证书路径。		否
`accesslog.otlp.http.tls.key`	OpenTelemetry Collector 使用的密钥路径。		否
`accesslog.otlp.http.tls.insecureSkipVerify`	指示 OpenTelemetry Collector 接受服务器提供的任何证书，无论证书中的主机名为何。	false	否
`accesslog.otlp.grpc`	指示导出器通过 gRPC 将访问日志发送到 OpenTelemetry Collector。		否
`accesslog.otlp.grpc.endpoint`	OpenTelemetry Collector 的端点。（格式为 `<host>:<port>`）	`localhost:4317`	否
`accesslog.otlp.grpc.headers`	导出器随访问日志发送到 OpenTelemetry Collector 的附加请求头。	[ ]	否
`accesslog.otlp.grpc.insecure`	指示导出器通过不安全的协议将访问日志发送到 OpenTelemetry Collector。	false	否
`accesslog.otlp.grpc.tls`	定义导出器将访问日志发送到 OpenTelemetry Collector 时使用的客户端 TLS 配置。		否
`accesslog.otlp.grpc.tls.ca`	用于安全连接到 OpenTelemetry Collector 的证书颁发机构文件路径，默认为系统证书包。		否
`accesslog.otlp.grpc.tls.cert`	OpenTelemetry Collector 使用的证书路径。		否
`accesslog.otlp.grpc.tls.key`	OpenTelemetry Collector 使用的密钥路径。		否
`accesslog.otlp.grpc.tls.insecureSkipVerify`	指示 OpenTelemetry Collector 接受服务器提供的任何证书，无论证书中的主机名为何。	false	否

resourceAttributes¶

resourceAttributes 选项允许设置随链路追踪发送的资源属性。 Traefik 也支持通过 OTEL_RESOURCE_ATTRIBUTES 环境变量设置资源属性。

Kubernetes 资源属性检测

此外，在 Kubernetes 集群中运行时，Traefik 会自动发现以下 Kubernetes 资源属性：

k8s.namespace.name
k8s.pod.uid
k8s.pod.name

请注意，自动检测可能失败，例如 Traefik Pod 运行在主机网络模式时。此时，应通过该选项或环境变量提供这些属性。

Traefik CLF 格式字段¶

这是 Traefik 提供的默认格式。以下是 Traefik 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>" <number_of_requests_received_since_Traefik_started>
"<Traefik_router_name>" "<Traefik_server_URL>" <request_duration_in_ms>ms

<HTTP_status> 是下游状态

在两种 CLF 格式中，<HTTP_status> 都是 DownstreamStatus，即发送给客户端的状态。后端状态（OriginStatus）仅在 json 格式中可用。

通用 CLF 格式字段¶

以下是通用 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 格式字段¶

字段	说明
`StartUTC`	请求处理开始的时间。
`StartLocal`	请求处理开始的本地时间。
`Duration`	处理响应花费的总时间（纳秒），包括源服务器的时间，但不包括日志写入时间。
`RouterName`	Traefik 路由器的名称。
`ServiceName`	Traefik 后端的名称。
`ServiceURL`	Traefik 后端的 URL。
`ServiceAddr`	Traefik 后端的 IP:port（从 `ServiceURL` 提取）。
`ClientAddr`	原始形式的远程地址（通常为 IP:port）。
`ClientHost`	接收客户端请求的来源远程 IP 地址。
`ClientPort`	接收客户端请求的来源远程 TCP 端口。
`ClientUsername`	URL 中提供的用户名（如果存在）。
`RequestAddr`	HTTP Host 请求头（通常为 IP:port）。Go API 不将其视为请求头。
`RequestHost`	HTTP Host 中的服务器名称（不含端口）。
`RequestPort`	HTTP Host 中的 TCP 端口。
`RequestMethod`	HTTP 方法。
`RequestPath`	HTTP 请求 URI，不含协议、主机或端口。
`RequestProtocol`	请求的 HTTP 版本。
`RequestScheme`	请求的 HTTP 协议：`http` 或 `https`。
`RequestLine`	`RequestMethod`、`RequestPath` 和 `RequestProtocol` 的组合。
`RequestContentSize`	客户端发送的请求实体（即请求体）的字节数。
`OriginDuration`	源服务器（“上游”）返回响应所花费的时间（纳秒）。
`OriginContentSize`	源服务器指定的内容长度，未指定时为 0。
`OriginStatus`	将请求代理到后端产生的 HTTP 状态码：可能是后端返回的状态码，也可能是无法访问服务器时生成的状态码（`502`、`504` 等）。参见源站状态与下游状态。
`OriginStatusLine`	`OriginStatus` 加状态码说明
`DownstreamStatus`	中间件链执行后，发送给客户端的 HTTP 状态码。参见源站状态与下游状态。
`DownstreamStatusLine`	`DownstreamStatus` 及状态码说明。
`DownstreamContentSize`	返回给客户端的响应实体字节数。这是除源站响应中可能存在的 “Content-Length” 响应头之外提供的信息。
`RequestCount`	Traefik 实例启动以来接收的请求数量。
`GzipRatio`	响应体实际达到的压缩比。
`Overhead`	Traefik 产生的处理时间开销（纳秒）。
`RetryAttempts`	请求重试的次数。
`TLSVersion`	连接使用的 TLS 版本（例如 `1.2`）（如果连接使用 TLS）。
`TLSCipher`	连接使用的 TLS 密码套件（例如 `TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA`）（如果连接使用 TLS）。
`TLSClientSubject`	TLS 客户端证书主体的字符串表示（例如 `CN=username,O=organization`）。
`KubernetesIngressNamespace`	路由器处理的 Kubernetes Ingress 资源的命名空间。路由器来自 Kubernetes Ingress 或 Kubernetes Ingress Nginx 提供者时输出。
`KubernetesIngressName`	路由器处理的 Kubernetes Ingress 资源的名称。路由器来自 Kubernetes Ingress 或 Kubernetes Ingress Nginx 提供者时输出。
`KubernetesIngressRouteNamespace`	路由器处理的 Kubernetes IngressRoute（CRD）的命名空间。路由器来自 Kubernetes CRD 提供者时输出。
`KubernetesIngressRouteName`	路由器处理的 Kubernetes IngressRoute（CRD）的名称。路由器来自 Kubernetes CRD 提供者时输出。
`KubernetesServiceNamespace`	处理请求的 Kubernetes Service 的命名空间。适用于所有 Kubernetes 提供者。按请求从负载均衡策略实际选择的后端记录，因此即使存在多服务路由、TraefikService 加权/镜像或跨命名空间引用，也能反映真实目标。
`KubernetesServiceName`	处理请求的 Kubernetes Service 的名称。每请求语义参见 `KubernetesServiceNamespace`。
`KubernetesServicePort`	处理请求的 Kubernetes Service 的端口。每请求语义参见 `KubernetesServiceNamespace`。

日志轮转¶

Traefik 不会轮转访问日志文件。收到 USR1 信号时，Traefik 会关闭并重新打开访问日志文件。这样外部程序（例如 logrotate）就能轮转访问日志文件。

USR1 信号对 Traefik 日志文件无效。 Traefik 使用 log.maxSize、log.maxAge 和 log.maxBackups 选项轮转 Traefik 日志文件。

警告

由于缺少 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，可以考虑为 Traefik OSS 增加企业级 API 网关能力或商业支持。

为 Traefik OSS 增加 API 网关能力快捷且平滑，无需推倒重来，现有配置也会完整保留。请通过这个简短视频了解实际效果。