Logs & Access Logs

日志¶

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

配置示例¶

要启用和配置 Traefik Proxy 日志，可以使用静态配置文件；如果使用 Helm chart，也可以通过 Helm values 配置。

结构化 (YAML)

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

结构化 (TOML)

[log]
  filePath = "/path/to/log-file.log"
  format = "json"
  level = "INFO"

Helm Chart 值

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

访问日志¶

访问日志记录 Traefik 所处理请求的相关信息。

配置示例¶

要启用和配置 Traefik Proxy 访问日志，可以使用静态配置文件；如果使用 Helm chart，也可以通过 Helm values 配置。

以下示例启用 JSON 格式的访问日志，通过过滤仅保留特定状态码，并自定义保留或丢弃的字段。

结构化 (YAML)

accessLog:
  format: json
  filters:
    statusCodes:
      - "200"
      - "400-404"
      - "500-503"
  fields:
    names:
      ClientUsername: drop
    headers:
      defaultMode: keep
      names:
        User-Agent: redact
        Content-Type: keep

结构化 (TOML)

[accessLog]
  format = "json"
  [accessLog.filters]
    statusCodes = ["200", "400-404", "500-503"]
  [accessLog.fields]
    [accessLog.fields.names]
      ClientUsername = "drop"
    [accessLog.fields.headers]
      defaultMode = "keep"
      [accessLog.fields.headers.names]
        "User-Agent" = "redact"
        "Content-Type" = "keep"

Helm Chart 值

# values.yaml
accessLog:
  enabled: true
  format: json
  filters:
    statusCodes:
      - "200"
      - "400-404"
      - "500-503"
  fields:
    names:
      ClientUsername: drop
    headers:
      defaultMode: keep
      names:
        User-Agent: redact
        Content-Type: keep

按路由器配置访问日志¶

您可以为特定路由器启用或禁用访问日志。这适合在全局保持启用的同时，关闭产生大量日志的路由的日志记录。

下面是在特定路由器上禁用访问日志的示例：

结构化 (YAML)

http:
  routers:
    my-router:
      rule: "Host(`example.com`)"
      service: my-service
      observability:
        accessLogs: false

结构化 (TOML)

[http.routers.my-router.observability]
  accessLogs = false

Kubernetes

# ingressroute.yaml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: my-router
spec:
  routes:
    - kind: Rule
      match: Host(`example.com`)
      services:
        - name: my-service
          port: 80
      observability:
        accessLogs: false

标签

labels:
  - "traefik.http.routers.my-router.observability.accesslogs=false"

标签

{
  // ...
  "Tags": [
    "traefik.http.routers.my-router.observability.accesslogs=false"
  ]
}

如果路由器未定义 observability 选项，就会继承入口点的可观测性配置或全局配置。

日志格式¶

Traefik Proxy 支持以下日志格式：

common - Traefik 扩展的 CLF 格式（默认）
genericCLF - 与标准日志分析器兼容的通用 CLF 格式
json - 适用于结构化日志的 JSON 格式

源站状态与下游状态¶

访问日志记录两个状态码，其命名以 Traefik 为参照：

Client <---- DownstreamStatus ---- Traefik <---- OriginStatus ---- Backend

OriginStatus 是将请求代理到后端的结果。它可以是后端返回的状态；如果无法访问后端或后端未正确响应，则为计算得到的状态码（502、504 等）。
DownstreamStatus 是中间件链执行完成后，Traefik 返回给客户端的状态。

请求未经改动地代理时，两者相等。如果两者均已设置但值不同，说明中间件改写了响应。如果 OriginStatus 为空（记录为 0），说明请求从未被代理到后端：响应来自路由处理（没有匹配的路由器）或中间件（身份验证、速率限制、重定向）。

提示

这两个字段仅在 json 格式中可用。 common、genericCLF 格式以及 statusCodes 过滤器使用 DownstreamStatus 的值。

访问日志过滤器¶

您可以配置 Traefik Proxy，使其仅记录满足特定条件的请求访问日志。这有助于减少日志量并聚焦特定事件。

可用的过滤器包括：

状态码：仅保留具有特定 HTTP 状态码或状态码范围（例如 200、400-404）的请求日志。
重试次数：仅在请求发生重试时保留日志。
最短持续时间：仅保留处理时长超过指定时间的请求日志。

自定义日志字段¶

使用 json 格式时，可以自定义访问日志中包含的字段。

请求字段：可以对任意标准请求字段选择 keep、drop 或 redact。ClientHost、RequestMethod、Duration 等可用字段的完整列表，请参阅参考文档。
请求头：还可以指定日志应包含哪些请求头，以及其值应该被 kept、dropped 还是 redacted。
请求查询参数：可以对请求的查询参数选择 keep 或 drop。

提示

详细配置选项请参阅参考文档。