Logs and AccessLogs

Logs

Logs capture all events related to Traefik Hub API Gateway, including startup, configuration changes, runtime events, and shutdown.

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.

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.		No
log.maxBackups	Maximum number of old log files to retain. The default is to retain all old log files.		No
log.compress	Compress log files in gzip after rotation	false	No

OpenTelemetry

Traefik Hub API Gateway supports OpenTelemetry for logging. To enable OpenTelemetry, you need to set the following in the Helm Chart values:

additionalArguments:
  - --experimental.otlpLogs=true

warning

This is an experimental feature.

Configuration Example

Helm Chart

additionalArguments:
  - --experimental.otlpLogs=true
  - --log.otlp.http.endpoint=https://collector:4318/v1/logs
  - --log.otlp.http.headers.Authorization=Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL

Static Configuration

experimental:
  otlpLogs: true

log:
  otlp:
    http:
      endpoint: https://collector:4318/v1/logs

Configuration Options

Field	Description	Default	Required
log.otlp.http	This instructs the exporter to send logs to the OpenTelemetry Collector using HTTP.		No
log.otlp.http.endpoint	The endpoint of the OpenTelemetry Collector.	https://localhost:4318/v1/logs (format=<scheme>://<host>:<port><path>)	No
log.otlp.http.headers	Additional headers sent with logs by the exporter to the OpenTelemetry Collector.		No
log.otlp.http.tls	Defines the Client TLS configuration used by the exporter to send logs to the OpenTelemetry Collector.		No
log.otlp.http.tls.ca	The path to the certificate authority used for the secure connection to the OpenTelemetry Collector, it defaults to the system bundle.		No
log.otlp.http.tls.cert	The path to the certificate to use for the OpenTelemetry Collector.		No
log.otlp.http.tls.key	The path to the key to use for the OpenTelemetry Collector.		No
log.otlp.http.tls.insecureSkipVerify	Instructs the OpenTelemetry Collector to accept any certificate presented by the server regardless of the hostname in the certificate.	false	No
log.otlp.grpc	This instructs the exporter to send logs to the OpenTelemetry Collector using gRPC.		No
log.otlp.grpc.endpoint	The endpoint of the OpenTelemetry Collector.	localhost:4317 (format=<host>:<port>)	No
log.otlp.grpc.headers	Additional headers sent with logs by the exporter to the OpenTelemetry Collector.		No
log.otlp.grpc.insecure	Instructs the exporter to send logs to the OpenTelemetry Collector using an insecure protocol.	false	No
log.otlp.grpc.tls	Defines the Client TLS configuration used by the exporter to send logs to the OpenTelemetry Collector.		No
log.otlp.grpc.tls.ca	The path to the certificate authority used for the secure connection to the OpenTelemetry Collector, it defaults to the system bundle.		No
log.otlp.grpc.tls.cert	The path to the certificate to use for the OpenTelemetry Collector.		No
log.otlp.grpc.tls.key	The path to the key to use for the OpenTelemetry Collector.		No
log.otlp.grpc.tls.insecureSkipVerify	Instructs the OpenTelemetry Collector to accept any certificate presented by the server regardless of the hostname in the certificate.	false	No

AccessLogs

Configuration Example

Helm Chart

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

Static Configuration

accessLog:
  # JSON format
  format: json
  # Filter on status codes, rety attempts anf minimal duration
  filters:
    statusCodes:
      - "200"
      - "300-302"
    retryAttempts: true
    minDuration: "10ms"
  fields:
    # 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.

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 help improve performance.		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)		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

OpenTelemetry

Traefik Hub API Gateway supports OpenTelemetry for access logs. To enable OpenTelemetry, you need to set the following in the Helm Chart values:

additionalArguments:
  - --experimental.otlpLogs=true

warning

This is an experimental feature.

Configuration Example

Helm Chart

additionalArguments:
  - --experimental.otlpLogs=true
  - --accesslog.otlp.http.endpoint=https://collector:4318/v1/logs
  - --accesslog.otlp.http.headers.Authorization=Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL

Static Configuration

experimental:
  otlpLogs: true

accesslog:
  otlp:
    http:
      endpoint: https://collector:4318/v1/logs

Configuration Options

Field	Description	Default	Required
accesslog.otlp.http	This instructs the exporter to send access logs to the OpenTelemetry Collector using HTTP.		No
accesslog.otlp.http.endpoint	The endpoint of the OpenTelemetry Collector.	https://localhost:4318/v1/logs (format=<scheme>://<host>:<port><path>)	No
accesslog.otlp.http.headers	Additional headers sent with access logs by the exporter to the OpenTelemetry Collector.		No
accesslog.otlp.http.tls	Defines the Client TLS configuration used by the exporter to send access logs to the OpenTelemetry Collector.		No
accesslog.otlp.http.tls.ca	The path to the certificate authority used for the secure connection to the OpenTelemetry Collector, it defaults to the system bundle.		No
accesslog.otlp.http.tls.cert	The path to the certificate to use for the OpenTelemetry Collector.		No
accesslog.otlp.http.tls.key	The path to the key to use for the OpenTelemetry Collector.		No
accesslog.otlp.http.tls.insecureSkipVerify	Instructs the OpenTelemetry Collector to accept any certificate presented by the server regardless of the hostname in the certificate.	false	No
accesslog.otlp.grpc	This instructs the exporter to send access logs to the OpenTelemetry Collector using gRPC.		No
accesslog.otlp.grpc.endpoint	The endpoint of the OpenTelemetry Collector.	localhost:4317 (format=<host>:<port>)	No
accesslog.otlp.grpc.headers	Additional headers sent with access logs by the exporter to the OpenTelemetry Collector.		No
accesslog.otlp.grpc.insecure	Instructs the exporter to send access logs to the OpenTelemetry Collector using an insecure protocol.	false	No
accesslog.otlp.grpc.tls	Defines the Client TLS configuration used by the exporter to send access logs to the OpenTelemetry Collector.		No
accesslog.otlp.grpc.tls.ca	The path to the certificate authority used for the secure connection to the OpenTelemetry Collector, it defaults to the system bundle.		No
accesslog.otlp.grpc.tls.cert	The path to the certificate to use for the OpenTelemetry Collector.		No
accesslog.otlp.grpc.tls.key	The path to the key to use for the OpenTelemetry Collector.		No
accesslog.otlp.grpc.tls.insecureSkipVerify	Instructs the OpenTelemetry Collector to accept any certificate presented by the server regardless of the hostname in the certificate.	false	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	RequestMethod + RequestPath + 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 (for example, 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	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 (in nanoseconds) caused by Traefik.
RetryAttempts	The amount of attempts the request was retried.
SpanId	A unique identifier for Traefik’s root span (EntryPoint) within a request trace, formatted as a 16-hex digit string.
TraceId	A consistent identifier for tracking requests across services, including upstream ones managed by Traefik, shown as a 32-hex digit string
TLSVersion	The TLS version used by the connection (for example, 1.2) (if connection is TLS).
TLSCipher	The TLS cipher used by the connection (for example, TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA) (if connection is TLS)
TLSClientSubject	The string representation of the TLS client certificate's Subject (for example, 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 in both the default Common Log Format (CLF) and JSON): accesslog.fields.names.StartUTC=drop.