feat(diagnostics): 결과 불명 쓰기의 effect와 원인을 진단에 싣는다

문제
실행 관측(HttpExecutionObservation)에는 effect가 있지만 조립 루트 projector는
진단에도 텔레메트리에도 싣지 않는다. 진단 허용 키에 effect가 없고 status는
묶음(4xx)만 남는다. 그래서 진단 버퍼에서 결과 불명과 적용 안 됨, 처리 중
409와 업무 409, 503 IDEMPOTENCY_UNAVAILABLE 재전송 소진이 같은 줄이 된다.
텔레메트리로는 결과 불명 쓰기의 비율을 셀 수 없다. 03-01이 고쳐져도 업무
거절은 선언 전까지 결과 불명이라 이 구분이 필요하다.

고른 방법
- effect_certainty 키: 진단·텔레메트리(api.request.failed 선택 속성) 모두
  HttpEffectCertainty 다섯 값만 받는 닫힌 value policy(isEffectCertainty)를
  쓴다. cardinality는 bounded. projector가 두 sink에 싣는다.
- 결과 불명 원인: Envelope 명령에서 표가 MAYBE_APPLIED를 줄 때 닫힌
  UnknownEffectReason을 진단 reason으로 싣는다. IN_FLIGHT(409 처리 중),
  IDEMPOTENCY_UNAVAILABLE, COMPLETION_UNKNOWN, RECOVERY_REQUIRED,
  SERVER_TIMEOUT(503 REQUEST_TIMEOUT), STAGE_UNKNOWN(단계를 모르는 400·409·
  422). 텔레메트리에는 싣지 않는다(VD-07: reason은 진단 전용).
- VD-07 5-1의 projector 키 목록과 reason 값 목록을 고쳤다. 남아 있던
  "effect_certainty는 필요해지면 더한다" 문장은 지웠다.

버린 대안
- 백엔드 error.code 원문을 진단에 싣기: cardinality 결정(1101 README 14.6)이
  먼저다. 닫힌 원인 집합이면 그 결정과 무관하다.
- 원인도 텔레메트리에: 텔레메트리 reason은 전달 실패용 닫힌 집합이라 뜻이
  섞인다. 비율은 effect_certainty로 센다.

위험·한계
- Envelope가 아닌 operation의 MAYBE_APPLIED는 원인 없이 effect만 남는다.
  응답을 잃은 경우는 outcome(TRANSPORT_FAILURE)이 원인을 보인다.
- 텔레메트리 수집기가 속성 목록을 고정해 두었다면 새 선택 속성을 받도록
  맞춰야 한다.

검증
- RED: envelope 진단 9행(effect·reason), observability 1건, cardinality
  8건 실패.
- GREEN: 처리 중 409는 reason IN_FLIGHT, 업무 409는 STAGE_UNKNOWN, 둘 다
  effect_certainty MAYBE_APPLIED. 진단 투영이 모두 통과한다.
  tests/unit·integration·component·features·contract·runtime-schema·platform
  282파일 중 281파일 통과. 남은 1건은 provider-guardian-transaction의 inotify
  한도(ENOSPC)로 이 변경과 무관하다.
- check:diagnostics, check:types, lint, verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-05
This commit is contained in:
DongHyeonka
2026-11-04 20:54:24 +09:00
parent 631ce339b9
commit 39c1de2e5e
9 changed files with 179 additions and 30 deletions
@@ -43,21 +43,27 @@ vendor 결정 전에는 안전한 기본값이 아니다.
`createHttpObservationProjector`가 유일한 projection authority다. observation은
arbitrary context map이 아니며 projector는 `route_id`, `operation_id`,
`operation`, `outcome`, `error_kind`, `http_status_group`,
`attempt_count_bucket`, `duration_bucket`만 사용한다. diagnostics에만
`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`으로 더한다. 값은 둘 중 하나다. 기능 패키지의
남기면 diagnostics에만 `reason`으로 더한다. 값은 넷 중 하나다. 기능 패키지의
`classifyProblem`이 throw하거나 집합 밖 값을 돌려줘 효과를 `MAYBE_APPLIED`로
떨어뜨린 `CLASSIFIER_FAILED`(03-05), 그리고 전송 전에 거절한 요청의 원인
떨어뜨린 `CLASSIFIER_FAILED`(03-05), 전송 전에 거절한 요청의 원인
`HttpRequestRejectionReason`(입력 검증 실패, 요청 조립 실패, 최종 불변식 실패,
미설치 계약 `CONTRACT_NOT_INSTALLED`, 03-02)이다. 미설치 계약은 실행기를
미설치 계약 `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로 나가지 않는다. effect certainty가 운영상 필요해지면 `effect_certainty`
key와 닫힌 value policy를 contract·fixture·이 ADR에 동시에 추가한 뒤에만
전달한다.
sink로 나가지 않는다.
5-2. caller cancellation과 scope fence는 API failure가 아니다. diagnostics는 한
번 남기고 `api.request.failed`는 발행하지 않는다. 자격증명이 없어 한 번도
보내지 않은 `UNAUTHENTICATED`(응답 status 없음)도 같다(03-07,