Traefik 로그 문서

원문 보기 위키 갱신 2026.10.03

Traefik 로그 문서 (Traefik Logs Documentation)

출처: Traefik Logs Documentation

본문

로그 & 액세스 로그 (Logs & AccessLogs)

로그 (Logs)

로그(Logs)는 Traefik 자체에 일어나는 모든 일(시작, 설정, 이벤트, 종료 등)을 다뤄요.

설정 예시 (Configuration Example)

파일 (YAML)

log:
  filePath: "/path/to/log-file.log"
  format: json
  level: INFO

파일 (TOML)

[log]
  filePath = "/path/to/log-file.log"
  format = "json"
  level = "INFO"

CLI

--log.filePath=/path/to/log-file.log
--log.format=json
--log.level=INFO

설정 옵션 (Configuration Options)

아래 섹션은 정적 설정으로 Traefik 로그를 구성하는 방법을 설명해요.

OpenTelemetry

Traefik은 로깅용 OpenTelemetry를 지원해요. OpenTelemetry를 활성화하려면 정적 설정에 다음을 설정해야 해요:

파일 (YAML)

experimental:
  otlpLogs: true

파일 (TOML)

[experimental]
  otlpLogs = true

CLI

--experimental.otlpLogs=true

경고 (Warning)

이것은 실험적 기능이에요.

Stdio 로그는 계속 사용 가능해요 (Stdio logs remain available)

OTLP 로깅이 활성화되면 표준 출력(stdio) 로그는 여전히 사용 가능하며 OTLP 내보내기와 함께 계속 작성돼요.

설정 예시 (Configuration Example)

파일 (YAML)

experimental:
  otlpLogs: true

log:
  otlp:
    http:
      endpoint: https://collector:4318/v1/logs
      headers:
        Authorization: Bearer auth_a...YRdL

파일 (TOML)

[experimental]
  otlpLogs = true

[log.otlp]
  http.endpoint = "https://collector:4318/v1/logs"
  http.headers.Authorization = "Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL"

CLI

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

설정 옵션 (Configuration Options)

log.otlp.http.headers 익스포터가 로그와 함께 OpenTelemetry 컬렉터로 보내는 추가 헤더예요. [ ] | 아니오 (No) |

log.otlp.http.tls 익스포터가 로그를 OpenTelemetry 컬렉터로 보낼 때 사용하는 클라이언트 TLS 설정을 정의해요. | | 아니오 (No) |

log.otlp.http.tls.ca OpenTelemetry 컬렉터와의 보안 연결에 사용하는 인증 기관의 경로로, 기본값은 시스템 번들이에요. | | 아니오 (No) |

log.otlp.http.tls.cert OpenTelemetry 컬렉터에 사용할 인증서의 경로예요. | | 아니오 (No) |

log.otlp.http.tls.key OpenTelemetry 컬렉터에 사용할 키의 경로예요. | | 아니오 (No) |

log.otlp.http.tls.insecureSkipVerify OpenTelemetry 컬렉터가 인증서의 호스트 이름과 관계없이 서버가 제시하는 어떤 인증서든 수락하도록 지시해요. false | 아니오 (No) |

log.otlp.grpc 익스포터가 gRPC를 사용해 로그를 OpenTelemetry 컬렉터로 보내도록 지시해요. | | 아니오 (No) |

log.otlp.grpc.endpoint OpenTelemetry 컬렉터의 끝점이에요. (형식=:) localhost:4317 | 아니오 (No) |

log.otlp.grpc.headers 익스포터가 로그와 함께 OpenTelemetry 컬렉터로 보내는 추가 헤더예요. [ ] | 아니오 (No) |

log.otlp.grpc.insecure 익스포터가 안전하지 않은 프로토콜을 사용해 로그를 OpenTelemetry 컬렉터로 보내도록 지시해요. false | 아니오 (No) |

log.otlp.grpc.tls 익스포터가 로그를 OpenTelemetry 컬렉터로 보낼 때 사용하는 클라이언트 TLS 설정을 정의해요. | | 아니오 (No) |

log.otlp.grpc.tls.ca OpenTelemetry 컬렉터와의 보안 연결에 사용하는 인증 기관의 경로로, 기본값은 시스템 번들이에요. | | 아니오 (No) |

log.otlp.grpc.tls.cert OpenTelemetry 컬렉터에 사용할 인증서의 경로예요. | | 아니오 (No) |

log.otlp.grpc.tls.key OpenTelemetry 컬렉터에 사용할 키의 경로예요. | | 아니오 (No) |

log.otlp.grpc.tls.insecureSkipVerify OpenTelemetry 컬렉터가 인증서의 호스트 이름과 관계없이 서버가 제시하는 어떤 인증서든 수락하도록 지시해요. false | 아니오 (No) |

resourceAttributes

resourceAttributes 옵션은 트레이스와 함께 보내는 리소스 속성을 설정하게 해 줘요. Traefik은 리소스 속성을 설정하기 위해 OTEL_RESOURCE_ATTRIBUTES 환경 변수도 지원해요.

Kubernetes 리소스 속성 감지 (Kubernetes Resource Attributes Detection)

추가로 Traefik은 Kubernetes 클러스터에서 실행될 때 다음 Kubernetes 리소스 속성을 자동으로 발견해요:

k8s.namespace.name
k8s.pod.uid
k8s.pod.name

이 자동 감지는 예를 들어 Traefik 파드가 호스트 네트워크 모드로 실행되는 경우처럼 실패할 수 있다는 점을 주의하세요. 그런 경우 옵션이나 환경 변수로 속성을 직접 제공해야 해요.

액세스 로그 (AccessLogs)

액세스 로그(Access logs)는 Traefik이 처리한 요청(request)에 일어나는 모든 일을 다뤄요.

Stdio 로그는 OTLP 내보내기와 함께 기본적으로 활성화되지 않아요 (Stdio logs are not enabled by default alongside OTLP exports)

Stdio 액세스 로그를 사용하려면 accessLog.dualOutput 옵션을 사용하세요.

설정 예시 (Configuration Example)

파일 (YAML)

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
    queryParameters:
      # Drop all query parameters
      defaultMode: drop

파일 (TOML)

[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.fields.queryParameters]
      defaultMode = "drop"

CLI

--accesslog=true
--accesslog.dualoutput=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
--accesslog.fields.queryparameters.defaultmode=drop

설정 옵션 (Configuration Options)

아래 섹션은 정적 설정으로 Traefik 액세스 로그를 구성하는 방법을 설명해요.

OpenTelemetry

Traefik은 액세스 로그용 OpenTelemetry를 지원해요. OpenTelemetry를 활성화하려면 정적 설정에 다음을 설정해야 해요:

파일 (YAML)

experimental:
  otlpLogs: true

파일 (TOML)

[experimental]
  otlpLogs = true

CLI

--experimental.otlpLogs=true

경고 (Warning)

이것은 실험적 기능이에요.

설정 예시 (Configuration Example)

파일 (YAML)

experimental:
  otlpLogs: true

accesslog:
  # Keep Stdio logs alongside OTEL logging
  dualOutput: true
  otlp:
    http:
      endpoint: https://collector:4318/v1/logs
      headers:
        Authorization: Bearer auth_a...YRdL

파일 (TOML)

[experimental]
  otlpLogs = true

[accessLog]
  dualOutput = true

[accesslog.otlp]
  http.endpoint = "https://collector:4318/v1/logs"
  http.headers.Authorization = "Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL"

CLI

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

설정 옵션 (Configuration Options)

accesslog.otlp.http.headers 익스포터가 액세스 로그와 함께 OpenTelemetry 컬렉터로 보내는 추가 헤더예요. [ ] | 아니오 (No) |

accesslog.otlp.http.tls 익스포터가 액세스 로그를 OpenTelemetry 컬렉터로 보낼 때 사용하는 클라이언트 TLS 설정을 정의해요. | | 아니오 (No) |

accesslog.otlp.http.tls.ca OpenTelemetry 컬렉터와의 보안 연결에 사용하는 인증 기관의 경로로, 기본값은 시스템 번들이에요. | | 아니오 (No) |

accesslog.otlp.http.tls.cert OpenTelemetry 컬렉터에 사용할 인증서의 경로예요. | | 아니오 (No) |

accesslog.otlp.http.tls.key OpenTelemetry 컬렉터에 사용할 키의 경로예요. | | 아니오 (No) |

accesslog.otlp.http.tls.insecureSkipVerify OpenTelemetry 컬렉터가 인증서의 호스트 이름과 관계없이 서버가 제시하는 어떤 인증서든 수락하도록 지시해요. false | 아니오 (No) |

accesslog.otlp.grpc 익스포터가 gRPC를 사용해 액세스 로그를 OpenTelemetry 컬렉터로 보내도록 지시해요. | | 아니오 (No) |

accesslog.otlp.grpc.endpoint OpenTelemetry 컬렉터의 끝점이에요. (형식=:) localhost:4317 | 아니오 (No) |

accesslog.otlp.grpc.headers 익스포터가 액세스 로그와 함께 OpenTelemetry 컬렉터로 보내는 추가 헤더예요. [ ] | 아니오 (No) |

accesslog.otlp.grpc.insecure 익스포터가 안전하지 않은 프로토콜을 사용해 액세스 로그를 OpenTelemetry 컬렉터로 보내도록 지시해요. false | 아니오 (No) |

accesslog.otlp.grpc.tls 익스포터가 액세스 로그를 OpenTelemetry 컬렉터로 보낼 때 사용하는 클라이언트 TLS 설정을 정의해요. | | 아니오 (No) |

accesslog.otlp.grpc.tls.ca OpenTelemetry 컬렉터와의 보안 연결에 사용하는 인증 기관의 경로로, 기본값은 시스템 번들이에요. | | 아니오 (No) |

accesslog.otlp.grpc.tls.cert OpenTelemetry 컬렉터에 사용할 인증서의 경로예요. | | 아니오 (No) |

accesslog.otlp.grpc.tls.key OpenTelemetry 컬렉터에 사용할 키의 경로예요. | | 아니오 (No) |

accesslog.otlp.grpc.tls.insecureSkipVerify OpenTelemetry 컬렉터가 인증서의 호스트 이름과 관계없이 서버가 제시하는 어떤 인증서든 수락하도록 지시해요. false | 아니오 (No) |

resourceAttributes

Kubernetes 리소스 속성 감지 (Kubernetes Resource Attributes Detection)

추가로 Traefik은 Kubernetes 클러스터에서 실행될 때 다음 Kubernetes 리소스 속성을 자동으로 발견해요:

k8s.namespace.name
k8s.pod.uid
k8s.pod.name

Traefik CLF 형식 필드 (Traefik CLF format fields)

이것은 Traefik이 제공하는 기본 형식이에요. Traefik CLF 형식으로 표시되는 필드는 아래와 같아요:

 -  [] 
"  "   
"" "" 
"" "" ms

``은 다운스트림 상태(downstream status)예요.

두 CLF 형식 모두에서 ``은 DownstreamStatus, 즉 클라이언트로 보내는 상태예요. 백엔드 상태(OriginStatus)는 json 형식에서만 사용할 수 있어요.

Generic CLF 형식 필드 (Generic CLF format fields)

generic CLF 형식으로 표시되는 필드는 아래와 같아요:

 -  [] 
"  "   
"" ""

JSON 형식 필드 (JSON format fields)

로그 회전 (Log Rotation)

Traefik은 액세스 로그 파일을 회전하지 않아요. Traefik이 USR1 신호를 받으면 액세스 로그 파일을 닫고 다시 연다. 이를 통해 logrotate 같은 외부 프로그램이 액세스 로그 파일을 회전할 수 있어요.

USR1 신호는 Traefik 로그 파일에는 효과가 없어요. Traefik은 log.maxSize, log.maxAge, log.maxBackups 옵션으로 Traefik 로그 파일을 회전해요.

경고 (Warning)

이것은 USR 신호가 없어서 Windows에서는 동작하지 않아요.

시간대 (Time Zones)

Traefik은 기본적으로 각 로그 줄을 UTC 시간으로 타임스탬프를 찍어요.

환경에서 다음 설정이 이루어졌는지 확인하면 Traefik이 특정 시간대로 타임스탬프를 찍도록 구성할 수 있어요:

/etc/localtime 또는 /usr/share/zoneinfo(배포판에 따라)에 시간대 데이터를 제공하거나, 환경 변수 TZ를 원하는 시간대로 설정하세요.
StartUTC라는 필드를 버리고 StartLocal 필드를 지정하세요 (기본 Common Log Format(CLF)과 JSON 모두에서 사용 가능): accesslog.fields.names.StartUTC=drop.

Docker Compose를 활용한 예시:

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

운영 환경에서 Traefik OSS를 사용하고 계신가요? (Using Traefik OSS in Production?)

직장에서 Traefik을 사용하고 있다면, Traefik OSS에 엔터프라이즈급 API 게이트웨이 기능이나 상업적 지원을 추가하는 것을 고려해 보세요.

API 게이트웨이 데모 영상 보기 (Watch our API Gateway Demo Video)
24/7/365 OSS 지원 요청 (Request 24/7/365 OSS Support)

Traefik OSS에 API 게이트웨이 기능을 추가하는 것은 빠르고 매끄러워요. 교체(rip and replace) 없이 모든 설정이 그대로 유지되며, 이 짧은 영상을 통해 실제 동작을 확인할 수 있어요.

더 알아보기 (Learn more)

Traefik 공식 문서