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의 진정한 표준화를 위한 필수 구성 요소다.