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:
@@ -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,
|
||||
|
||||
Reference in New Issue
Block a user