Skip to content

Logs & AccessLogs

Logs

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

Configuration Example

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
--log.format=json
--log.level=INFO

Configuration Options

The section below describe how to configure Traefik logs using the static configuration.

Field Description Default Required
log.filePath By default, the logs are written to the standard output.
You can configure a file path instead using the filePath option.
- No
log.format Log format (commonor json).
The fields displayed with the format common cannot be customized.
"common" No
log.level Log level (TRACE, DEBUG, INFO, WARN, ERROR, FATAL, and PANIC) ERROR No
log.noColor When using the format common, disables the colorized output. false No
log.maxSize Maximum size in megabytes of the log file before it gets rotated. 100MB No
log.maxAge Maximum number of days to retain old log files based on the timestamp encoded in their filename.
A day is defined as 24 hours and may not exactly correspond to calendar days due to daylight savings, leap seconds, etc.
By default files are not removed based on their age.
0 No
log.maxBackups Maximum number of old log files to retain.
The default is to retain all old log files.
0 No
log.compress Compress log files in gzip after rotation. false No

AccessLogs

Configuration Example

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

Configuration Options

The section below describes how to configure Traefik access logs using the static configuration.

Field Description Default Required
accesslog.filePath By default, the access logs are written to the standard output.
You can configure a file path instead using the filePath option.
No
accesslog.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.
More information about CLF fields here.
"common" No
accesslog.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.
0 No
accesslog.addInternals Enables access logs for internal resources (e.g.: ping@internal). false No
accesslog.filters.statusCodes Limit the access logs to requests with a status codes in the specified range. false No
accesslog.filters.retryAttempts Keep the access logs when at least one retry has happened. false No
accesslog.filters.minDuration Keep access logs when requests take longer than the specified duration (provided in seconds or as a valid duration format, see time.ParseDuration). 0 No
accesslog.fields.defaultMode Mode to apply by default to the access logs fields (keep, redact or drop). keep No
accesslog.fields.names Set the fields list to display in the access logs (format name:mode).
Available fields list here.
- No
accesslog.headers.defaultMode Mode to apply by default to the access logs headers (keep, redact or drop). drop No
accesslog.headers.names Set the headers list to display in the access logs (format name:mode). - No

CLF format fields

Below the fields displayed with the CLF format:

<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

Available Fields

Field Description
StartUTC The time at which request processing started.
StartLocal The local time at which request processing started.
Duration The total time taken (in nanoseconds) by processing the response, including the origin server's time but not the log writing time.
RouterName The name of the Traefik router.
ServiceName The name of the Traefik backend.
ServiceURL The URL of the Traefik backend.
ServiceAddr The IP:port of the Traefik backend (extracted from ServiceURL).
ClientAddr The remote address in its original form (usually IP:port).
ClientHost The remote IP address from which the client request was received.
ClientPort The remote TCP port from which the client request was received.
ClientUsername The username provided in the URL, if present.
RequestAddr The HTTP Host header (usually IP:port). This is treated as not a header by the Go API.
RequestHost The HTTP Host server name (not including port).
RequestPort The TCP port from the HTTP Host.
RequestMethod The HTTP method.
RequestPath The HTTP request URI, not including the scheme, host or port.
RequestProtocol The version of HTTP requested.
RequestScheme The HTTP scheme requested http or https.
RequestLine The RequestMethod, + RequestPath and RequestProtocol.
RequestContentSize The number of bytes in the request entity (a.k.a. body) sent by the client.
OriginDuration The time taken (in nanoseconds) by the origin server ('upstream') to return its response.
OriginContentSize The content length specified by the origin server, or 0 if unspecified.
OriginStatus The 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 (0).
OriginStatusLine OriginStatus + Status code explanation
DownstreamStatus The HTTP status code returned to the client.
DownstreamStatusLine The DownstreamStatus and status code explanation.
DownstreamContentSize The 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.
RequestCount The number of requests received since the Traefik instance started.
GzipRatio The response body compression ratio achieved.
Overhead The processing time overhead (in nanoseconds) caused by Traefik.
RetryAttempts The amount of attempts the request was retried.
TLSVersion The TLS version used by the connection (e.g. 1.2) (if connection is TLS).
TLSCipher The TLS cipher used by the connection (e.g. TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA) (if connection is TLS).
TLSClientSubject The string representation of the TLS client certificate's Subject (e.g. CN=username,O=organization).

Log Rotation

Traefik 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): accesslog.fields.names.StartUTC=drop.

Example utilizing Docker Compose:

version: "3.7"

services:
  traefik:
    image: traefik:v3.2
    environment:
      - TZ=US/Alaska
    command:
      - --accesslog.fields.names.StartUTC=drop
      - --providers.docker
    ports:
      - 80:80
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

Using Traefik OSS in Production?

If you are using Traefik at work, consider adding enterprise-grade API gateway capabilities or commercial support for Traefik OSS.

Adding API Gateway capabilities to Traefik OSS is fast and seamless. There's no rip and replace and all configurations remain intact. See it in action via this short video.