The V3 composition admits operationIds with /^[A-Za-z][A-Za-z0-9_.-]{0,127}$/
(camelCase, up to 128 chars), but telemetry validated operation_id with
/^[A-Z][A-Z0-9_]{0,63}$/, so api.request.failed for a V3 operation such as
`getUser` failed projection as invalid-attribute-value and was dropped.
Diagnostics used the free-form 64-char safe-string pattern instead.
http_status_group had the same split: statusGroup() emits [0-9]xx|none and
diagnostics accepted that, but telemetry only [1-5]xx|none, so a failure
with status 0 or >= 600 was dropped too.
- New src/contracts/operation-id.ts holds isOperationId (the V3 grammar);
the V3 composition, telemetry operation_id and diagnostics operation_id
all use it. The REST v2 and browser RPC registry grammars are subsets.
- isHttpStatusGroup sits next to statusGroup() in diagnostics.ts and is used
by both diagnostics and telemetry.
Other telemetry attribute policies (route_id, error_kind, redaction) are
unchanged.
RED: "shared operationId and status-group grammar" failed before the fix:
getUser, users.v1.get-item and a 128-char id were rejected by telemetry;
"1getUser", "get:user", "get/user" were accepted by diagnostics; and the
statusGroup(0)/statusGroup(999) groups were rejected by telemetry.
Gates: check:architecture, check:types:app/test/node, lint, test:component,
test:runtime-schema, test:contract pass; test:unit passes except the
environment-dependent removal-fixture.test.ts (needs generated
artifacts/release files; unrelated). check:diagnostics,
check:registries:structure, check:types:web-worker/service-worker and
tests/integration, tests/platform/telemetry also pass.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
121 lines
4.0 KiB
TypeScript
121 lines
4.0 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" });
|
|
});
|
|
|
|
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_REFERENCE_RESOURCES",
|
|
"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);
|
|
},
|
|
);
|
|
});
|