Access Logs Configuration

Access logs provide detailed information about every request handled by Traefik, including source IP, request details, response status, processing time, and more.

Overview

Access logs enable you to:

Monitor incoming traffic patterns
Analyze request/response metrics
Debug routing issues
Track client behavior
Audit security events
Generate analytics

By default, access logs are written to stdout in Traefik’s extended Common Log Format (CLF).

Basic Configuration

Enable access logs:

accessLog: {}

Configuration Options

File Path

filePath

string

default:"stdout"

Path to the access log file. If not specified, logs are written to stdout.

accessLog:
  filePath: /var/log/traefik/access.log

Format

format

string

default:"common"

Log output format: common, genericCLF, or json.

Common (Traefik CLF)
Generic CLF
JSON

Traefik’s extended Common Log Format with additional fields:

accessLog:
  format: common

Format:

<remote_IP> - <client_user> [<timestamp>] "<method> <path> <protocol>" <status> <size> "<referrer>" "<user_agent>" <request_count> "<router>" "<service_url>" <duration>ms

Example:

192.168.1.100 - - [03/Mar/2026:10:00:00 +0000] "GET /api/users HTTP/1.1" 200 1234 "-" "Mozilla/5.0" 42 "api-router@docker" "http://backend:8080" 45ms

Standard Common Log Format compatible with standard log analyzers:

accessLog:
  format: genericCLF

Format:

<remote_IP> - <client_user> [<timestamp>] "<method> <path> <protocol>" <status> <size> "<referrer>" "<user_agent>"

Omits Traefik-specific fields (request count, router, service, duration).

Structured JSON format for log aggregation and analysis:

accessLog:
  format: json

Example:

{
  "ClientHost": "192.168.1.100",
  "ClientPort": "52143",
  "ClientUsername": "-",
  "DownstreamContentSize": 1234,
  "DownstreamStatus": 200,
  "Duration": 45000000,
  "RequestMethod": "GET",
  "RequestPath": "/api/users",
  "RequestProtocol": "HTTP/1.1",
  "RouterName": "api-router@docker",
  "ServiceURL": "http://backend:8080",
  "StartUTC": "2026-03-03T10:00:00Z"
}

Add Internals

addInternals

boolean

default:"false"

Enable access logs for internal resources like ping@internal.

accessLog:
  addInternals: true

Buffering

bufferingSize

integer

default:"0"

Number of log lines to buffer in memory before writing. Improves performance for high-traffic scenarios.

accessLog:
  filePath: /var/log/traefik/access.log
  bufferingSize: 100

Filtering

Filter access logs to reduce volume and focus on specific requests:

Status Codes

filters.statusCodes

array

default:"[]"

Log only requests with specific status codes or ranges.

accessLog:
  filters:
    statusCodes:
      - "200"
      - "300-302"
      - "400-499"

Retry Attempts

filters.retryAttempts

boolean

default:"false"

Log only requests that were retried at least once.

accessLog:
  filters:
    retryAttempts: true

Minimum Duration

filters.minDuration

duration

default:"0"

Log only requests that took longer than specified duration.

accessLog:
  filters:
    minDuration: 10ms

Combined Filters

Filters are OR-connected (any matching filter will log the request):

accessLog:
  format: json
  filters:
    statusCodes:
      - "400-599"  # Client and server errors
    retryAttempts: true
    minDuration: 100ms

This logs requests that:

Have 4xx or 5xx status codes, OR
Were retried at least once, OR
Took longer than 100ms

Field Customization

Control which fields are logged:

Default Mode

fields.defaultMode

string

default:"keep"

Default action for fields: keep or drop.

Field Names

fields.names

object

default:"{}"

Override specific field behavior: keep or drop.

accessLog:
  format: json
  fields:
    defaultMode: keep
    names:
      ClientUsername: drop
      Duration: keep

Header Fields

fields.headers.defaultMode

string

default:"drop"

Default action for headers: keep, drop, or redact.

fields.headers.names

object

default:"{}"

Override specific header behavior: keep, drop, or redact.

accessLog:
  fields:
    headers:
      defaultMode: keep
      names:
        User-Agent: redact
        Authorization: drop
        Content-Type: keep
        X-Custom-Header: keep

keep - Include header value
drop - Exclude header completely
redact - Replace value with “REDACTED”

Available Fields

Complete list of available fields in access logs:

Field	Description
`StartUTC`	Request start time in UTC
`StartLocal`	Request start time in local timezone
`Duration`	Total processing time in nanoseconds
`RouterName`	Traefik router name
`ServiceName`	Traefik service name
`ServiceURL`	Backend service URL
`ServiceAddr`	Backend IP:port
`ClientAddr`	Client address (IP:port)
`ClientHost`	Client IP address
`ClientPort`	Client TCP port
`ClientUsername`	HTTP basic auth username
`RequestAddr`	HTTP Host header (IP:port)
`RequestHost`	HTTP Host (without port)
`RequestPort`	HTTP Host port
`RequestMethod`	HTTP method (GET, POST, etc.)
`RequestPath`	Request URI path
`RequestProtocol`	HTTP version
`RequestScheme`	http or https
`RequestLine`	Full request line
`RequestContentSize`	Request body size in bytes
`OriginDuration`	Upstream processing time
`OriginContentSize`	Upstream response size
`OriginStatus`	Upstream HTTP status
`DownstreamStatus`	Status returned to client
`DownstreamContentSize`	Response size to client
`RequestCount`	Total requests since startup
`GzipRatio`	Compression ratio
`Overhead`	Traefik processing overhead
`RetryAttempts`	Number of retries
`TLSVersion`	TLS version (1.2, 1.3)
`TLSCipher`	TLS cipher suite
`TLSClientSubject`	Client certificate subject
`TraceId`	Distributed trace ID (32-hex)
`SpanId`	Root span ID (16-hex)

Time Zones

By default, timestamps use UTC. Configure local timezone:

Using Environment Variable

services:
  traefik:
    image: traefik:v3.0
    environment:
      - TZ=America/New_York
    command:
      - --accesslog=true
      - --accesslog.fields.names.StartUTC=drop

Using Volume Mount

services:
  traefik:
    image: traefik:v3.0
    volumes:
      - /usr/share/zoneinfo/America/New_York:/etc/localtime:ro
    command:
      - --accesslog=true
      - --accesslog.fields.names.StartUTC=drop

Drop StartUTC and keep StartLocal to use local timestamps.

Log Rotation

Traefik supports external log rotation using USR1 signal:

kill -USR1 <traefik-pid>

Example logrotate configuration:

/var/log/traefik/access.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    postrotate
        killall -USR1 traefik
    endscript
}

Windows SupportUSR1 signal rotation is not supported on Windows.

OpenTelemetry Access Logs

Experimental FeatureOpenTelemetry access logs are currently experimental.

Enable Experimental Feature

experimental:
  otlpLogs: true

accessLog:
  otlp:
    serviceName: traefik-access
    http:
      endpoint: https://otel-collector:4318/v1/logs

OTLP Configuration

Same configuration options as Traefik logs:

serviceName - Service identifier
resourceAttributes - Additional attributes
http - HTTP protocol configuration
grpc - gRPC protocol configuration
tls - TLS settings

See Logs documentation for detailed OTLP configuration.

Complete Examples

Production Setup

accessLog:
  format: json
  filePath: /var/log/traefik/access.log
  bufferingSize: 100
  filters:
    statusCodes:
      - "400-599"
    minDuration: 100ms
  fields:
    defaultMode: keep
    names:
      ClientUsername: drop
    headers:
      defaultMode: drop
      names:
        User-Agent: keep
        X-Forwarded-For: keep
        Authorization: drop
        Cookie: drop

Development Setup

accessLog:
  format: common

High-Traffic Optimized

accessLog:
  format: json
  filePath: /var/log/traefik/access.log
  bufferingSize: 1000
  filters:
    # Only log errors and slow requests
    statusCodes:
      - "500-599"
    minDuration: 500ms
  fields:
    defaultMode: keep
    names:
      # Drop high-cardinality fields
      RequestCount: drop
      GzipRatio: drop
    headers:
      defaultMode: drop

Security-Focused Logging

accessLog:
  format: json
  filePath: /var/log/traefik/access.log
  filters:
    # Log authentication failures and suspicious activity
    statusCodes:
      - "401"
      - "403"
      - "404"
  fields:
    headers:
      defaultMode: drop
      names:
        User-Agent: keep
        X-Forwarded-For: keep
        X-Real-Ip: keep
        # Redact sensitive headers
        Authorization: redact
        Cookie: redact
        X-Api-Key: drop

Best Practices

Performance

Use buffering for high-traffic deployments
Filter logs to reduce volume
Use JSON format for structured log processing
Avoid logging all headers (high overhead)

Security

Drop or redact sensitive headers (Authorization, Cookie, API keys)
Don’t log request/response bodies
Secure log files with appropriate permissions
Rotate logs regularly to prevent disk exhaustion

Monitoring

Log errors and slow requests (use filters)
Include trace IDs for distributed tracing correlation
Monitor log file sizes
Integrate with log aggregation systems (ELK, Loki, etc.)

Getting Started

Core Configuration

Providers

Routing

Middlewares

HTTPS & TLS

Observability

Operations

Access Logs Configuration

Access Logs Configuration

Overview

Basic Configuration

Configuration Options

File Path

Format

Add Internals

Buffering

Filtering

Status Codes

Retry Attempts

Minimum Duration

Combined Filters

Field Customization

Default Mode

Field Names

Header Fields

Available Fields

Time Zones

Using Environment Variable

Using Volume Mount

Log Rotation

OpenTelemetry Access Logs

Enable Experimental Feature

OTLP Configuration

Complete Examples

Production Setup

Development Setup

High-Traffic Optimized

Security-Focused Logging

Best Practices

Getting Started

Core Configuration

Providers

Routing

Middlewares

HTTPS & TLS

Observability

Operations

Documentation Index

​Access Logs Configuration

​Overview

​Basic Configuration

​Configuration Options

​File Path

​Format

​Add Internals

​Buffering

​Filtering

​Status Codes

​Retry Attempts

​Minimum Duration

​Combined Filters

​Field Customization

​Default Mode

​Field Names

​Header Fields

​Available Fields

​Time Zones

​Using Environment Variable

​Using Volume Mount

​Log Rotation

​OpenTelemetry Access Logs

​Enable Experimental Feature

​OTLP Configuration

​Complete Examples

​Production Setup

​Development Setup

​High-Traffic Optimized

​Security-Focused Logging

​Best Practices

Access Logs Configuration

Overview

Basic Configuration

Configuration Options

File Path

Format

Add Internals

Buffering

Filtering

Status Codes

Retry Attempts

Minimum Duration

Combined Filters

Field Customization

Default Mode

Field Names

Header Fields

Available Fields

Time Zones

Using Environment Variable

Using Volume Mount

Log Rotation

OpenTelemetry Access Logs

Enable Experimental Feature

OTLP Configuration

Complete Examples

Production Setup

Development Setup

High-Traffic Optimized

Security-Focused Logging

Best Practices