tracing 지시문

원문 보기 위키 갱신 2026.10.03

tracing 지시문 (OpenTelemetry 추적 연동)

tracing 지시문은 opentelemetry-go를 사용해 OpenTelemetry 추적 기능과의 연동을 켜줘요. 활성화하면 기존 trace context를 전파하거나 새로 초기화해요.

출처: Caddy 공식 문서

본문

opentelemetry-go를 사용해 OpenTelemetry 추적 기능과의 연동을 활성화해요.

활성화하면 기존 trace context를 전파하거나 새 것을 초기화해요.

gRPC를 exporter 프로토콜로, W3C tracecontext와 baggage를 propagator로 사용해요.

trace ID와 span ID는 표준 traceID 및 spanID 필드로 액세스 로그에 추가돼요. 또한 {http.vars.trace_id}와 {http.vars.span_id} placeholder를 사용할 수 있는데, 예를 들어 request_header에서 이 값을 앱에 전달할 수 있어요.

문법 (Syntax)

tracing {
	span <span_name>
	span_attributes {
		<attr1> <value1>
		<attr2> <value2>
	}
}

**<span_name>**은 span 이름이에요. span 이름 지정 가이드라인을 참고해요.
**<span_attributes>**는 기록되는 각 span에 붙는 추가 속성들이에요. 요청·응답·클라이언트에 대한 세부 정보 같은 많은 span 속성이 OTEL HTTP span에 대한 시맨틱 규칙에 따라 기본으로 설정돼요.

Placeholder를 span 이름과 속성에 사용할 수 있어요. span 이름은 요청이 전달되기 전에 설정되므로 요청 placeholder만 사용할 수 있다는 점을 기억해요. span 속성에는 모든 placeholder를 사용할 수 있어요.

설정 (Configuration)

환경 변수

OpenTelemetry 환경 변수 규격이 정의한 환경 변수로 설정할 수 있어요.

exporter 설정 세부 사항은 spec을 참고해요.

예를 들어:

export OTEL_EXPORTER_OTLP_HEADERS="myAuthHeader=myToken,anotherHeader=value"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://my-otlp-endpoint:55680

예시 (Examples)

Caddyfile 예시입니다:

example.com {
	handle /api* {
		tracing {
			span api
		}
		request_header X-Trace-Id {http.vars.trace_id}
		reverse_proxy localhost:8081
	}

	handle {
		tracing {
			span app
			span_attributes {
				user_id {http.request.cookie.user-id}
			}
		}
		reverse_proxy localhost:8080
	}
}

더 알아보기 (Learn more)

Caddy 공식 문서