Files
clean-architecture-frontend…/docs/adr/VD-07-diagnostics-and-telemetry-exporter.md
DongHyeonka 75fad73a7d docs(records): 기록·설계서·결정 기록 67개에 한국어 머리 블록을 단다
문제: 옮긴 기록은 지금 동작을 설명하는지, 상태가 무엇인지, 지금
정본이 어디인지 알 길이 없다. 설계서·계획서 27개와 docs/architecture
목표 설계 16개에는 상태 칸이 없고, VD는 「상태: Accepted」 같은 영어
값을 쓴다.

고른 방법: docs-system.md 4절 형식으로 맨 위에 머리 블록을 달고 본문은
한 글자도 고치지 않는다. 상태는 기계 변환이다.
- 설계서: Accepted·확정·정본·설계 완료 → 채택, 상태 줄이 없으면
  확인 안 함 (채택 4, 확인 안 함 21)
- 계획서: 체크 상자가 모두 표시됐으면 끝남, 아니면 확인 안 함. SPEC.md는
  같은 폴더 plan.md와 같은 근거(0.2.0으로 끝난 라운드)로 끝남 (끝남 5,
  확인 안 함 14. 이미 블록이 있던 5개는 그대로)
- 결정 기록: Accepted → 채택, 날짜가 붙은 뒤늦은 보완 메모가 본문에
  있으면 채택(보완) (채택 14, 채택(보완) 9). 프론트 VD는 처음부터
  한국어로 썼고 번역하지 않으므로 둘째 줄은 「원문이다」 문구다.
- 작성일: 파일 이름 날짜 → 본문 날짜 줄(VD는 `결정일:`) → git 첫 추가일.

위험: VD-09·11·13은 git으로 보면 결정 뒤 본문이 그 자리에서
고쳐졌지만 본문에 날짜 표시가 없어 기계 규칙대로 채택으로 두었다.
보완으로 올릴지는 사람이 정한다. 「현재 정본」은 지금 있는 살아 있는
문서나 코드 경로만 쓴다.

검증: 블록과 그 뒤 빈 줄 하나를 빼면 72개 모두 `git show HEAD:`와 바이트가
같다. 뒤 커밋의 문서 검사 head 규칙으로 돌려 문제 0건.
2026-11-08 17:25:41 +09:00

11 KiB

결정 기록 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 채택(보완)
  • 작성일: 2026-07-26
  • 요약: 운영 진단은 DiagnosticsPort, 의미 이벤트는 TelemetryPort로 나누고 닫힌 registry와 값 정책을 통과한 값만 보낸다는 결정이다.
  • 현재 정본: src/adapters/diagnostics/, src/adapters/telemetry/

VD-07: Diagnostics와 telemetry exporter 경계

  • 상태: Accepted
  • 결정일: 2026-07-26
  • 적용 브랜치: feature-frontend-diagnostics-telemetry-runtime
  • 재검토: 실제 운영 sink, consent가 필요한 analytics 또는 분산 tracing provider가 선정될 때

배경

기존 telemetry registry와 best-effort HTTP queue는 있었지만 운영 진단 record와 semantic event의 책임이 하나의 telemetry port에 섞여 있었다. boot, HTTP, cache, storage, route와 release failure의 선언도 실제 production producer와 완전히 연결되지 않았다. 이 상태에서는 retry attempt마다 같은 사건을 발행하거나 raw URL, query, request body와 오류 객체가 queue에 들어갈 위험이 있다.

반면 skeleton 단계에는 실제 관측 vendor, endpoint의 운영 보안 정책, analytics consent와 보존 기간이 결정되지 않았다. 특정 SDK를 기본 번들에 설치하는 것은 vendor 결정 전에는 안전한 기본값이 아니다.

결정

  1. level 기반 운영 진단은 DiagnosticsPort, registry 기반 semantic event는 TelemetryPort로 분리한다. application은 두 port의 concrete adapter나 exporter SDK를 알지 못한다.
  2. diagnostics의 level, event ID와 context key는 닫힌 registry/allowlist다. telemetry도 event별 required/optional attribute와 value policy를 적용한다. 등록되지 않은 event·context·고카디널리티 값은 전송하지 않는다.
  3. 기본 diagnostics adapter는 bounded in-memory evidence이고 telemetry는 설정이 없으면 true no-op이다. endpoint가 있을 때만 bounded oldest-drop queue와 best-effort HTTP sink를 사용한다.
  4. raw path/URL/query/body/response/storage value, credential, cookie, email, stack과 오류 객체 전체는 context에 넣지 않는다. route ID, operation ID, correlation ID, release ID, error kind, status/attempt/duration bucket만 허용한다.
  5. HTTP logical execution은 success, retry recovery, terminal failure 또는 abort마다 http.request.completed diagnostics를 정확히 한 번 남긴다. api.request.failed telemetry는 retry가 끝난 terminal non-abort failure에만 정확히 한 번 발행한다. 5-1. V2 client와 V3 contract executor는 각각 자신의 logical execution에 대해 이 규칙을 만족한다. V3에서는 execution site가 HttpExecutionObservation typed record 하나만 만들고, composition root의 createHttpObservationProjector가 유일한 projection authority다. observation은 arbitrary context map이 아니며 projector는 route_id, operation_id, operation, outcome, error_kind, http_status_group, attempt_count_bucket, duration_bucket, effect_certainty만 사용한다. effect_certainty는 V3 HttpEffectCertainty 다섯 값(NOT_APPLICABLE, NOT_STARTED, NOT_APPLIED, APPLIED_CONFIRMED, MAYBE_APPLIED)만 받는 닫힌 value policy(isEffectCertainty)를 두 sink가 함께 쓴다. 결과 불명 쓰기의 수를 세기 위해서다(1103/03-05). diagnostics에만 correlation_id(서버가 돌려준 x-correlation-id, 없으면 실행이 보낸 요청 ID)를 더한다. telemetry에는 넣지 않는다(03-03, createHttpObservationProjector). 실행이 observation의 diagnosticReason(닫힌 집합 HttpDiagnosticReason)을 남기면 diagnostics에만 reason으로 더한다. 값은 넷 중 하나다. 기능 패키지의 classifyProblem이 throw하거나 집합 밖 값을 돌려줘 효과를 MAYBE_APPLIED로 떨어뜨린 CLASSIFIER_FAILED(03-05), 전송 전에 거절한 요청의 원인 HttpRequestRejectionReason(입력 검증 실패, 요청 조립 실패, 최종 불변식 실패, 미설치 계약 CONTRACT_NOT_INSTALLED, 03-02), Envelope 백엔드가 멱등 키를 거절한 IdempotencyRefusalReason, 그리고 Envelope 명령의 결과를 모르게 된 원인 UnknownEffectReason(IN_FLIGHT, IDEMPOTENCY_UNAVAILABLE, COMPLETION_UNKNOWN, RECOVERY_REQUIRED, SERVER_TIMEOUT, STAGE_UNKNOWN, 1103/03-05)이다. 백엔드 error.code 원문은 싣지 않는다. 미설치 계약은 실행기를 거치지 않으므로 조립 지점이 같은 projector로 관측 1건을 직접 남긴다. raw attempt count, duration, status, URL, intent, key, input identity와 내부 terminalReason은 sink로 나가지 않는다. 5-2. caller cancellation과 scope fence는 API failure가 아니다. diagnostics는 한 번 남기고 api.request.failed는 발행하지 않는다. 자격증명이 없어 한 번도 보내지 않은 UNAUTHENTICATED(응답 status 없음)도 같다(03-07, src/bootstrap/runtime-adapters.ts isTerminalNonAbortFailure). 5-3. routeId는 installed operation-executor 경계의 필수 입력이다. feature gateway가 소유한 low-cardinality route identity를 URL에서 재구성하지 않는다.
  6. app.boot.failed, ui.render.failed, release.mismatch.detected, telemetry.delivery.dropped를 production path에 연결한다. cache와 storage 실패는 diagnostics로 기록하되 raw key/value를 기록하지 않는다.
  7. queue full, invalid event/context, serialization과 sink failure는 제한된 reason bucket으로 집계한다. drop observer의 failure는 다시 telemetry를 발행하지 않는 nonrecursive 경계다. 7-1. telemetry adapter lifecycle은 ACTIVE | DISPOSED 둘뿐이다. dispose()는 한 번만 전이하고 pagehide listener 제거, queue 비우기, scheduled callback generation 무효화, in-flight sink AbortController abort를 모두 수행한다. dispose 뒤 emit()은 no-op이고 새 flush는 스케줄되지 않으며, abort를 무시한 sink가 늦게 settle해도 post-dispose delivery state를 갱신하거나 재스케줄하지 못한다. 종료 중 drop telemetry를 재귀적으로 발행하지 않는다. 7-2. flush()는 active delivery promise를 join한다. 이미 진행 중인 flush가 있으면 같은 promise를 반환하므로 await flush()는 실제 settle을 뜻한다. 7-3. runtime infrastructure.dispose()는 diagnostics/state dependency를 파괴하기 전에 telemetry.dispose()를 먼저 호출한다. 7-4. queue/entry capacity는 construction-time 계약이다. Number.isSafeInteger가 아니거나 1 미만이거나 문서화된 ceiling(각각 MAX_TELEMETRY_QUEUE, MAX_DIAGNOSTIC_ENTRIES = 10,000)을 넘으면 TypeError로 거절한다. NaN/Infinity가 조용히 eviction을 비활성화하는 경로를 남기지 않는다. 7-5. (2026-09-25) 두 telemetry port는 collector 하나로 보낸다 (src/adapters/telemetry/telemetry-collector.ts). collector는 본문을 60KiB 아래로 나누고, 진행 중인 keepalive 본문 합이 64KiB를 넘으면 그 부분은 keepalive 없이 보낸다(03-05). 조합 루트가 release manifest의 buildId·releaseId를 넘기면 모든 이벤트에 build_id·release_id를 붙인다(13-11, src/bootstrap/runtime-adapters.ts).
  8. diagnostics와 telemetry failure는 제품 흐름, HTTP 결과, route transition, storage/cache fallback과 React error surface를 바꾸지 않는다.
  9. mount 전 bootstrap failure는 안전한 build/config/error kind만 별도 evidence로 만들며 untrusted error message, stack과 support 입력을 serialize하지 않는다.
  10. 실제 error reporter, RUM, analytics나 tracing SDK는 같은 port 뒤의 외부 adapter로만 추가한다. SDK type과 event API를 application/feature/presentation public contract에 노출하지 않는다.

실행 경계

route/application/HTTP/cache/storage/bootstrap
  -> typed DiagnosticsPort 또는 TelemetryPort
  -> registry + allowlist + value policy
  -> bounded memory/no-op 또는 best-effort HTTP adapter
  -> 프로젝트가 선택한 외부 sink
  • diagnostics contract: src/contracts/diagnostics.ts
  • telemetry contract: src/contracts/telemetry.ts
  • application ports: src/application/ports/diagnostics-port.ts, telemetry-port.ts
  • bounded diagnostics: src/adapters/diagnostics/bounded-diagnostics.ts
  • best-effort telemetry: src/adapters/telemetry/best-effort-telemetry.ts
  • composition: src/bootstrap/runtime-adapters.ts

검증

  • check:diagnostics는 모든 registry event에 production producer가 있는지와 source의 direct console/sensitive context 우회를 검사한다.
  • negative source fixture는 direct console, unknown event와 raw context를 실제로 거절하며 TypeScript fixture는 잘못된 level/event ID를 거절한다.
  • unit test는 allowlist, hostile/circular error, bounded diagnostics, no-op, queue full, sink/observer failure와 pre-mount boot evidence를 검증한다.
  • HTTP integration은 success, retry recovery, terminal failure와 abort의 producer 횟수, route/operation/correlation context와 요청 값 비노출을 검증한다.
  • tests/integration/http-execution-v3-observability.test.ts는 V3 terminal outcome이 실제로 closed allowlist를 통과하는지, terminal non-abort failure가 api.request.failed를 정확히 한 번 발행하는지, cancellation/scope fence가 발행하지 않는지, feature route ID가 executor 경계까지 보존되는지, sink 예외가 HTTP 결과를 바꾸지 못하는지를 검증한다.
  • cache/storage/release/application/runtime test는 각 production wiring과 diagnostics failure isolation을 검증한다.

한계와 재검토 조건

기본 adapter는 운영 log 검색, source map 연계, session replay, distributed span, analytics consent, sampling budget과 장기 보존을 제공하지 않는다. 실제 sink를 선정할 때 데이터 처리 지역, 보존 기간, consent, CSP, source map 접근 제어, sampling과 비용 상한을 별도 결정해야 한다.

Rollback

telemetry exporter는 runtime 설정을 끄거나 adapter wiring을 noOpTelemetry로 바꾸어 독립적으로 제거할 수 있다. 이때도 DiagnosticsPort, registry, redaction/value policy, producer-count와 negative fixture는 유지한다. 외부 SDK 문제로 application producer와 안전 계약을 함께 되돌리지 않는다.