Skip to content
GitHub

Logs & Access Logs

Logs

Logs concern everything that happens to Traefik itself (startup, configuration, events, shutdown, and so on).

Configuration Example

To enable and configure logs in Traefik Proxy, you can use the static configuration file or Helm values if you are using the Helm chart.

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

Access Logs

Access logs concern everything that happens to the requests handled by Traefik.

Configuration Example

To enable and configure access logs in Traefik Proxy, you can use the static configuration file or Helm values if you are using the Helm chart.

The following example enables access logs in JSON format, filters them to only include specific status codes, and customizes the fields that are kept or dropped.

accessLog:
  format: json
  filters:
    statusCodes:
      - "200"
      - "400-404"
      - "500-503"
  fields:
    names:
      ClientUsername: drop
    headers:
      defaultMode: keep
      names:
        User-Agent: redact
        Content-Type: keep
[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"
# 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

Per-Router Access Logs

You can enable or disable access logs for a specific router. This is useful for turning off logging for noisy routes while keeping it on globally.

Here's an example of disabling access logs on a specific router:

http:
  routers:
    my-router:
      rule: "Host(`example.com`)"
      service: my-service
      observability:
        accessLogs: false
[http.routers.my-router.observability]
  accessLogs = false
# 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"
  ]
}

When the observability options are not defined on a router, it inherits the behavior from the entrypoint's observability configuration, or the global one.

Log Formats

Traefik Proxy supports the following log formats:

  • common - Traefik's extended CLF format (default)
  • genericCLF - Generic CLF format compatible with standard log analyzers
  • json - JSON format for structured logging

Origin vs. Downstream Status

Access logs report two status codes, named relative to Traefik:

Client <---- DownstreamStatus ---- Traefik <---- OriginStatus ---- Backend
  • OriginStatus is the outcome of proxying the request to a backend. It is either the status returned by that backend or the computed status code, when the backend could not be reached or did not answer properly (502, 504, ...).
  • DownstreamStatus is what Traefik returned to the client, after the middleware chain has run.

Both are equal when the request is proxied unchanged. When both are set but differ, a middleware rewrote the response. When OriginStatus is empty (logged as 0), the request was never proxied to a backend: the response comes from routing (no matching router) or from a middleware (authentication, rate limiting, redirection).

Info

Both fields are only available with the json format. The common and genericCLF formats, and the statusCodes filter, use the DownstreamStatus value.

Access Log Filters

You can configure Traefik Proxy to only record access logs for requests that match certain criteria. This is useful for reducing the volume of logs and focusing on specific events.

The available filters are:

  • Status Codes: Keep logs only for requests with specific HTTP status codes or ranges (e.g., 200, 400-404).
  • Retry Attempts: Keep logs only when a request retry has occurred.
  • Minimum Duration: Keep logs only for requests that take longer than a specified duration.

Log Fields Customization

When using the json format, you can customize which fields are included in your access logs.

  • Request Fields: You can choose to keep, drop, or redact any of the standard request fields. A complete list of available fields like ClientHost, RequestMethod, and Duration can be found in the reference documentation.
  • Request Headers: You can also specify which request headers should be included in the logs, and whether their values should be kept, dropped, or redacted.
  • Request Query Parameters: You can choose to keep or drop the query parameters for a request.

Info

For detailed configuration options, refer to the reference documentation.