Logs Definition

Reference

TOML

  1. logLevel = "INFO"
  2. [traefikLog]
  3. filePath = "/path/to/traefik.log"
  4. format = "json"
  5. [accessLog]
  6. filePath = "/path/to/access.log"
  7. format = "json"
  8. [accessLog.filters]
  9. statusCodes = ["200", "300-302"]
  10. retryAttempts = true
  11. minDuration = "10ms"
  12. [accessLog.fields]
  13. defaultMode = "keep"
  14. [accessLog.fields.names]
  15. "ClientUsername" = "drop"
  16. # ...
  17. [accessLog.fields.headers]
  18. defaultMode = "keep"
  19. [accessLog.fields.headers.names]
  20. "User-Agent" = "redact"
  21. "Authorization" = "drop"
  22. "Content-Type" = "keep"
  23. # ...

CLI

For more information about the CLI, see the documentation about Traefik command.

  1. --logLevel="DEBUG"
  2. --traefikLog.filePath="/path/to/traefik.log"
  3. --traefikLog.format="json"
  4. --accessLog.filePath="/path/to/access.log"
  5. --accessLog.format="json"
  6. --accessLog.filters.statusCodes="200,300-302"
  7. --accessLog.filters.retryAttempts="true"
  8. --accessLog.filters.minDuration="10ms"
  9. --accessLog.fields.defaultMode="keep"
  10. --accessLog.fields.names="Username=drop Hostname=drop"
  11. --accessLog.fields.headers.defaultMode="keep"
  12. --accessLog.fields.headers.names="User-Agent=redact Authorization=drop Content-Type=keep"

Traefik Logs

By default the Traefik log is written to stdout in text format.

To write the logs into a log file specify the filePath:

  1. [traefikLog]
  2. filePath = "/path/to/traefik.log"

To switch to JSON format instead of standard format (common), specify json as the format:

  1. [traefikLog]
  2. filePath = "/path/to/traefik.log"
  3. format = "json"

Deprecated way (before 1.4):

DEPRECATED

traefikLogsFile is deprecated, use traefikLog instead.

  1. # Traefik logs file
  2. # If not defined, logs to stdout
  3. #
  4. # DEPRECATED - see [traefikLog] lower down
  5. # In case both traefikLogsFile and traefikLog.filePath are specified, the latter will take precedence.
  6. # Optional
  7. #
  8. traefikLogsFile = "log/traefik.log"

To customize the log level:

  1. # Log level
  2. #
  3. # Optional
  4. # Default: "ERROR"
  5. #
  6. # Accepted values, in order of severity: "DEBUG", "INFO", "WARN", "ERROR", "FATAL", "PANIC"
  7. # Messages at and above the selected level will be logged.
  8. #
  9. logLevel = "ERROR"

Access Logs

Access logs are written when the entry [accessLog] is defined (or the command line flag --accesslog). By default it writes to stdout and produces logs in the textual Common Log Format (CLF), extended with additional fields.

To enable access logs using the default settings, add the [accessLog] entry in your traefik.toml configuration file:

  1. [accessLog]

To write the logs into a log file specify the filePath:

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

To switch to JSON format instead of Common Log Format (CLF), specify json as the format:

  1. [accessLog]
  2. filePath = "/path/to/access.log"
  3. format = "json" # Default: "common"

To write the logs in async, specify bufferingSize as the format (must be >0):

  1. [accessLog]
  2. filePath = "/path/to/access.log"
  3. # Buffering Size
  4. #
  5. # Optional
  6. # Default: 0
  7. #
  8. # Number of access log lines to process in a buffered way.
  9. #
  10. bufferingSize = 100

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:

  1. [accessLog]
  2. filePath = "/path/to/access.log"
  3. format = "json" # Default: "common"
  4. [accessLog.filters]
  5. # statusCodes: keep access logs with status codes in the specified range
  6. #
  7. # Optional
  8. # Default: []
  9. #
  10. statusCodes = ["200", "300-302"]
  11. # retryAttempts: keep access logs when at least one retry happened
  12. #
  13. # Optional
  14. # Default: false
  15. #
  16. retryAttempts = true
  17. # minDuration: keep access logs when request took longer than the specified duration
  18. #
  19. # Optional
  20. # Default: 0
  21. #
  22. minDuration = "10ms"

CLF - Common Log Format

By default, Traefik use the CLF (common) as access 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_frontend_name>" "<Traefik_backend_URL>" <request_duration_in_ms>ms

Customize Fields

You can customize the fields written in the access logs. The list of available fields is found below: List of All Available Fields.

Each field has a "mode" which defines if it is written or not in the access log lines. The possible values for the mode are:

  • keep: the field and its value are written on the access log line. This is the default behavior.
  • drop: the field is not written at all on the access log.

To customize the fields, you must:

  • Switch to the JSON format (mandatory)
  • Define the "default mode" for all fields (default is keep)
  • OR Define the fields which does not follow the default mode
  1. [accessLog]
  2. # Access Log Format
  3. #
  4. # Optional
  5. # Default: "common"
  6. #
  7. # Accepted values "common", "json"
  8. #
  9. format = "json"
  10. [accessLog.fields]
  11. # defaultMode
  12. #
  13. # Optional
  14. # Default: "keep"
  15. #
  16. # Accepted values "keep", "drop"
  17. #
  18. defaultMode = "keep"
  19. # Fields map which is used to override fields defaultMode
  20. [accessLog.fields.names]
  21. "ClientUsername" = "drop"
  22. # ...

Customize Headers

Access logs prints the headers of each request, as fields of the access log line. You can customize which and how the headers are printed, likewise the other fields (see "Customize Fields" section).

Each header has a "mode" which defines how it is written in the access log lines. The possible values for the mode are:

  • keep: the header and its value are written on the access log line. This is the default behavior.
  • drop: the header is not written at all on the access log.
  • redacted: the header is written, but its value is redacted to avoid leaking sensitive information.

To customize the headers, you must:

  • Switch to the JSON format (mandatory)
  • Define the "default mode" for all headers (default is keep)
  • OR Define the headers which does not follow the default mode

Important

The headers are written with the prefix request_ in the access log. This prefix must not be included when specifying a header in the TOML configuration.

  • Do: "User-Agent" = "drop"
  • Don't: "redacted_User-Agent" = "drop"
  1. [accessLog]
  2. # Access Log Format
  3. #
  4. # Optional
  5. # Default: "common"
  6. #
  7. # Accepted values "common", "json"
  8. #
  9. format = "json"
  10. [accessLog.fields.headers]
  11. # defaultMode
  12. #
  13. # Optional
  14. # Default: "keep"
  15. #
  16. # Accepted values "keep", "drop", "redact"
  17. #
  18. defaultMode = "keep"
  19. # Fields map which is used to override headers defaultMode
  20. [accessLog.fields.headers.names]
  21. "User-Agent" = "redact"
  22. "Authorization" = "drop"
  23. "Content-Type" = "keep"
  24. # ...

List of All 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 by processing the response, including the origin server's time but not the log writing time.
FrontendName The name of the Traefik frontend.
BackendName The name of the Traefik backend.
BackendURL The URL of the Traefik backend.
BackendAddr The IP:port of the Traefik backend (extracted from BackendURL)
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.
RequestLine RequestMethod + RequestPath + RequestProtocol
RequestContentSize The number of bytes in the request entity (a.k.a. body) sent by the client.
OriginDuration The time taken 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.
OriginStatusLine OriginStatus + Status code explanation
DownstreamStatus The HTTP status code returned to the client.
DownstreamStatusLine DownstreamStatus + 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 caused by Traefik.
RetryAttempts The amount of attempts the request was retried.

Depreciation Notice

Deprecated way (before 1.4):

DEPRECATED

accessLogsFile is deprecated, use accessLog instead.

  1. # Access logs file
  2. #
  3. # DEPRECATED - see [accessLog]
  4. #
  5. accessLogsFile = "log/access.log"

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.

Note

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

Time Zones

The timestamp of each log line is in UTC time by default.

If you want to use local timezone, you need to ensure the 3 following elements:

  • Provide the timezone data into /usr/share/zoneinfo
  • Set the environement variable TZ to the timezone to be used
  • Specify the field StartLocal instead of StartUTC (works on default Common Log Format (CLF) as well as JSON)

Example using docker-compose:

  1. version: '3'
  2. services:
  3. traefik:
  4. image: containous/traefik:[latest stable version]
  5. ports:
  6. - "80:80"
  7. environment:
  8. - "TZ=US/Alaska"
  9. command:
  10. - --docker
  11. - --accesslog
  12. - --accesslog.fields.names="StartUTC=drop"
  13. volumes:
  14. - "/var/run/docker.sock:/var/run/docker.sock"
  15. - "/usr/share/zoneinfo:/usr/share/zoneinfo:ro"