OTLP란? OpenTelemetry 전송 방식과 설정

OTLP/gRPC와 OTLP/HTTP의 차이, 부분 성공과 재시도의 의미, DataKit으로 보낼 때 필요한 엔드포인트 설정을 설명합니다.

모범 사례
애플리케이션 성능 모니터링의 서비스 트레이스와 메트릭을 보여 주는 그림

Collector에 연결됐어도 요청 경로가 틀리면 데이터는 들어가지 않습니다. HTTP 200을 받아도 수신 측에서 배치 일부를 거부했을 수 있습니다. 원인을 좁히려면 exporter가 어떤 형식과 경로로 보냈는지, 수신 측은 무엇을 받아들였는지 함께 봐야 합니다.

OTLP(OpenTelemetry Protocol)는 텔레메트리의 인코딩과 전송을 정의하는 프로토콜입니다. Protobuf로 메시지를 정의하고 gRPC와 HTTP를 지원합니다. 트레이스, 메트릭, 로그의 전송 명세는 안정화됐고, Profiles는 개발 중입니다. 송신 측과 수신 측이 같은 신호, 전송 방식, 인코딩을 지원하면 데이터를 교환할 수 있습니다.

OTLP 핵심 정리

  • OTLP는 인코딩과 전송을 다룹니다. 저장과 조회는 백엔드가 맡습니다.
  • gRPC는 바이너리 Protobuf를 사용합니다. HTTP에서는 수신 측이 지원할 경우 OTLP의 JSON 인코딩도 사용할 수 있습니다.
  • 개별 스팬, 메트릭, 로그 레코드는 리소스와 계측 스코프 아래에 묶입니다.
  • DataKit은 OTLP 트레이스, 메트릭, 로그를 받습니다. 기본 HTTP 포트는 9529이며 경로는 /otel/v1/로 시작합니다.

OTLP 요청이 오가는 과정

  1. 요청을 만듭니다. SDK exporter나 Collector가 텔레메트리를 OTLP 내보내기 요청으로 묶습니다.
  2. 전송합니다. gRPC의 단항 호출이나 HTTP POST를 사용합니다. gzip 압축, TLS, 인증은 송신·수신 양쪽에서 지원하는 방식으로 설정합니다.
  3. 응답을 읽습니다. 완전한 성공은 현재 수신 측이 배치를 받아들였다는 의미입니다. OTLP/HTTP에서 완전한 성공과 부분 성공은 모두 HTTP 200으로 돌아옵니다. partial_success가 설정돼 있다면 거부 건수와 진단 메시지를 확인합니다. 거부 건수가 0이고 경고만 있을 수도 있습니다. 이 필드가 채워진 응답을 받으면 같은 요청을 다시 보내지 않습니다.

OTLP/HTTP 명세에서 재시도 대상 상태 코드는 429, 502, 503, 504입니다. Retry-After가 있으면 그 값을 따르고, 없으면 지수 백오프로 재시도합니다. 다른 4xx와 5xx는 재시도하지 않습니다. 예를 들어 400이면 페이로드부터 확인합니다. OTLP/gRPC에서는 gRPC 상태 코드와 오류 상세를 따르며, UNAVAILABLE은 재시도할 수 있습니다.

수신 확인은 인접한 송신 측과 수신 측 사이에서만 이루어집니다. Collector가 받았더라도 백엔드에 저장됐는지는 따로 확인해야 합니다. 응답이 네트워크에서 유실되면 재시도로 같은 데이터가 두 번 들어갈 수도 있습니다. OTLP 명세(영어)

OTLP 데이터 모델

트레이스, 메트릭, 로그는 같은 바깥 구조를 사용합니다. 실제 Protobuf 필드 이름은 신호에 따라 다릅니다.

Export<Signal>ServiceRequest
└── resource_<signal>[]
    ├── resource (service.name, host.name, …)
    └── scope_<signal>[]
        ├── scope (name, version, …)
        └── spans[] / metrics[] / log_records[]

스팬에는 trace_id, span_id, 필요한 경우 부모 스팬의 ID, 상태와 속성 등이 들어갑니다. 메트릭에는 Sum, Gauge, Histogram, ExponentialHistogram 등의 유형이 있습니다. 로그 레코드에는 이벤트 시각, 심각도, 본문과 속성이 들어가며 트레이스 컨텍스트도 담을 수 있습니다.

트레이스의 Protobuf 필드는 resource_spans와 scope_spans입니다. OTLP JSON에서는 traceId처럼 키를 lowerCamelCase로 쓰고, 트레이스와 스팬 ID는 16진 문자열, 열거형은 정수로 표현합니다. 범용 JSON 변환기를 쓴다면 결과가 이 규칙과 맞는지 확인해야 합니다.

OTLP/gRPC와 OTLP/HTTP 선택

항목 OTLP/gRPC OTLP/HTTP
표준 기본 포트 4317 4318
요청과 연결 gRPC 연결에서 단항 호출로 내보내기 HTTP POST, 연결 재사용 가능
인코딩 바이너리 Protobuf 바이너리 Protobuf 또는 OTLP JSON. 수신 측 지원에 따름
프록시 요건 gRPC를 올바르게 전달해야 함 POST, 경로, Content-Type이 통과해야 함
디버깅 해당 서비스 정의를 사용할 수 있는 gRPC 클라이언트 curl로 인코딩이 맞는 유효한 본문을 POST

SDK, 프록시, 수신 측이 모두 지원하는 방식을 고릅니다. 둘 다 가능하면 운영에 사용할 배치 크기와 압축 설정으로 처리량과 자원 사용량을 비교합니다. 바이너리 Protobuf를 HTTP로 보낼 때 Content-Type은 application/x-protobuf입니다. 기본 경로는 /v1/traces, /v1/metrics, /v1/logs이며, 실제 설정은 수신 서비스의 경로에 맞춥니다.

애플리케이션을 수신 측에 연결하기

  1. 애플리케이션에서 직접 보냅니다. OpenTelemetry SDK(영어)나 지원되는 자동 계측으로 데이터를 만들고, exporter의 프로토콜과 엔드포인트를 수신 측에 맞춥니다.
  2. Collector를 거칩니다. OpenTelemetry Collector(영어)가 데이터를 받아 설정된 파이프라인에서 배치 처리, 필터링, 민감 정보 제거 등을 한 뒤 내보냅니다.
  3. 기존 트레이스 형식을 변환합니다. 배포판에 Jaeger 또는 Zipkin receiver가 들어 있다면 기존 송신 형식에 맞는 receiver를 활성화하고 OTLP로 내보낼 수 있습니다. 프로토콜, 필드 매핑과 컨텍스트를 확인합니다.

Guance로 보내려면 DataKit OpenTelemetry 입력(영어)과 필요한 신호의 exporter를 활성화합니다. gRPC 예시에 나오는 127.0.0.1:4317은 루프백입니다. 다른 호스트나 네트워크 네임스페이스에서 보낼 때는 송신 측에서 접근할 수 있는 수신 주소를 설정합니다. HTTP는 http/protobuf를 사용합니다. 기본 포트는 9529이고 경로는 각각 /otel/v1/traces, /otel/v1/metrics, /otel/v1/logs입니다.

아래는 신뢰할 수 있는 테스트 네트워크에서 평문으로 DataKit의 기본 HTTP 경로에 연결하는 예입니다. 호스트 이름은 실제 환경에 맞게 바꿉니다.

export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://datakit-host:9529/otel

공통 HTTP 엔드포인트는 베이스 URL입니다. 명세를 따르는 exporter는 여기에 신호별 경로를 붙입니다. OTEL_EXPORTER_OTLP_TRACES_ENDPOINT처럼 개별 신호를 지정하는 변수에는 http://datakit-host:9529/otel/v1/traces 같은 전체 URL을 넣습니다. 메트릭과 로그도 같은 방식입니다. 인증 정보는 수신 측이나 게이트웨이의 설정에 맞춥니다. 실제 Guance 워크스페이스는 DataKit 연결 설정에서 결정됩니다. OTLP exporter 설정(영어)

식별할 수 있는 테스트 배치를 보낸 뒤 의도한 워크스페이스에서 활성화한 신호를 각각 조회합니다. Collector의 필터링과 민감 정보 제거는 설정에 따라 전송 전에 실행됩니다. 로그에서 트레이스로 이동하려면 ID가 일치하고 해당 트레이스가 조회돼야 합니다.

자주 묻는 질문

OTLP 연결은 어떻게 보호하나요? 신뢰할 수 없는 네트워크를 거칠 때는 TLS를 설정하고 수신 측 인증서를 검증합니다. 인증은 배포 구성에 따라 게이트웨이가 요구하는 헤더나 상호 TLS 등을 사용합니다.

OTLP가 병목이 될 수 있나요? 인코딩과 압축, 전송, 수신 처리 모두 비용이 듭니다. 배치를 키우면 요청 오버헤드는 줄어들지만 대기 시간이나 메모리 사용량은 늘 수 있습니다. gzip도 전송량을 줄이는 대신 CPU를 사용합니다. 내보내기 지연, 큐 사용량과 거부 건수를 함께 보면서 조정합니다.

새 exporter가 이전 버전 수신 측과 통신할 수 있나요? Protobuf는 일부 스키마 변경에 호환성을 제공합니다. 예를 들어 이전 수신 측은 모르는 필드를 무시할 수 있습니다. 필요한 신호, 인코딩, 선택 기능을 양쪽 구현에서 모두 지원하는지는 확인해야 합니다.

Guance를 유일한 OTLP 백엔드로 쓸 수 있나요? DataKit 연동이 필요한 신호와 처리 조건을 충족한다면 Guance로 보낼 수 있습니다. 신호별로 조회와 보존, 알림에 필요한 데이터가 들어오는지 확인합니다.

관련 글

참고 자료 OTLP 명세(영어) · Guance OpenTelemetry 연동(영어) · DataKit 문서(영어) · Guance APM(영어)

맞춤형 플랜 상담

문의하기

커뮤니티 가입

WeChat으로 스캔하여
커뮤니티에 가입하세요

Guance 사용해 보기

온라인에서 바로 시작하고 사용한 만큼만 결제하세요.

시작하기

Guance 요금제 선택

코드 저장소