donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
55de4f55b037af9554af9007ce834030ac7e729e
llm-wiki/raw/official-docs/log-otel-log-data-model-spec.md
T

9.0 KiB
Raw Blame History

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed
title source_type url archive_url status confidence tags related_projects related_branches created last_reviewed
OpenTelemetry Logs Data Model Specification official-doc https://opentelemetry.io/docs/specs/otel/logs/data-model/ raw high
ca-log-management
opentelemetry
log-signal
structured-logging
official-standard
ca-skeleton-operational-contract
feature-log-management-contract
2026-05-22 2026-05-27

OpenTelemetry Logs Data Model Specification

Layer: raw/official-docs/ — OpenTelemetry Logs Data Model 표준 사양 verbatim 발췌. ca-tmpl log 채택안의 대안 평가용.

Parent / 활용 branch (필수)

Branch 이 자료가 정당화하는 결정
raw/branch-notes/feature-log-management-contract ca-tmpl stdout JSON default 대안으로 OTel log signal 직접 emit 평가의 1차 근거
raw/project-notes/ca-skeleton-operational-contract Group G-A (Log management) 대안 3 — OpenTelemetry Log signal 의 baseline

컨텍스트

ca-tmpl이 stdout JSON으로 log을 emit하는 default 대신, OpenTelemetry log signal로 직접 emit하는 대안 평가. tracing은 OTel을 채택했으므로 log signal 통합이 자연스러운지 검토.

출처 / Source

핵심 인용 / Key quotes (verbatim)

[§Logs Data Model — opening] "This is a data model and semantic conventions that allow to represent logs from various sources: application log files, machine generated events, system logs, etc."

[§Design Notes > Requirements] "The purpose of the data model is to have a common understanding of what a log record is, what data needs to be recorded, transferred, stored and interpreted by a logging system."

[§Design Notes > Requirements] "It should be possible to unambiguously map existing log formats to this Data Model. Translating log data from an arbitrary log format to this Data Model and back should ideally result in identical data."

[§Severity Fields > Field: SeverityNumber] "The following table defines the meaning of SeverityNumber value: 1-4 TRACE, 5-8 DEBUG, 9-12 INFO, 13-16 WARN, 17-20 ERROR, 21-24 FATAL"

[§Trace Context Fields] "Request trace ID as defined in W3C Trace Context. Can be set for logs that are part of request processing and have an assigned trace ID." + "If SpanId is present TraceId SHOULD be also present."

Claims Extracted / 추출된 주장

Claim ID Claim (이 자료가 직접 말하는 것) Evidence quote Strength Applies to Does not prove
LOG-OTEL-C1 OTel Logs Data Model 은 다양한 source (application log file, machine event, system log 등) 의 log 를 표현하는 공식 data model + semantic conventions [§Logs Data Model — opening] "This is a data model and semantic conventions that allow to represent logs from various sources: application log files, machine generated events, system logs, etc." official-standard OpenTelemetry signal 채택 환경 OTel 이 모든 vendor 의 default log format 이라는 뜻은 아님
LOG-OTEL-C2 본 data model 의 목적은 logging system 이 기록/전송/저장/해석하는 log record 의 공통 정의 제공 [§Design Notes > Requirements] "The purpose of the data model is to have a common understanding of what a log record is, what data needs to be recorded, transferred, stored and interpreted by a logging system." official-standard OTel-compliant logging pipeline 설계 모든 log producer 가 OTel 로 마이그레이션해야 한다는 뜻은 아님
LOG-OTEL-C3 data model 은 lossless translation 을 목표로 설계됨 — 기존 log format ↔ data model 양방향 변환 시 ideally identical data 유지 [§Design Notes > Requirements] "It should be possible to unambiguously map existing log formats to this Data Model. Translating log data from an arbitrary log format to this Data Model and back should ideally result in identical data." official-standard log format migration / bridge 구현 실제 모든 기존 format (syslog 등) 이 100% lossless 변환된다는 보장은 아님 — "ideally"
LOG-OTEL-C4 SeverityNumber 는 syslog-style numeric mapping 사용: TRACE=1–4, DEBUG=5–8, INFO=9–12, WARN=13–16, ERROR=17–20, FATAL=21–24 [§Severity Fields > Field: SeverityNumber] "The following table defines the meaning of SeverityNumber value: 1-4 TRACE, 5-8 DEBUG, 9-12 INFO, 13-16 WARN, 17-20 ERROR, 21-24 FATAL" official-standard OTel SDK / collector severity mapping SLF4J / Log4j / Logback level 과 1:1 매핑된다는 보장은 아님 — 변환 필요
LOG-OTEL-C5 LogRecord 의 TraceId 는 W3C Trace Context 의 request trace ID 정의를 따름. SpanId 가 있으면 TraceId 도 SHOULD 함께 존재 [§Trace Context Fields] "Request trace ID as defined in W3C Trace Context. Can be set for logs that are part of request processing and have an assigned trace ID." + "If SpanId is present TraceId SHOULD be also present." official-standard OTel log-trace correlation 구현 SDK 가 active span 의 TraceId 를 자동 주입한다는 보장은 본 spec 인용에 없음 — bridge implementation 별로 다름
LOG-OTEL-C6 LogRecord 는 다음 field 들로 구성: Timestamp, ObservedTimestamp, TraceId, SpanId, TraceFlags, SeverityText, SeverityNumber, Body, Resource, InstrumentationScope, Attributes, EventName (12개) [§Log and Event Record Definition] (field list enumeration in spec body) official-standard OTel LogRecord 구조 이해 모든 field 가 모든 emit 시점에 채워져야 한다는 뜻은 아님 — 다수가 optional

Usage Boundaries / 적용 경계

  • 이 자료가 직접 증명하는 것:
    • LOG-OTEL-C1, C2: OTel Logs Data Model 의 정의와 목적
    • LOG-OTEL-C3: lossless translation 설계 목표 (보장이 아닌 design goal)
    • LOG-OTEL-C4: SeverityNumber 의 정확한 numeric range
    • LOG-OTEL-C5: TraceId 가 W3C Trace Context 를 따른다는 사실 + SpanId/TraceId 의 SHOULD 관계
    • LOG-OTEL-C6: LogRecord 의 12개 field 구성
  • 이 자료가 증명하지 않는 것:
    • Logback OpenTelemetryAppender 가 active span 의 TraceId 를 자동 주입한다는 SDK-level 동작 (별도 opentelemetry-logback-appender-1.0 문서 필요)
    • OTel log signal 의 ecosystem maturity 평가 (vendor 별 지원 수준)
    • stdout JSON 대비 OTLP push 의 정량적 overhead 비교
    • ECS field 와 OTel field 의 1:1 매핑표 (별도 semantic conventions 필요)
  • 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
    • ca-tmpl 의 logback config 에 OpenTelemetryAppender 추가 시 SeverityNumber 변환이 자동인지 (SLF4J INFO → OTel 9–12 매핑)
    • OTel collector 가 ca-tmpl deployment 환경 (K8s sidecar / DaemonSet) 에서 stable 한지
    • log signal export 실패 시 fallback 으로 stdout JSON 동시 emit 가능한지

메모 / Notes (내 프로젝트 해석)

본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

  • emit 모델: SDK가 LogRecord를 OTLP로 export. stdout JSON 대신 OTLP gRPC/HTTP. logback appender(OpenTelemetryAppender)가 brigde 역할.
  • 자동 trace context 주입: active span의 TraceId/SpanId가 LogRecord에 자동 부착됨 (MDC 수작업 불필요). — 주의: 이는 bridge implementation 동작이며 본 spec 인용으로 증명되지 않음.
  • 장점:
    • tracing/metrics와 같은 transport(OTLP) → collector 통합.
    • trace-log correlation이 SDK 레벨에서 보장.
    • vendor-neutral (Loki/Tempo/Jaeger/Datadog/Honeycomb 모두 OTLP 수신 가능).
  • 단점:
    • logs signal은 2024-01에 GA. tracing/metrics 대비 ecosystem maturity 낮음.
    • SDK overhead (push 기반 vs stdout flush).
    • stdout JSON은 container/k8s 친화적, OTLP는 collector deploy 추가 필요.
    • severity number mapping이 SLF4J level과 완전 일치하지 않음 (변환 필요).
  • ca-tmpl과의 차이:
    • ca-tmpl은 stdout JSON default + file logging은 local/dev only로 결정.
    • OTel log signal 채택 시 stdout 우회하고 OTLP exporter로 직접 push.
    • tracing은 이미 OTel 채택했으므로 log signal로 확장 가능하지만, 현재 ca-tmpl 결정은 stdout JSON.
    • OTel log signal은 ECS field와 일부 매핑(예: TraceId ↔ trace.id) 권장.

Related / 관련

Reference in New Issue View Git Blame Copy Permalink