Access Logs

Who Calls Whom?

By default, logs are written to stdout, in text format.

Configuration

To enable the access logs:

File (YAML)

  1. accessLog: {}

File (TOML)

  1. [accessLog]

CLI

  1. --accesslog=true

filePath

By default access logs are written to the standard output. To write the logs into a log file, use the filePath option.

File (YAML)

  1. accessLog:
  2. filePath: "/path/to/access.log"

File (TOML)

  1. [accessLog]
  2. filePath = "/path/to/access.log"

CLI

  1. --accesslog.filepath=/path/to/access.log

format

By default, logs are written using the Common Log Format (CLF). To write logs in JSON, use json in the format option. If the given format is unsupported, the default (CLF) is used instead.

Common Log Format

  1. <remote_IP_address> - <client_user_name_if_available> [<timestamp>] "<request_method> <request_path> <request_protocol>" <origin_server_HTTP_status> <origin_server_content_size> "<request_referrer>" "<request_user_agent>" <number_of_requests_received_since_Traefik_started> "<Traefik_router_name>" "<Traefik_server_URL>" <request_duration_in_ms>ms

bufferingSize

To write the logs in an asynchronous fashion, specify a bufferingSize option. This option represents the number of log lines Traefik will keep in memory before writing them to the selected output. In some cases, this option can greatly help performances.

File (YAML)

  1. # Configuring a buffer of 100 lines
  2. accessLog:
  3. filePath: "/path/to/access.log"
  4. bufferingSize: 100

File (TOML)

  1. # Configuring a buffer of 100 lines
  2. [accessLog]
  3. filePath = "/path/to/access.log"
  4. bufferingSize = 100

CLI

  1. # Configuring a buffer of 100 lines
  2. --accesslog.filepath=/path/to/access.log
  3. --accesslog.bufferingsize=100

Filtering

To filter logs, you can specify a set of filters which are logically “OR-connected”. Thus, specifying multiple filters will keep more access logs than specifying only one.

The available filters are:

  • statusCodes, to limit the access logs to requests with a status codes in the specified range
  • retryAttempts, to keep the access logs when at least one retry has happened
  • minDuration, to keep access logs when requests take longer than the specified duration (provided in seconds or as a valid duration format, see time.ParseDuration)

File (YAML)

  1. # Configuring Multiple Filters
  2. accessLog:
  3. filePath: "/path/to/access.log"
  4. format: json
  5. filters:
  6. statusCodes:
  7. - "200"
  8. - "300-302"
  9. retryAttempts: true
  10. minDuration: "10ms"

File (TOML)

  1. # Configuring Multiple Filters
  2. [accessLog]
  3. filePath = "/path/to/access.log"
  4. format = "json"
  5. [accessLog.filters]
  6. statusCodes = ["200", "300-302"]
  7. retryAttempts = true
  8. minDuration = "10ms"

CLI

  1. # Configuring Multiple Filters
  2. --accesslog.filepath=/path/to/access.log
  3. --accesslog.format=json
  4. --accesslog.filters.statuscodes=200,300-302
  5. --accesslog.filters.retryattempts
  6. --accesslog.filters.minduration=10ms

Limiting the Fields/Including Headers

You can decide to limit the logged fields/headers to a given list with the fields.names and fields.headers options.

Each field can be set to:

  • keep to keep the value
  • drop to drop the value
  • redact to replace the value with “redacted”

The defaultMode for fields.names is keep.

The defaultMode for fields.headers is drop.

File (YAML)

  1. # Limiting the Logs to Specific Fields
  2. accessLog:
  3. filePath: "/path/to/access.log"
  4. format: json
  5. fields:
  6. defaultMode: keep
  7. names:
  8. ClientUsername: drop
  9. headers:
  10. defaultMode: keep
  11. names:
  12. User-Agent: redact
  13. Authorization: drop
  14. Content-Type: keep

File (TOML)

  1. # Limiting the Logs to Specific Fields
  2. [accessLog]
  3. filePath = "/path/to/access.log"
  4. format = "json"
  5. [accessLog.fields]
  6. defaultMode = "keep"
  7. [accessLog.fields.names]
  8. "ClientUsername" = "drop"
  9. [accessLog.fields.headers]
  10. defaultMode = "keep"
  11. [accessLog.fields.headers.names]
  12. "User-Agent" = "redact"
  13. "Authorization" = "drop"
  14. "Content-Type" = "keep"

CLI

  1. # Limiting the Logs to Specific Fields
  2. --accesslog.filepath=/path/to/access.log
  3. --accesslog.format=json
  4. --accesslog.fields.defaultmode=keep
  5. --accesslog.fields.names.ClientUsername=drop
  6. --accesslog.fields.headers.defaultmode=keep
  7. --accesslog.fields.headers.names.User-Agent=redact
  8. --accesslog.fields.headers.names.Authorization=drop
  9. --accesslog.fields.headers.names.Content-Type=keep

Available Fields

FieldDescription
StartUTCThe time at which request processing started.
StartLocalThe local time at which request processing started.
DurationThe total time taken (in nanoseconds) by processing the response, including the origin server’s time but not the log writing time.
RouterNameThe name of the Traefik router.
ServiceNameThe name of the Traefik backend.
ServiceURLThe URL of the Traefik backend.
ServiceAddrThe IP:port of the Traefik backend (extracted from ServiceURL)
ClientAddrThe remote address in its original form (usually IP:port).
ClientHostThe remote IP address from which the client request was received.
ClientPortThe remote TCP port from which the client request was received.
ClientUsernameThe username provided in the URL, if present.
RequestAddrThe HTTP Host header (usually IP:port). This is treated as not a header by the Go API.
RequestHostThe HTTP Host server name (not including port).
RequestPortThe TCP port from the HTTP Host.
RequestMethodThe HTTP method.
RequestPathThe HTTP request URI, not including the scheme, host or port.
RequestProtocolThe version of HTTP requested.
RequestSchemeThe HTTP scheme requested http or https.
RequestLineRequestMethod + RequestPath + RequestProtocol
RequestContentSizeThe number of bytes in the request entity (a.k.a. body) sent by the client.
OriginDurationThe time taken (in nanoseconds) by the origin server (‘upstream’) to return its response.
OriginContentSizeThe content length specified by the origin server, or 0 if unspecified.
OriginStatusThe HTTP status code returned by the origin server. If the request was handled by this Traefik instance (e.g. with a redirect), then this value will be absent.
OriginStatusLineOriginStatus + Status code explanation
DownstreamStatusThe HTTP status code returned to the client.
DownstreamStatusLineDownstreamStatus + Status code explanation
DownstreamContentSizeThe number of bytes in the response entity returned to the client. This is in addition to the “Content-Length” header, which may be present in the origin response.
RequestCountThe number of requests received since the Traefik instance started.
GzipRatioThe response body compression ratio achieved.
OverheadThe processing time overhead (in nanoseconds) caused by Traefik.
RetryAttemptsThe amount of attempts the request was retried.
TLSVersionThe TLS version used by the connection (e.g. 1.2) (if connection is TLS).
TLSCipherThe TLS cipher used by the connection (e.g. TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA) (if connection is TLS)

Log Rotation

Traefik will close and reopen its log files, assuming they’re configured, on receipt of a USR1 signal. This allows the logs to be rotated and processed by an external program, such as logrotate.

Warning

This does not work on Windows due to the lack of USR signals.

Time Zones

Traefik will timestamp each log line in UTC time by default.

It is possible to configure the Traefik to timestamp in a specific timezone by ensuring the following configuration has been made in your environment:

  1. Provide time zone data to /etc/localtime or /usr/share/zoneinfo (based on your distribution) or set the environment variable TZ to the desired timezone
  2. Specify the field StartLocal by dropping the field named StartUTC (available on the default Common Log Format (CLF) as well as JSON)

Example utilizing Docker Compose:

  1. version: "3.7"
  2. services:
  3. traefik:
  4. image: traefik:v2.8
  5. environment:
  6. - TZ=US/Alaska
  7. command:
  8. - --accesslog.fields.names.StartUTC=drop
  9. - --providers.docker
  10. ports:
  11. - 80:80
  12. volumes:
  13. - /var/run/docker.sock:/var/run/docker.sock