156 lines
13 KiB
Markdown
156 lines
13 KiB
Markdown
---
|
||
title: Observability Baseline (Log + Metric + Trace + Runbook)
|
||
source_type: llm-generated
|
||
status: draft
|
||
confidence: medium
|
||
tags: [observability, logging, metrics, tracing, runbook, sre]
|
||
related_projects: [ca-skeleton]
|
||
last_reviewed: 2026-05-22
|
||
---
|
||
|
||
# Observability Baseline (Log + Metric + Trace + Runbook)
|
||
|
||
> Layer: `wiki/concepts/` — 일반 개념. 내 프로젝트 사실은 project 문서에서 다룬다.
|
||
|
||
## Summary
|
||
|
||
Observability는 세 가지 신호(structured log, metric, distributed trace)와 이를 운영 행위로 잇는 runbook이 결합될 때 성립한다. ca-tmpl은 **JSON Logback + Micrometer dot.case 이름 규칙 + W3C tracecontext 전파 + `runbook://` URI 스킴**을 기본선으로 잡아 네 축을 하나의 운영 계약으로 묶는다. 어느 한 축만 갖추면 인시던트 시 "왜·어디서·어떻게 대응할지"를 답할 수 없다.
|
||
|
||
## Standard (공식 정의)
|
||
|
||
### Log
|
||
|
||
- **ECS (Elastic Common Schema)**: `@timestamp`, `log.level`, `service.name`, `trace.id`, `event.dataset` 등 필드명을 표준화. Elastic이 정의한 공개 스키마지만 OTel·Loki·Datadog도 부분 호환.
|
||
- **OpenTelemetry Log Data Model**: log record를 trace/metric과 동일 SDK로 다루는 신호. `SeverityNumber`, `Body`, `Attributes`, `TraceId`/`SpanId` correlation을 정의.
|
||
- **Structured logging best practice**: 자유 텍스트가 아닌 key-value JSON. PII는 발신 측에서 마스킹 (Logback `ch.qos.logback.classic.pattern` 또는 `MaskingPatternLayout`).
|
||
|
||
### Metric
|
||
|
||
- **Micrometer**: JVM 표준 facade. 이름은 `dot.case` (`http.server.requests`), `meterRegistry`가 backend별 변환을 담당.
|
||
- **Prometheus**: pull-based, label cardinality bound 권장. exporter가 dot을 `_`로 변환 (`http_server_requests_seconds_count`).
|
||
- **OpenTelemetry Metrics Data Model**: counter / gauge / histogram / exponential histogram을 정의. instrument 종류와 aggregation을 분리.
|
||
- **RED method (Tom Wilkie)**: Request rate / Error rate / Duration. request-driven 서비스 표준.
|
||
- **USE method (Brendan Gregg)**: Utilization / Saturation / Errors. 리소스 관점.
|
||
- **SLO burn-rate alert (Google SRE Workbook)**: error budget 소진 속도를 multi-window multi-burn-rate로 측정 (예: 1h 14.4× burn AND 5m 14.4× burn).
|
||
|
||
### Trace
|
||
|
||
- **W3C Trace Context (W3C TR)**: `traceparent` 헤더 — `version-trace-id-parent-id-trace-flags`. 128-bit trace-id, 64-bit span-id, vendor-neutral.
|
||
- **Micrometer Tracing**: Spring 진영의 facade. Brave(Zipkin) 또는 OpenTelemetry bridge로 backend 교체 가능.
|
||
- **B3 propagation (Zipkin legacy)**: `X-B3-TraceId`(64 or 128-bit), `X-B3-SpanId`, `X-B3-Sampled`. 일부 레거시 서비스 호환용.
|
||
- **Sampling**: head-based (요청 시점 결정, 저비용) vs tail-based (span 완료 후 결정, 고비용·고정밀). OTel Collector가 tail processor 제공.
|
||
|
||
### Runbook
|
||
|
||
- **Google SRE Workbook**: incident response·postmortem·error budget을 한 묶음으로 본다. runbook은 "on-call이 새벽 3시에 따라할 수 있어야" 한다.
|
||
- **PagerDuty Incident Response**: severity(SEV-1~5), incident commander, scribe, communication template을 표준화.
|
||
- **PagerDuty Runbook Automation (구 Rundeck)**: runbook을 코드/스크립트로 실행. drift 감소.
|
||
- **ITIL**: 광의의 service operation 프로세스 (incident / problem / change). runbook은 ITIL의 procedure에 해당.
|
||
- **Runbook-as-code (GitOps)**: markdown runbook을 git에 두고 alert payload에 URL을 박는다. `runbook://` 같은 내부 스킴은 ca-tmpl 관례.
|
||
|
||
## 한계 / 주의점
|
||
|
||
### Log
|
||
|
||
| 항목 | 한계 |
|
||
|------|------|
|
||
| ECS schema | Elastic이 사실상 owner — Loki/Datadog 채택은 부분적, **vendor lock-in 위험**. |
|
||
| OTel log signal | 2024년 기준 GA 진입했지만 ecosystem maturity는 metric/trace 대비 낮음. SDK·Collector 버전 호환에 주의. |
|
||
| SaaS 백엔드 (Loki/Datadog/Splunk) | 필드 매핑·인덱싱 정책이 제품마다 달라 schema drift 발생. 마이그레이션 비용 큼. |
|
||
| Masking | Logback `MaskingPatternLayout`은 정규식 기반 — false negative (놓침)·false positive (과다 마스킹) 모두 가능. 정책은 발신지에서. |
|
||
|
||
### Metric
|
||
|
||
| 항목 | 한계 |
|
||
|------|------|
|
||
| Naming drift | Micrometer dot.case → Prometheus exporter underscore 변환은 자동이지만, 대시보드·alert rule은 backend 표기를 직접 참조 → 코드와 alert 사이 표기 분리. |
|
||
| Cardinality | `userId`·`requestId`처럼 unbounded label을 metric에 박으면 시계열 폭증. trace/log로 보내야 함. |
|
||
| SLO burn-rate | 식이 직관적이지 않음. SLO 자체가 없는 단계에선 traffic-based threshold가 더 합리적. |
|
||
| Histogram | exponential histogram은 OTel·Prometheus 양쪽에서 채택 중이나 client/server 호환 매트릭스 확인 필요. |
|
||
|
||
### Trace
|
||
|
||
| 항목 | 한계 |
|
||
|------|------|
|
||
| Sampling | head-based 1% sampling은 rare-error 누락 위험. tail-based는 Collector 메모리·CPU 비용 큼. |
|
||
| Adaptive sampling | "에러는 100%, 정상은 N%" 같은 정책 — 검증·재현이 어렵고 비교 분석을 깨뜨릴 수 있음. |
|
||
| B3 non-호환 | B3 64-bit trace-id는 W3C 128-bit와 1:1 호환 안 됨. 게이트웨이에서 변환 정책 필요. |
|
||
| Backend lock-in | Datadog APM·New Relic의 auto-instrumentation은 강력하지만 OTel exporter로 동등하게 옮기기 어려움. |
|
||
| 비용 | full-trace 보관은 비싸다. 보존 기간·sampling rate가 곧 비용. |
|
||
|
||
### Runbook
|
||
|
||
| 항목 | 한계 |
|
||
|------|------|
|
||
| Drift | Confluence·Notion runbook은 코드와 따로 움직여 stale 되기 쉽다. |
|
||
| Automation lock-in | PagerDuty Runbook Automation·Rundeck 같은 도구는 ops 표면을 그 제품에 묶는다. |
|
||
| `runbook://` scheme | git markdown 링크는 repo 이동·이름 변경 시 link rot. CI에서 link check 필요. |
|
||
| 적용 한계 | runbook은 "이미 알려진 장애"에 강하다. novel incident에는 framework(SEV·comm·IC)만 도움이 되고 절차 자체는 비워둬야 한다. |
|
||
|
||
## Project Application
|
||
|
||
- [[wiki/projects/ca-tmpl/observability-log-metric-trace-runbook]] — ca-tmpl 의사결정 기록 (`verified` — foundation observability 토대 slice는 MDC snake_case 표준 + 응답-로그 상관 + 헤더 sanitization으로 코드 구현·로컬 검증됨; 4축 full 기능은 여전히 `documented-only`). 실제 구현 범위·검증 수준은 project 문서 참조.
|
||
- [[raw/project-notes/ca-skeleton-operational-contract]] — ca-tmpl 운영 계약 SSOT (§8 Structured Log, §6 Operational Error, §29 G-A).
|
||
- [[raw/branch-notes/feature-log-management-contract]] — JSON Logback + masking + trace 상관관계 계약.
|
||
- [[raw/branch-notes/feature-metrics-alerting-contract]] — Micrometer dot.case + SLO burn-rate alert 계약.
|
||
- [[raw/branch-notes/feature-distributed-tracing-contract]] — W3C tracecontext 전파 + sampling 계약.
|
||
- [[raw/branch-notes/feature-operational-runbook-contract]] — `runbook://` scheme · alert payload 연동 계약.
|
||
- [[raw/branch-notes/feature-operational-error-observability-foundation]] — error code · severity · 3 pillars 연계 토대.
|
||
|
||
## Claim-backed Knowledge
|
||
|
||
> 이 개념 문서의 핵심 설명은 raw source claim 으로 뒷받침되어야 한다.
|
||
> 공식 문서 claim, 회사 사례 claim, 내 프로젝트 decision 을 분리한다.
|
||
|
||
| Knowledge Point | Supporting Claims | Confidence | Notes |
|
||
|---|---|---|---|
|
||
| ECS는 `@timestamp`/`log.level`/`service.name`/`trace.id` 등 로그 필드명을 표준화한 공개 스키마다 | [[raw/official-docs/log-ecs-schema-elastic-official]] | `high` | 공식(Elastic) — 사실상 Elastic이 owner라 Loki/Datadog 채택은 부분적, vendor lock-in 위험 |
|
||
| OpenTelemetry는 log를 trace/metric과 동일 SDK 신호로 다루며 `TraceId`/`SpanId` correlation을 정의한다 | [[raw/official-docs/log-otel-log-data-model-spec]], [[raw/official-docs/metric-otel-metrics-data-model-spec]] | `high` | 공식 spec — log signal은 metric/trace 대비 ecosystem maturity 낮음 |
|
||
| Micrometer는 `dot.case` 이름 규칙을 쓰고 Prometheus exporter가 `_`로 변환한다 (`http.server.requests` → `http_server_requests_seconds_count`) | [[raw/official-docs/metric-micrometer-naming-convention-official]] | `high` | 공식 — 대시보드·alert rule은 backend 표기를 직접 참조해 코드/alert 표기 분리 발생 |
|
||
| W3C Trace Context `traceparent`는 128-bit trace-id·64-bit span-id의 vendor-neutral 표준이며 B3(64-bit)와 1:1 lossless 변환이 안 된다 | [[raw/official-docs/tracing-w3c-trace-context-spec]], [[raw/official-docs/tracing-b3-propagation-zipkin-spec]] | `high` | 공식 — hybrid 환경에서 게이트웨이 변환 정책 필요 |
|
||
| trace sampling은 head-based(저비용, rare-error 누락 위험) vs tail-based(고정밀, Collector 메모리/CPU 비용)의 trade-off다 | [[raw/official-docs/tracing-otel-sampling-tail-vs-head-spec]] | `high` | 공식 — full-trace 보관 비용이 곧 보존기간·sampling rate |
|
||
| SLO burn-rate alert는 error budget 소진 속도를 multi-window multi-burn-rate로 측정한다 | [[raw/official-docs/metric-google-sre-slo-burn-rate]] | `high` | 공식(Google SRE Workbook) — SLO 미합의 단계에선 traffic-based threshold가 더 운영 가능 |
|
||
| PagerDuty는 severity·incident commander·comm template로 incident response를 표준화하며 runbook은 "on-call이 새벽 3시에 따라할 수 있어야" 한다 | [[raw/official-docs/runbook-pagerduty-incident-response-doc]] | `high` | 공식 — runbook은 알려진 장애에 강하고 novel incident엔 framework만 유효 |
|
||
|
||
## 내가 설명할 수 있어야 하는 것
|
||
|
||
- Observability 3 pillars(log/metric/trace)의 공식 정의와 각 신호가 서로 대체 불가능한 이유는?
|
||
- 각 축의 공개 표준(ECS / OTel data model / Micrometer / W3C Trace Context / SLO burn-rate)은 무엇을 규정하는가?
|
||
- 어떤 상황에서는 특정 선택을 쓰면 안 되는가(SLO 미합의 시 burn-rate alert, unbounded label을 metric에 박기 등)?
|
||
- 공식 표준이 말하지 않는 부분(backend lock-in, schema drift, masking false negative/positive)은 무엇인가?
|
||
- Datadog APM vs OTel 같은 tech-blog 비교를 공식 best practice처럼 일반화하면 안 되는 지점은?
|
||
- 내 프로젝트에서는 어떤 branch decision(MDC snake_case 표준, W3C traceparent 채택, `runbook://` scheme 등)으로 연결됐는가?
|
||
- 이 개념을 코드/운영에서 검증하려면 무엇을 확인해야 하는가(MDC 키 일관성, 응답-로그 상관, 헤더 sanitization, alert 발화 등)?
|
||
|
||
## Interview Questions
|
||
|
||
- Observability **3 pillars**(log/metric/trace)를 정의하고, 각각이 다른 신호로 대체될 수 없는 이유는?
|
||
- **SLO burn-rate alert**의 원리와 단순 threshold alert 대비 장점은?
|
||
- **W3C tracecontext와 B3 propagation**의 차이, 그리고 hybrid 환경에서 변환 전략은?
|
||
- **trace sampling rate 1%**를 선택할 때의 근거와 rare-error 누락 위험을 어떻게 보완하는가?
|
||
- **log masking**은 어디서(발신/수신) 수행해야 하며, false negative를 어떻게 줄이는가?
|
||
- **runbook drift**(코드와 문서 불일치)를 방지하는 운영적 장치는?
|
||
|
||
## Do Not Overclaim
|
||
|
||
- "OpenTelemetry만 쓰면 vendor-neutral이다"라고 단정하지 말 것. instrument 표준은 중립이지만 **backend (Datadog/New Relic/Tempo/Jaeger)** 선택 시점에 다시 lock-in이 발생한다.
|
||
- "SLO burn-rate alert가 정답이다"라고 단정하지 말 것. SLO·error budget이 합의되지 않은 단계에선 traffic-based threshold (RPS·5xx rate)가 더 운영 가능하다.
|
||
- "structured logging만 하면 PII는 안전하다"고 단정하지 말 것. 필드 단위 마스킹 정책과 sink(Elastic/Loki/Datadog)별 접근 통제가 함께 있어야 한다.
|
||
- "B3과 W3C는 호환된다"고 단정하지 말 것. 64-bit B3 trace-id는 128-bit W3C로 lossless 변환되지 않는다.
|
||
- "runbook이 있으면 incident가 빨라진다"고 단정하지 말 것. drift된 runbook은 오히려 잘못된 행동을 유도한다.
|
||
|
||
## Sources
|
||
|
||
- [[raw/official-docs/log-ecs-schema-elastic-official]] — ECS schema 공식 정의.
|
||
- [[raw/official-docs/log-otel-log-data-model-spec]] — OpenTelemetry log data model spec.
|
||
- [[raw/official-docs/log-logback-mask-pattern-converter-official]] — Logback masking pattern 공식.
|
||
- [[raw/official-docs/metric-micrometer-naming-convention-official]] — Micrometer dot.case 이름 규칙.
|
||
- [[raw/official-docs/metric-otel-metrics-data-model-spec]] — OTel metrics data model spec.
|
||
- [[raw/official-docs/metric-google-sre-slo-burn-rate]] — Google SRE Workbook burn-rate alert.
|
||
- [[raw/official-docs/tracing-w3c-trace-context-spec]] — W3C Trace Context spec.
|
||
- [[raw/official-docs/tracing-b3-propagation-zipkin-spec]] — Zipkin B3 propagation spec.
|
||
- [[raw/official-docs/tracing-otel-sampling-tail-vs-head-spec]] — OTel sampling head/tail 비교.
|
||
- [[raw/official-docs/runbook-pagerduty-incident-response-doc]] — PagerDuty incident response 공식 문서.
|
||
- [[raw/company-tech-blogs/tracing-datadog-apm-vs-opentelemetry]] — Datadog APM vs OTel 비교 (tech blog 관점).
|
||
- [[raw/project-notes/ca-skeleton-operational-contract]] — ca-tmpl 운영 계약 canonical SSOT.
|