OpenTelemetry Semantic Conventions

개요

OpenTelemetry Semantic Conventions(이하 OTel SemConv)은 분산 추적(Tracing), 메트릭(Metrics), 로그(Logs) 데이터를 공통된 규칙과 명명 체계로 구조화하기 위한 표준 규약이다. 이는 서로 다른 서비스, 언어, 프레임워크 간에도 일관된 관측 데이터(Context)를 생성하고 분석할 수 있도록 한다.

SemConv는 단순한 명명 규칙이 아닌, **Telemetry 데이터의 스키마 표준(Schema Definition)**으로서, Observability의 신뢰성과 상호운용성을 보장한다.

---

1. 개념 및 정의

OpenTelemetry Semantic Conventions는 Telemetry 데이터의 필드 이름, 속성(Key/Value), 단위(Unit), 네이밍 규칙을 표준화한 규약이다. 예를 들어, HTTP 요청의 경우 다음과 같은 공통 속성을 정의한다.

• http.method: GET, POST 등 요청 메서드
• http.status_code: HTTP 응답 코드
• url.full: 전체 요청 URL

이를 통해 Prometheus, Jaeger, Datadog, New Relic 등 다양한 APM 도구 간에도 동일한 관측 정보를 해석할 수 있다.

---

2. 특징

항목	설명	비고
표준화된 키 네이밍	Telemetry 속성(Key)을 규칙적으로 정의	예: db.system, net.peer.name
도메인별 스키마 구분	HTTP, DB, Messaging, RPC 등으로 분류	구조적 관리 용이
상호운용성	다양한 Observability 백엔드와 호환	OpenTelemetry Collector 기반
확장성	Custom Attribute 추가 가능	서비스별 확장 허용
버전 관리	Schema Versioning 체계 지원	하위 호환성 유지

→ 일관된 Telemetry 데이터 구조는 복잡한 마이크로서비스 환경에서 분석 정확도를 높인다.

---

3. 구성 요소

구성 요소	설명	예시
Traces	요청 흐름을 추적하는 스팬(Span) 데이터	trace_id, span_id, span.name
Metrics	성능 및 상태 수치를 수집	http.server.duration, db.query.time
Logs	이벤트 및 오류 기록	log.severity, log.message
Resource	서비스/호스트 메타데이터	service.name, host.arch
Instrumentation Scope	라이브러리 및 SDK 정보	instrumentation.name, version

→ SemConv는 이 모든 데이터 타입에 공통적인 속성 모델을 정의하여 분석 일관성을 제공한다.

---

4. 기술 요소

기술 요소	설명	관련 표준
OTLP(OpenTelemetry Protocol)	Telemetry 전송을 위한 표준 프로토콜	gRPC / HTTP 기반
Schema Definition	속성명 및 단위 정의 문서	schema.yaml, attributes.json
Trace Semantic Conventions	스팬 속성 규칙 정의	trace/semantic_conventions 디렉토리
Metrics Semantic Conventions	메트릭 네이밍 및 단위 표준화	metrics/semantic_conventions
Logging Semantic Conventions	로그 필드 표준화	log/semantic_conventions

→ OpenTelemetry 공식 GitHub 저장소에서 JSON Schema로 관리되며, Collector 및 SDK가 이를 준수한다.

---

5. 장점 및 이점

구분	설명	효과
데이터 일관성	동일한 키 구조를 통해 분석 단순화	관측 신뢰성 향상
상호운용성	다양한 벤더 및 백엔드 간 호환	멀티플랫폼 통합 지원
유지보수성	버전 관리 기반 변경 추적	스키마 충돌 최소화
자동화 용이성	표준 키 기반 필터링 및 대시보드 자동 구성	운영 효율 증대
분석 정확도	필드 명명 표준화로 데이터 품질 향상	APM 성능 개선

→ SemConv는 ‘데이터 모델링’ 수준의 표준화로 Telemetry 생태계 전반의 통합을 이끈다.

---

6. 주요 활용 사례 및 고려사항

사례	내용	기대 효과
마이크로서비스 관측	각 서비스별 Telemetry를 동일 스키마로 수집	서비스 간 연관 분석 용이
멀티벤더 Observability	Datadog, Prometheus, Grafana 통합	플랫폼 독립적 모니터링
대규모 분산 트레이싱	HTTP/gRPC 스팬 데이터 정규화	추적 분석 자동화
클라우드 네이티브 모니터링	Kubernetes 기반 Pod/Node 메타데이터 활용	자원-서비스 상관관계 분석

고려사항: Custom Attributes 정의 시 표준 키와 중복되지 않도록 주의해야 하며, Schema 버전 업 시 Collector 호환성을 검증해야 한다.

---

7. 결론

OpenTelemetry Semantic Conventions는 관측 데이터의 언어를 통일하는 핵심 규약이다. 다양한 Telemetry 소스가 존재하는 환경에서 데이터의 의미를 일관되게 표현함으로써, 조직 전반의 모니터링, 분석, 문제 해결 효율성을 극대화한다. Observability의 진정한 표준화를 위한 필수 구성 요소다.