로그와 액세스 로그
로그와 액세스 로그 (Logs and Access Logs)
본문
로그 & 액세스 로그
로그 (Logs)
로그(Logs)는 Traefik 자체에 일어나는 모든 일(시작, 설정, 이벤트, 종료 등)을 다뤄요.
설정 예시 (Configuration Example)
Traefik Proxy에서 로그를 활성화하고 설정하려면 정적 설정 파일이나(Helm 차트를 쓴다면) Helm 값을 사용하면 돼요.
구조화 (YAML)
log:
filePath: "/path/to/log-file.log"
format: json
level: INFO
구조화 (TOML)
[log]
filePath = "/path/to/log-file.log"
format = "json"
level = "INFO"
Helm 차트 값 (Helm Chart Values)
log:
filePath: "/path/to/log-file.log"
format: json
level: INFO
액세스 로그 (Access Logs)
액세스 로그(Access Logs)는 Traefik이 처리한 요청(request)에 일어나는 모든 일을 다뤄요.
설정 예시 (Configuration Example)
Traefik Proxy에서 액세스 로그를 활성화하고 설정하려면 정적 설정 파일이나(Helm 차트를 쓴다면) Helm 값을 사용하면 돼요.
다음 예시는 JSON 형식으로 액세스 로그를 활성화하고, 특정 상태 코드만 포함하도록 필터링한 뒤, 유지하거나 버릴 필드를 커스터마이즈해요.
구조화 (YAML)
accessLog:
format: json
filters:
statusCodes:
- "200"
- "400-404"
- "500-503"
fields:
names:
ClientUsername: drop
headers:
defaultMode: keep
names:
User-Agent: redact
Content-Type: keep
구조화 (TOML)
[accessLog]
format = "json"
[accessLog.filters]
statusCodes = ["200", "400-404", "500-503"]
[accessLog.fields]
[accessLog.fields.names]
ClientUsername = "drop"
[accessLog.fields.headers]
defaultMode = "keep"
[accessLog.fields.headers.names]
"User-Agent" = "redact"
"Content-Type" = "keep"
Helm 차트 값 (Helm Chart Values)
# values.yaml
accessLog:
enabled: true
format: json
filters:
statusCodes:
- "200"
- "400-404"
- "500-503"
fields:
names:
ClientUsername: drop
headers:
defaultMode: keep
names:
User-Agent: redact
Content-Type: keep
라우터별 액세스 로그 (Per-Router Access Logs)
특정 라우터에 대해 액세스 로그를 활성화하거나 비활성화할 수 있어요. 로그가 많은(noisy) 라우트의 로깅을 끄면서 전역으로는 켜두고 싶을 때 유용하죠.
특정 라우터에서 액세스 로그를 비활성화하는 예시를 볼게요:
구조화 (YAML)
http:
routers:
my-router:
rule: "Host(`example.com`)"
service: my-service
observability:
accessLogs: false
구조화 (TOML)
[http.routers.my-router.observability]
accessLogs = false
Kubernetes
# ingressroute.yaml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: my-router
spec:
routes:
- kind: Rule
match: Host(`example.com`)
services:
- name: my-service
port: 80
observability:
accessLogs: false
Labels (레이블)
labels:
- "traefik.http.routers.my-router.observability.accesslogs=false"
Tags (태그)
{
// ...
"Tags": [
"traefik.http.routers.my-router.observability.accesslogs=false"
]
}
라우터에 observability 옵션이 정의되어 있지 않으면, 엔트리포인트의 관찰성 설정이나 전역 설정의 동작을 상속받아요.
로그 형식 (Log Formats)
Traefik Proxy는 다음 로그 형식을 지원해요:
-
common - Traefik의 확장 CLF 형식 (기본값)
-
genericCLF - 표준 로그 분석기와 호환되는 일반 CLF 형식
-
json - 구조화 로깅용 JSON 형식
기원 상태 vs. 다운스트림 상태 (Origin vs. Downstream Status)
액세스 로그는 Traefik을 기준으로 이름 붙은 두 가지 상태 코드를 보고해요:
Client <---- DownstreamStatus ---- Traefik <---- OriginStatus ---- Backend
-
OriginStatus는 요청을 백엔드로 프록시한 결과예요. 백엔드가 반환한 상태 코드이거나, 백엔드에 도달하지 못하거나 제대로 응답하지 않았을 때(502, 504, ...) 계산된 상태 코드예요.
-
DownstreamStatus는 미들웨어 체인이 실행된 뒤 Traefik이 클라이언트에게 반환한 값이에요.
요청이 변경 없이(unchanged) 프록시되면 둘은 같아요.
둘 다 설정되어 있는데 서로 다르면, 미들웨어가 응답을 다시 쓴(rewrite) 거예요.
OriginStatus가 비어 있으면(0으로 기록됨), 요청은 백엔드로 프록시된 적이 없어요. 응답은 라우팅(일치하는 라우터 없음) 또는 미들웨어(인증, 속도 제한, 리다이렉션)에서 온 거예요.
정보 (Info)
두 필드 모두 json 형식에서만 사용할 수 있어요.
common과 genericCLF 형식, 그리고 statusCodes 필터는 DownstreamStatus 값을 사용해요.
액세스 로그 필터 (Access Log Filters)
Traefik Proxy가 특정 기준에 맞는 요청에 대해서만 액세스 로그를 기록하도록 설정할 수 있어요. 로그의 양을 줄이고 특정 이벤트에 집중할 때 유용해요.
사용 가능한 필터는 다음과 같아요:
-
상태 코드 (Status Codes): 특정 HTTP 상태 코드나 범위(예: 200, 400-404)를 가진 요청에 대해서만 로그를 유지해요.
-
재시도 횟수 (Retry Attempts): 요청 재시도(retry)가 발생한 경우에만 로그를 유지해요.
-
최소 지속 시간 (Minimum Duration): 지정한 시간보다 오래 걸린 요청에 대해서만 로그를 유지해요.
로그 필드 커스터마이즈 (Log Fields Customization)
json 형식을 사용할 때 액세스 로그에 포함할 필드를 커스터마이즈할 수 있어요.
-
요청 필드 (Request Fields): 표준 요청 필드 중 어떤 것을 유지(keep)하거나, 버리거나(drop), 수정할(redact) 수 있어요. ClientHost, RequestMethod, Duration 같은 사용 가능한 필드의 전체 목록은 참조 문서에서 찾을 수 있어요.
-
요청 헤더 (Request Headers): 로그에 포함할 요청 헤더와, 그 값의 유지·버림·수정 여부를 지정할 수 있어요.
-
요청 쿼리 파라미터 (Request Query Parameters): 요청의 쿼리 파라미터를 유지하거나 버릴 수 있어요.
정보 (Info)
자세한 설정 옵션은 참조 문서를 참고하세요.