문제 실행 관측(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
168 lines
5.5 KiB
TypeScript
168 lines
5.5 KiB
TypeScript
import { describe, expect, it } from "vitest";
|
|
|
|
import {
|
|
DIAGNOSTIC_CONTEXT_ALLOWLIST,
|
|
DIAGNOSTIC_CONTEXT_CARDINALITY,
|
|
projectDiagnosticRecord,
|
|
statusGroup,
|
|
} from "../../src/contracts/diagnostics.ts";
|
|
import {
|
|
TELEMETRY_ATTRIBUTE_ALLOWLIST,
|
|
projectTelemetryEvent,
|
|
} from "../../src/contracts/telemetry.ts";
|
|
|
|
describe("observability cardinality policy", () => {
|
|
it("classifies every diagnostic context key exactly once", () => {
|
|
expect(Object.keys(DIAGNOSTIC_CONTEXT_CARDINALITY).sort()).toEqual(
|
|
[...DIAGNOSTIC_CONTEXT_ALLOWLIST].sort(),
|
|
);
|
|
expect(DIAGNOSTIC_CONTEXT_CARDINALITY.correlation_id).toBe("request");
|
|
expect(DIAGNOSTIC_CONTEXT_CARDINALITY.route_id).toBe("topology");
|
|
expect(DIAGNOSTIC_CONTEXT_CARDINALITY.operation_id).toBe("topology");
|
|
expect(DIAGNOSTIC_CONTEXT_CARDINALITY.duration_bucket).toBe("bounded");
|
|
});
|
|
|
|
it("keeps request-cardinality keys out of telemetry dimensions", () => {
|
|
for (const key of TELEMETRY_ATTRIBUTE_ALLOWLIST) {
|
|
expect(DIAGNOSTIC_CONTEXT_CARDINALITY[key]).not.toBe("request");
|
|
}
|
|
expect(TELEMETRY_ATTRIBUTE_ALLOWLIST).not.toContain("correlation_id");
|
|
});
|
|
|
|
it("rejects free-form values for bounded diagnostic dimensions", () => {
|
|
expect(
|
|
projectDiagnosticRecord({
|
|
level: "info",
|
|
eventId: "http.request.completed",
|
|
context: {
|
|
outcome: "customer-123",
|
|
http_status_group: "599",
|
|
attempt_count_bucket: "37",
|
|
duration_bucket: "12345ms",
|
|
},
|
|
}),
|
|
).toEqual({ success: false, reason: "invalid-context" });
|
|
});
|
|
|
|
// 1103/03-05. The effect certainty is a closed five-value dimension in
|
|
// both sinks.
|
|
it.each(["NOT_APPLICABLE", "NOT_STARTED", "NOT_APPLIED", "APPLIED_CONFIRMED", "MAYBE_APPLIED"])(
|
|
"admits effect_certainty %s in diagnostics and failure telemetry",
|
|
(effect) => {
|
|
expect(DIAGNOSTIC_CONTEXT_CARDINALITY.effect_certainty).toBe("bounded");
|
|
expect(
|
|
projectDiagnosticRecord({
|
|
level: "warn",
|
|
eventId: "http.request.completed",
|
|
context: { effect_certainty: effect },
|
|
}).success,
|
|
).toBe(true);
|
|
expect(
|
|
projectTelemetryEvent("api.request.failed", {
|
|
error_kind: "PROBLEM",
|
|
http_status_group: "4xx",
|
|
attempt_count_bucket: "1",
|
|
route_id: "TEST_ROUTE",
|
|
effect_certainty: effect,
|
|
}).success,
|
|
).toBe(true);
|
|
},
|
|
);
|
|
|
|
it.each(["maybe", "UNKNOWN", "MAYBE_APPLIED_ON_RETRY"])(
|
|
"rejects effect_certainty %j in both sinks",
|
|
(effect) => {
|
|
expect(
|
|
projectDiagnosticRecord({
|
|
level: "warn",
|
|
eventId: "http.request.completed",
|
|
context: { effect_certainty: effect },
|
|
}),
|
|
).toEqual({ success: false, reason: "invalid-context" });
|
|
expect(
|
|
projectTelemetryEvent("api.request.failed", {
|
|
error_kind: "PROBLEM",
|
|
http_status_group: "4xx",
|
|
attempt_count_bucket: "1",
|
|
route_id: "TEST_ROUTE",
|
|
effect_certainty: effect,
|
|
}),
|
|
).toEqual({ success: false, reason: "invalid-attribute-value" });
|
|
},
|
|
);
|
|
|
|
it("allows request correlation only in bounded diagnostics evidence", () => {
|
|
const projected = projectDiagnosticRecord({
|
|
level: "info",
|
|
eventId: "http.request.completed",
|
|
context: {
|
|
correlation_id: "request-a1b2c3",
|
|
outcome: "success",
|
|
http_status_group: "2xx",
|
|
attempt_count_bucket: "1",
|
|
duration_bucket: "lt100ms",
|
|
},
|
|
});
|
|
|
|
expect(projected.success).toBe(true);
|
|
});
|
|
});
|
|
|
|
/**
|
|
* R-7.5. One operationId grammar. The V3 composition accepts camelCase ids of
|
|
* up to 128 characters; a failure for such an operation must not be dropped
|
|
* as an invalid telemetry attribute, and diagnostics apply the same rule.
|
|
*/
|
|
describe("shared operationId and status-group grammar", () => {
|
|
function telemetryFailure(operationId: string, httpStatusGroup = "5xx") {
|
|
return projectTelemetryEvent("api.request.failed", {
|
|
error_kind: "SERVER_FAILURE",
|
|
http_status_group: httpStatusGroup,
|
|
attempt_count_bucket: "1",
|
|
route_id: "TEST_ROUTE",
|
|
operation_id: operationId,
|
|
});
|
|
}
|
|
|
|
function diagnosticCompletion(operationId: string, httpStatusGroup = "5xx") {
|
|
return projectDiagnosticRecord({
|
|
level: "warn",
|
|
eventId: "http.request.completed",
|
|
context: { operation_id: operationId, http_status_group: httpStatusGroup },
|
|
});
|
|
}
|
|
|
|
it.each([
|
|
"getUser",
|
|
"LIST_ORDER_ITEMS",
|
|
"users.v1.get-item",
|
|
`a${"b".repeat(127)}`,
|
|
])("keeps both observability records for operationId %s", (operationId) => {
|
|
expect(telemetryFailure(operationId).success).toBe(true);
|
|
expect(diagnosticCompletion(operationId).success).toBe(true);
|
|
});
|
|
|
|
it.each(["", "1getUser", "get user", "get:user", "get/user", `a${"b".repeat(128)}`])(
|
|
"rejects operationId %j in both sinks",
|
|
(operationId) => {
|
|
expect(telemetryFailure(operationId)).toEqual({
|
|
success: false,
|
|
reason: "invalid-attribute-value",
|
|
});
|
|
expect(diagnosticCompletion(operationId)).toEqual({
|
|
success: false,
|
|
reason: "invalid-context",
|
|
});
|
|
},
|
|
);
|
|
|
|
it.each([undefined, 0, 101, 204, 302, 404, 503, 999])(
|
|
"accepts the status group statusGroup(%s) produces in both sinks",
|
|
(status) => {
|
|
const group = statusGroup(status);
|
|
expect(telemetryFailure("GET_USER", group).success).toBe(true);
|
|
expect(diagnosticCompletion("GET_USER", group).success).toBe(true);
|
|
},
|
|
);
|
|
});
|