Skip to main content

Logs and AccessLogs

Logs

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

Helm Chart Configuration Options

Traefik Hub API Gateway logging level and format can be configured using the Helm Chart values. To know more about the Helm Chart options, refer to Helm Chart reference page (Options logs.general).

Configuration Options

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

FieldDescriptionDefaultRequired
log.filePathBy default, the logs are written to the standard output.
You can configure a file path instead using the filePath option.
No
log.formatLog format (commonor json).
The fields displayed with the format common cannot be customized.
commonNo
log.levelLog level (TRACE, DEBUG, INFO, WARN, ERROR, FATAL, and PANIC)ERRORNo
log.noColorWhen using the format common, disables the colorized output.falseNo
log.maxSizeMaximum size in megabytes of the log file before it gets rotated.100mBNo
log.maxAgeMaximum 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 remove based on their age.
Yes
log.maxBackupsMaximum number of old log files to retain.
The default is to retain all old log files.
No
log.compressCompress log files in gzip after rotationfalseNo

AccessLogs

Configuration Example

logs:
access
enabled: true
# JSON format
format: json
# Filter on status codes, rety attempts anf minimal duration
filters:
statusCodes:
- "200"
- "300-302"
retryAttempts: true
minDuration: "10ms"
fields:
general:
# Keep all the fields except 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

Helm Chart Configuration Options

Traefik Hub API Gateway access logs can be configured using the Helm Chart values. To know more about the Helm Chart options, refer to the Helm Chart reference page (Options logs.access).

Configuration Options

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

FieldDescriptionDefaultRequired
accesslog.filePathBy default, the access logs are written to the standard output.
You can configure a file path instead using the filePath option.
No
accesslog.formatBy 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
commonNo
accesslog.bufferingSizeTo 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.
No
accesslog.addInternalsEnables access logs for internal resources (e.g.: ping@internal).falseNo
accesslog.filters.statusCodesLimit the access logs to requests with a status codes in the specified range.falseNo
accesslog.filters.retryAttemptsKeep the access logs when at least one retry has happened.falseNo
accesslog.filters.minDurationKeep access logs when requests take longer than the specified duration (provided in seconds or as a valid duration format, see time.ParseDuration)No
accesslog.fields.defaultModeMode to apply by default to the access logs fields (keep, redact or drop).keepNo
accesslog.fields.namesSet the fields list to display in the access logs (format name:mode).
Available fields list here
No
accesslog.headers.defaultModeMode to apply by default to the access logs headers (keep, redact or drop).dropNo
accesslog.headers.namesSet 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

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 (0).
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.
SpanIdA unique identifier for Traefik’s root span (EntryPoint) within a request trace, formatted as a 16-hex digit string.
TraceIdA consistent identifier for tracking requests across services, including upstream ones managed by Traefik, shown as a 32-hex digit string
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)
TLSClientSubjectThe string representation of the TLS client certificate's Subject (e.g. CN=username,O=organization)

Log Rotation

Traefik Hub API Gateway 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 Hub API Gateway 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.