lyon
1136 lines
54 KiB
TypeScript
1136 lines
54 KiB
TypeScript
// SPEC: PJ2026-01060505 Workbench Performance draft-2026-06-17-p0
|
|
// Records low-cardinality Cloud API backend performance metrics and Server-Timing phases.
|
|
|
|
import { AsyncLocalStorage } from "node:async_hooks";
|
|
|
|
const REQUEST_BUCKETS_SECONDS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60];
|
|
const PHASE_BUCKETS_SECONDS = [0.001, 0.0025, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30];
|
|
const UPSTREAM_BUCKETS_SECONDS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60, 120];
|
|
const PROJECTION_LAG_EVENT_BUCKETS = [0, 1, 5, 10, 50, 100, 500, 1000, 2000, 5000, 10000];
|
|
const PROJECTION_LAG_SECONDS_BUCKETS = [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60, 300, 900, 1800, 3600];
|
|
const WORKBENCH_TURN_DURATION_BUCKETS_SECONDS = [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60];
|
|
const WORKBENCH_TURN_RESPONSE_BYTES_BUCKETS = [512, 1024, 4096, 16384, 65536, 262144, 1048576, 4194304];
|
|
const WORKBENCH_CACHE_OPERATION_BUCKETS_SECONDS = [0.001, 0.0025, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];
|
|
const WORKBENCH_CACHE_PAYLOAD_BYTES_BUCKETS = [512, 1024, 4096, 16384, 65536, 262144, 1048576, 4194304];
|
|
const AGENTRUN_RESULT_BUCKETS_SECONDS = [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60, 120];
|
|
const AGENTRUN_RESULT_EVENTS_BUCKETS = [0, 50, 100, 500, 1000, 2000, 5000, 10000];
|
|
const AGENTRUN_RESULT_PAGES_BUCKETS = [0, 1, 2, 5, 10, 20, 50, 100];
|
|
const PROJECTOR_BATCH_BUCKETS_SECONDS = [0.001, 0.0025, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60];
|
|
const MAX_SERVER_TIMING_ENTRIES = 8;
|
|
const DEFAULT_BACKEND_EVIDENCE_WINDOW = "15m";
|
|
const BACKEND_EVIDENCE_WINDOWS = {
|
|
"5m": { id: "5m", label: "最近 5 分钟", milliseconds: 5 * 60 * 1000 },
|
|
"15m": { id: "15m", label: "最近 15 分钟", milliseconds: 15 * 60 * 1000 },
|
|
"1h": { id: "1h", label: "最近 1 小时", milliseconds: 60 * 60 * 1000 },
|
|
"6h": { id: "6h", label: "最近 6 小时", milliseconds: 6 * 60 * 60 * 1000 },
|
|
"24h": { id: "24h", label: "最近 24 小时", milliseconds: 24 * 60 * 60 * 1000 },
|
|
all: { id: "all", label: "全部累计", milliseconds: null }
|
|
} as const;
|
|
|
|
const backendPerformanceStorage = new AsyncLocalStorage();
|
|
|
|
interface HistogramSeries {
|
|
labels: Record<string, string>;
|
|
buckets: number[];
|
|
sum: number;
|
|
count: number;
|
|
}
|
|
|
|
interface CounterSeries {
|
|
labels: Record<string, string>;
|
|
value: number;
|
|
}
|
|
|
|
interface GaugeSeries {
|
|
labels: Record<string, string>;
|
|
value: number;
|
|
}
|
|
|
|
interface BackendPerformanceStoreOptions {
|
|
env?: Record<string, unknown>;
|
|
maxSeries?: number;
|
|
maxEvidenceSamples?: number;
|
|
}
|
|
|
|
interface BackendPerformanceContextInput {
|
|
route: string;
|
|
method: string;
|
|
}
|
|
|
|
interface BackendPhaseInput {
|
|
phase: string;
|
|
durationMs: number;
|
|
outcome?: string;
|
|
}
|
|
|
|
interface BackendUpstreamInput {
|
|
component: string;
|
|
operation?: string;
|
|
route: string;
|
|
method: string;
|
|
statusClass?: string;
|
|
outcome?: string;
|
|
durationMs: number;
|
|
}
|
|
|
|
interface WorkbenchProjectionInput {
|
|
sourceLatestSeq?: unknown;
|
|
lastProjectedSeq?: unknown;
|
|
sourceLatestEventAt?: unknown;
|
|
projectedLatestEventAt?: unknown;
|
|
terminalSourceAt?: unknown;
|
|
terminalProjectedAt?: unknown;
|
|
status?: unknown;
|
|
reason?: unknown;
|
|
projectionStatus?: unknown;
|
|
source?: unknown;
|
|
}
|
|
|
|
interface WorkbenchTurnReadInput {
|
|
route: string;
|
|
status?: unknown;
|
|
degradedReason?: unknown;
|
|
durationMs: number;
|
|
responseBytes?: unknown;
|
|
timedOut?: boolean;
|
|
}
|
|
|
|
interface WorkbenchCacheInput {
|
|
route: string;
|
|
cacheKeyClass?: unknown;
|
|
cacheStatus?: unknown;
|
|
operation?: unknown;
|
|
durationMs?: unknown;
|
|
payloadBytes?: unknown;
|
|
cacheAgeMs?: unknown;
|
|
dbQueryAvoided?: unknown;
|
|
freshnessSloMs?: unknown;
|
|
projectionSeq?: unknown;
|
|
}
|
|
|
|
interface AgentRunResultInput {
|
|
durationMs?: unknown;
|
|
eventsScanned?: unknown;
|
|
pagesScanned?: unknown;
|
|
eventCount?: unknown;
|
|
status?: unknown;
|
|
budget?: unknown;
|
|
timedOut?: boolean;
|
|
}
|
|
|
|
interface WorkbenchProjectorBatchInput {
|
|
phase: string;
|
|
status?: unknown;
|
|
durationMs: number;
|
|
}
|
|
|
|
interface WorkbenchProjectorCounterInput {
|
|
status?: unknown;
|
|
reason?: unknown;
|
|
eventKind?: unknown;
|
|
count?: unknown;
|
|
}
|
|
|
|
interface BackendRequestSample {
|
|
atMs: number;
|
|
route: string;
|
|
method: string;
|
|
statusClass: string;
|
|
outcome: string;
|
|
durationSeconds: number;
|
|
responseBytes: number | null;
|
|
phases: Array<{ phase: string; outcome: string; durationSeconds: number }>;
|
|
}
|
|
|
|
interface WorkbenchCacheEvidenceSample {
|
|
atMs: number;
|
|
route: string;
|
|
cacheKeyClass: string;
|
|
cacheStatus: string;
|
|
operation: string;
|
|
durationSeconds: number | null;
|
|
payloadBytes: number | null;
|
|
cacheAgeMs: number | null;
|
|
dbQueryAvoided: boolean;
|
|
freshnessSloMs: number | null;
|
|
projectionSeq: number | null;
|
|
}
|
|
|
|
export function createBackendPerformanceStore(options: BackendPerformanceStoreOptions = {}) {
|
|
const env = options.env ?? process.env;
|
|
const maxSeries = parsePositiveInteger(env.HWLAB_BACKEND_PERFORMANCE_MAX_SERIES, options.maxSeries ?? 320);
|
|
const maxEvidenceSamples = parsePositiveInteger(env.HWLAB_BACKEND_PERFORMANCE_MAX_EVIDENCE_SAMPLES, options.maxEvidenceSamples ?? 5000);
|
|
const requestDurationSeries = new Map<string, HistogramSeries>();
|
|
const requestTotalSeries = new Map<string, CounterSeries>();
|
|
const requestPhaseSeries = new Map<string, HistogramSeries>();
|
|
const upstreamSeries = new Map<string, HistogramSeries>();
|
|
const droppedSeries = new Map<string, CounterSeries>();
|
|
const projectionLagEventsSeries = new Map<string, HistogramSeries>();
|
|
const projectionLagSecondsSeries = new Map<string, HistogramSeries>();
|
|
const projectionStuckGaugeSeries = new Map<string, GaugeSeries>();
|
|
const projectionCursorAdvanceSeries = new Map<string, CounterSeries>();
|
|
const terminalProjectionDelaySeries = new Map<string, HistogramSeries>();
|
|
const turnGetDurationSeries = new Map<string, HistogramSeries>();
|
|
const turnGetTimeoutSeries = new Map<string, CounterSeries>();
|
|
const turnGetResponseBytesSeries = new Map<string, HistogramSeries>();
|
|
const cacheRequestSeries = new Map<string, CounterSeries>();
|
|
const cacheOperationDurationSeries = new Map<string, HistogramSeries>();
|
|
const cachePayloadBytesSeries = new Map<string, HistogramSeries>();
|
|
const cacheStaleSeries = new Map<string, CounterSeries>();
|
|
const cacheUnavailableSeries = new Map<string, CounterSeries>();
|
|
const dbQueryAvoidedSeries = new Map<string, CounterSeries>();
|
|
const agentRunResultDurationSeries = new Map<string, HistogramSeries>();
|
|
const agentRunResultPagesSeries = new Map<string, HistogramSeries>();
|
|
const agentRunResultEventsSeries = new Map<string, HistogramSeries>();
|
|
const agentRunResultTimeoutSeries = new Map<string, CounterSeries>();
|
|
const projectorBatchDurationSeries = new Map<string, HistogramSeries>();
|
|
const projectorCandidatesSeries = new Map<string, CounterSeries>();
|
|
const projectorEventsProcessedSeries = new Map<string, CounterSeries>();
|
|
const projectorErrorsSeries = new Map<string, CounterSeries>();
|
|
const projectorLastSuccessSeries = new Map<string, GaugeSeries>();
|
|
const requestSamples: BackendRequestSample[] = [];
|
|
const cacheSamples: WorkbenchCacheEvidenceSample[] = [];
|
|
const baseLabels = {
|
|
service: "hwlab-cloud-api",
|
|
namespace: sanitizeLabelValue(env.POD_NAMESPACE ?? env.HWLAB_METRICS_NAMESPACE ?? "hwlab-v02"),
|
|
gitops_target: sanitizeLabelValue(env.HWLAB_GITOPS_TARGET ?? env.HWLAB_GITOPS_PROFILE ?? env.HWLAB_RUNTIME_LANE ?? "v02")
|
|
};
|
|
const workbenchBaseLabels = {
|
|
...baseLabels,
|
|
node: sanitizeLabelValue(env.HWLAB_CODE_AGENT_AGENTRUN_PROVIDER_ID ?? env.AGENTRUN_PROVIDER_ID ?? env.HWLAB_NODE_ID ?? "unknown"),
|
|
lane: sanitizeLabelValue(env.HWLAB_RUNTIME_LANE ?? env.HWLAB_GITOPS_TARGET ?? env.HWLAB_GITOPS_PROFILE ?? "unknown")
|
|
};
|
|
|
|
function beginHttpRequest(request: any, response: any) {
|
|
const url = safeUrl(request?.url || "/");
|
|
const context = createContext({ route: backendPerformanceRouteTemplate(url.pathname), method: normalizeMethod(request?.method) });
|
|
const originalWriteHead = typeof response?.writeHead === "function" ? response.writeHead : null;
|
|
if (originalWriteHead) {
|
|
response.writeHead = function writeHeadWithServerTiming(statusCode: number, ...args: unknown[]) {
|
|
context.setStatus(statusCode);
|
|
context.applyServerTimingHeader(response);
|
|
return originalWriteHead.call(this, statusCode, ...args);
|
|
};
|
|
}
|
|
const originalEnd = typeof response?.end === "function" ? response.end : null;
|
|
if (originalEnd) {
|
|
response.end = function endWithBackendEvidenceBytes(chunk?: unknown, encoding?: unknown, callback?: unknown) {
|
|
context.setResponseBytes(responseEndChunkBytes(chunk, encoding));
|
|
return originalEnd.apply(this, arguments as any);
|
|
};
|
|
}
|
|
if (typeof response?.once === "function") {
|
|
response.once("finish", () => context.finish(Number(response.statusCode ?? context.statusCode ?? 0)));
|
|
}
|
|
return context;
|
|
}
|
|
|
|
function createManualContext(input: BackendPerformanceContextInput) {
|
|
return createContext({ route: backendPerformanceRouteTemplate(input.route), method: normalizeMethod(input.method) });
|
|
}
|
|
|
|
function createContext(input: BackendPerformanceContextInput) {
|
|
const startedAt = nowMs();
|
|
const phases: Array<{ name: string; durationMs: number; outcome: string }> = [];
|
|
let statusCode = 200;
|
|
let responseBytes: number | null = null;
|
|
let finished = false;
|
|
const route = input.route;
|
|
const method = input.method;
|
|
|
|
function recordPhase(inputPhase: BackendPhaseInput) {
|
|
const durationMs = boundedDurationMs(inputPhase.durationMs, 30_000);
|
|
const phase = sanitizeMetricName(inputPhase.phase, "unknown");
|
|
const outcome = normalizeOutcome(inputPhase.outcome ?? "ok");
|
|
phases.push({ name: phase, durationMs, outcome });
|
|
const labels = { ...baseLabels, route, method, phase, outcome };
|
|
if (!recordHistogram(requestPhaseSeries, labels, durationMs / 1000, PHASE_BUCKETS_SECONDS, maxSeries)) incrementDropped("phase_series_limit");
|
|
}
|
|
|
|
async function measure<T>(phase: string, fn: () => Promise<T> | T): Promise<T> {
|
|
const phaseStartedAt = nowMs();
|
|
try {
|
|
const result = await fn();
|
|
recordPhase({ phase, durationMs: nowMs() - phaseStartedAt, outcome: "ok" });
|
|
return result;
|
|
} catch (error) {
|
|
recordPhase({ phase, durationMs: nowMs() - phaseStartedAt, outcome: "error" });
|
|
throw error;
|
|
}
|
|
}
|
|
|
|
function recordUpstream(inputUpstream: BackendUpstreamInput) {
|
|
const labels = {
|
|
...baseLabels,
|
|
component: sanitizeMetricName(inputUpstream.component, "unknown"),
|
|
operation: sanitizeMetricName(inputUpstream.operation ?? inputUpstream.route, "unknown"),
|
|
route: backendPerformanceRouteTemplate(inputUpstream.route),
|
|
method: normalizeMethod(inputUpstream.method),
|
|
status_class: normalizeStatusClass(inputUpstream.statusClass ?? "unknown"),
|
|
outcome: normalizeOutcome(inputUpstream.outcome ?? "ok")
|
|
};
|
|
if (!recordHistogram(upstreamSeries, labels, boundedDurationMs(inputUpstream.durationMs, 120_000) / 1000, UPSTREAM_BUCKETS_SECONDS, maxSeries)) incrementDropped("upstream_series_limit");
|
|
}
|
|
|
|
function setStatus(nextStatusCode: number) {
|
|
if (Number.isInteger(nextStatusCode) && nextStatusCode > 0) statusCode = nextStatusCode;
|
|
}
|
|
|
|
function setResponseBytes(bytes: number | null) {
|
|
if (bytes === null) return;
|
|
responseBytes = Math.min(64 * 1024 * 1024, Math.max(0, Math.trunc(bytes)));
|
|
}
|
|
|
|
function applyServerTimingHeader(response: any) {
|
|
if (!response || typeof response.setHeader !== "function" || response.headersSent) return;
|
|
const header = serverTimingHeader(nowMs() - startedAt, phases);
|
|
if (header) response.setHeader("server-timing", header);
|
|
}
|
|
|
|
function finish(finalStatusCode = statusCode) {
|
|
if (finished) return;
|
|
finished = true;
|
|
const statusClassValue = statusClass(finalStatusCode);
|
|
const outcome = statusClassValue === "5xx" ? "error" : statusClassValue === "4xx" ? "denied" : "ok";
|
|
const labels = { ...baseLabels, route, method, status_class: statusClassValue, outcome };
|
|
if (!recordHistogram(requestDurationSeries, labels, boundedDurationMs(nowMs() - startedAt, 120_000) / 1000, REQUEST_BUCKETS_SECONDS, maxSeries)) incrementDropped("request_series_limit");
|
|
incrementCounter(requestTotalSeries, labels, maxSeries) || incrementDropped("request_counter_series_limit");
|
|
recordBackendRequestSample({
|
|
atMs: Date.now(),
|
|
route,
|
|
method,
|
|
statusClass: statusClassValue,
|
|
outcome,
|
|
durationSeconds: boundedDurationMs(nowMs() - startedAt, 120_000) / 1000,
|
|
responseBytes,
|
|
phases: phases.map((phase) => ({ phase: phase.name, outcome: phase.outcome, durationSeconds: boundedDurationMs(phase.durationMs, 30_000) / 1000 }))
|
|
});
|
|
}
|
|
|
|
return { route, method, startedAt, recordPhase, measure, recordUpstream, setStatus, setResponseBytes, applyServerTimingHeader, finish, get statusCode() { return statusCode; } };
|
|
}
|
|
|
|
function recordBackendRequestSample(sample: BackendRequestSample) {
|
|
requestSamples.push(sample);
|
|
if (requestSamples.length > maxEvidenceSamples) requestSamples.splice(0, requestSamples.length - maxEvidenceSamples);
|
|
}
|
|
|
|
function recordWorkbenchProjection(input: WorkbenchProjectionInput = {}) {
|
|
const labels = {
|
|
...workbenchBaseLabels,
|
|
status: normalizeStatusLabel(input.status ?? "unknown"),
|
|
reason: normalizeReason(input.reason ?? "none"),
|
|
projection_status: normalizeProjectionStatus(input.projectionStatus ?? "unknown"),
|
|
source: normalizeSourceLabel(input.source ?? "agentrun_v01")
|
|
};
|
|
const sourceSeq = finiteNonNegativeNumber(input.sourceLatestSeq);
|
|
const projectedSeq = finiteNonNegativeNumber(input.lastProjectedSeq);
|
|
if (sourceSeq !== null && projectedSeq !== null) {
|
|
const lagEvents = isTerminalProjectionStatus(labels.projection_status)
|
|
? 0
|
|
: Math.max(0, Math.floor(sourceSeq - projectedSeq));
|
|
if (!recordHistogram(projectionLagEventsSeries, labels, lagEvents, PROJECTION_LAG_EVENT_BUCKETS, maxSeries)) incrementDropped("projection_lag_events_series_limit");
|
|
setGauge(projectionStuckGaugeSeries, labels, lagEvents > 0 && labels.projection_status !== "caught_up" ? 1 : 0, maxSeries) || incrementDropped("projection_stuck_series_limit");
|
|
}
|
|
const sourceAt = unixMs(input.sourceLatestEventAt);
|
|
const projectedAt = unixMs(input.projectedLatestEventAt);
|
|
if (sourceAt !== null && projectedAt !== null) {
|
|
const lagSeconds = isTerminalProjectionStatus(labels.projection_status) ? 0 : Math.max(0, (sourceAt - projectedAt) / 1000);
|
|
if (!recordHistogram(projectionLagSecondsSeries, labels, lagSeconds, PROJECTION_LAG_SECONDS_BUCKETS, maxSeries)) incrementDropped("projection_lag_seconds_series_limit");
|
|
}
|
|
const terminalSourceAt = unixMs(input.terminalSourceAt);
|
|
const terminalProjectedAt = unixMs(input.terminalProjectedAt) ?? (isTerminalProjectionStatus(labels.projection_status) ? projectedAt : null);
|
|
if (terminalSourceAt !== null) {
|
|
const delaySeconds = Math.max(0, ((terminalProjectedAt ?? Date.now()) - terminalSourceAt) / 1000);
|
|
if (!recordHistogram(terminalProjectionDelaySeries, labels, delaySeconds, PROJECTION_LAG_SECONDS_BUCKETS, maxSeries)) incrementDropped("terminal_projection_delay_series_limit");
|
|
}
|
|
}
|
|
|
|
function recordWorkbenchProjectionCursorAdvance(input: WorkbenchProjectorCounterInput = {}) {
|
|
const labels = {
|
|
...workbenchBaseLabels,
|
|
status: normalizeStatusLabel(input.status ?? "advanced"),
|
|
reason: normalizeReason(input.reason ?? "sync"),
|
|
projection_status: normalizeProjectionStatus((input as any).projectionStatus ?? "projecting"),
|
|
source: normalizeSourceLabel((input as any).source ?? "agentrun_v01")
|
|
};
|
|
incrementCounterBy(projectionCursorAdvanceSeries, labels, boundedCounterValue(input.count), maxSeries) || incrementDropped("projection_cursor_advance_series_limit");
|
|
}
|
|
|
|
function recordWorkbenchTurnRead(input: WorkbenchTurnReadInput) {
|
|
const labels = {
|
|
...workbenchBaseLabels,
|
|
route: workbenchTurnRouteTemplate(input.route),
|
|
status: normalizeStatusLabel(input.status ?? "unknown"),
|
|
degraded_reason: normalizeReason(input.degradedReason ?? "none")
|
|
};
|
|
if (!recordHistogram(turnGetDurationSeries, labels, boundedDurationMs(input.durationMs, 120_000) / 1000, WORKBENCH_TURN_DURATION_BUCKETS_SECONDS, maxSeries)) incrementDropped("turn_get_duration_series_limit");
|
|
const bytes = finiteNonNegativeNumber(input.responseBytes);
|
|
if (bytes !== null) {
|
|
const byteLabels = { ...workbenchBaseLabels, route: labels.route, status: labels.status };
|
|
if (!recordHistogram(turnGetResponseBytesSeries, byteLabels, bytes, WORKBENCH_TURN_RESPONSE_BYTES_BUCKETS, maxSeries)) incrementDropped("turn_get_response_bytes_series_limit");
|
|
}
|
|
if (input.timedOut === true || labels.status === "timeout") {
|
|
const timeoutLabels = { ...workbenchBaseLabels, route: labels.route, degraded_reason: labels.degraded_reason };
|
|
incrementCounter(turnGetTimeoutSeries, timeoutLabels, maxSeries) || incrementDropped("turn_get_timeout_series_limit");
|
|
}
|
|
}
|
|
|
|
function recordWorkbenchCache(input: WorkbenchCacheInput) {
|
|
const route = workbenchCacheRouteTemplate(input.route);
|
|
const cacheKeyClass = normalizeCacheKeyClass(input.cacheKeyClass);
|
|
const cacheStatus = normalizeCacheStatus(input.cacheStatus);
|
|
const operation = normalizeCacheOperation(input.operation ?? "read");
|
|
const labels = {
|
|
...workbenchBaseLabels,
|
|
route,
|
|
cache_key_class: cacheKeyClass,
|
|
operation,
|
|
cache_status: cacheStatus
|
|
};
|
|
incrementCounter(cacheRequestSeries, labels, maxSeries) || incrementDropped("workbench_cache_request_series_limit");
|
|
const durationMs = finiteNonNegativeNumber(input.durationMs);
|
|
const durationSeconds = durationMs === null ? null : boundedDurationMs(durationMs, 120_000) / 1000;
|
|
if (durationSeconds !== null) {
|
|
if (!recordHistogram(cacheOperationDurationSeries, labels, durationSeconds, WORKBENCH_CACHE_OPERATION_BUCKETS_SECONDS, maxSeries)) incrementDropped("workbench_cache_operation_series_limit");
|
|
}
|
|
const payloadBytes = finiteNonNegativeNumber(input.payloadBytes);
|
|
if (payloadBytes !== null) {
|
|
if (!recordHistogram(cachePayloadBytesSeries, labels, payloadBytes, WORKBENCH_CACHE_PAYLOAD_BYTES_BUCKETS, maxSeries)) incrementDropped("workbench_cache_payload_series_limit");
|
|
}
|
|
if (cacheStatus === "stale") {
|
|
incrementCounter(cacheStaleSeries, labels, maxSeries) || incrementDropped("workbench_cache_stale_series_limit");
|
|
}
|
|
if (cacheStatus === "unavailable" || cacheStatus === "set_failed" || cacheStatus === "error") {
|
|
incrementCounter(cacheUnavailableSeries, labels, maxSeries) || incrementDropped("workbench_cache_unavailable_series_limit");
|
|
}
|
|
const dbQueryAvoided = booleanValue(input.dbQueryAvoided);
|
|
if (dbQueryAvoided) {
|
|
const avoidedLabels = { ...workbenchBaseLabels, route, cache_key_class: cacheKeyClass };
|
|
incrementCounter(dbQueryAvoidedSeries, avoidedLabels, maxSeries) || incrementDropped("workbench_db_query_avoided_series_limit");
|
|
}
|
|
cacheSamples.push({
|
|
atMs: Date.now(),
|
|
route,
|
|
cacheKeyClass,
|
|
cacheStatus,
|
|
operation,
|
|
durationSeconds,
|
|
payloadBytes,
|
|
cacheAgeMs: finiteNonNegativeNumber(input.cacheAgeMs),
|
|
dbQueryAvoided,
|
|
freshnessSloMs: finiteNonNegativeNumber(input.freshnessSloMs),
|
|
projectionSeq: finiteNonNegativeNumber(input.projectionSeq)
|
|
});
|
|
while (cacheSamples.length > maxEvidenceSamples) cacheSamples.shift();
|
|
}
|
|
|
|
function recordAgentRunResult(input: AgentRunResultInput = {}) {
|
|
const eventCount = finiteNonNegativeNumber(input.eventCount ?? input.eventsScanned) ?? 0;
|
|
const labels = {
|
|
...workbenchBaseLabels,
|
|
event_count_bucket: agentRunEventCountBucket(eventCount),
|
|
status: normalizeStatusLabel(input.status ?? (input.timedOut ? "timeout" : "unknown"))
|
|
};
|
|
const durationMs = finiteNonNegativeNumber(input.durationMs);
|
|
if (durationMs !== null) {
|
|
if (!recordHistogram(agentRunResultDurationSeries, labels, boundedDurationMs(durationMs, 120_000) / 1000, AGENTRUN_RESULT_BUCKETS_SECONDS, maxSeries)) incrementDropped("agentrun_result_duration_series_limit");
|
|
}
|
|
const pagesScanned = finiteNonNegativeNumber(input.pagesScanned);
|
|
if (pagesScanned !== null) {
|
|
if (!recordHistogram(agentRunResultPagesSeries, workbenchBaseLabels, pagesScanned, AGENTRUN_RESULT_PAGES_BUCKETS, maxSeries)) incrementDropped("agentrun_result_pages_series_limit");
|
|
}
|
|
const eventsScanned = finiteNonNegativeNumber(input.eventsScanned);
|
|
if (eventsScanned !== null) {
|
|
if (!recordHistogram(agentRunResultEventsSeries, workbenchBaseLabels, eventsScanned, AGENTRUN_RESULT_EVENTS_BUCKETS, maxSeries)) incrementDropped("agentrun_result_events_series_limit");
|
|
}
|
|
if (input.timedOut === true || labels.status === "timeout") {
|
|
const timeoutLabels = {
|
|
...workbenchBaseLabels,
|
|
budget: normalizeBudgetLabel(input.budget),
|
|
status: labels.status
|
|
};
|
|
incrementCounter(agentRunResultTimeoutSeries, timeoutLabels, maxSeries) || incrementDropped("agentrun_result_timeout_series_limit");
|
|
}
|
|
}
|
|
|
|
function recordWorkbenchProjectorBatch(input: WorkbenchProjectorBatchInput) {
|
|
const labels = {
|
|
...workbenchBaseLabels,
|
|
phase: normalizeProjectorPhase(input.phase),
|
|
status: normalizeStatusLabel(input.status ?? "ok")
|
|
};
|
|
if (!recordHistogram(projectorBatchDurationSeries, labels, boundedDurationMs(input.durationMs, 120_000) / 1000, PROJECTOR_BATCH_BUCKETS_SECONDS, maxSeries)) incrementDropped("projector_batch_series_limit");
|
|
if (labels.status === "ok") setGauge(projectorLastSuccessSeries, workbenchBaseLabels, Math.floor(Date.now() / 1000), maxSeries) || incrementDropped("projector_last_success_series_limit");
|
|
}
|
|
|
|
function recordWorkbenchProjectorCandidate(input: WorkbenchProjectorCounterInput = {}) {
|
|
const labels = {
|
|
...workbenchBaseLabels,
|
|
status: normalizeStatusLabel(input.status ?? "seen"),
|
|
reason: normalizeReason(input.reason ?? "unknown")
|
|
};
|
|
incrementCounterBy(projectorCandidatesSeries, labels, boundedCounterValue(input.count), maxSeries) || incrementDropped("projector_candidates_series_limit");
|
|
}
|
|
|
|
function recordWorkbenchProjectorEvents(input: WorkbenchProjectorCounterInput = {}) {
|
|
const labels = {
|
|
...workbenchBaseLabels,
|
|
event_kind: normalizeReason(input.eventKind ?? "unknown"),
|
|
status: normalizeStatusLabel(input.status ?? "ok")
|
|
};
|
|
incrementCounterBy(projectorEventsProcessedSeries, labels, boundedCounterValue(input.count), maxSeries) || incrementDropped("projector_events_series_limit");
|
|
}
|
|
|
|
function recordWorkbenchProjectorError(input: WorkbenchProjectorCounterInput = {}) {
|
|
const labels = {
|
|
...workbenchBaseLabels,
|
|
reason: normalizeReason(input.reason ?? "unknown")
|
|
};
|
|
incrementCounterBy(projectorErrorsSeries, labels, boundedCounterValue(input.count), maxSeries) || incrementDropped("projector_errors_series_limit");
|
|
}
|
|
|
|
function incrementDropped(reason: string) {
|
|
incrementCounter(droppedSeries, { ...baseLabels, reason }, Math.max(maxSeries, 16));
|
|
}
|
|
|
|
function metricsText() {
|
|
return [
|
|
"# HELP hwlab_cloud_api_requests_total Cloud API HTTP requests by low-cardinality route template.",
|
|
"# TYPE hwlab_cloud_api_requests_total counter",
|
|
...renderCounters("hwlab_cloud_api_requests_total", requestTotalSeries),
|
|
"# HELP hwlab_cloud_api_request_duration_seconds Cloud API HTTP request duration in seconds.",
|
|
"# TYPE hwlab_cloud_api_request_duration_seconds histogram",
|
|
...renderHistogram("hwlab_cloud_api_request_duration_seconds", requestDurationSeries, REQUEST_BUCKETS_SECONDS),
|
|
"# HELP hwlab_cloud_api_request_phase_duration_seconds Cloud API handler phase duration in seconds.",
|
|
"# TYPE hwlab_cloud_api_request_phase_duration_seconds histogram",
|
|
...renderHistogram("hwlab_cloud_api_request_phase_duration_seconds", requestPhaseSeries, PHASE_BUCKETS_SECONDS),
|
|
"# HELP hwlab_cloud_api_upstream_duration_seconds Cloud API upstream dependency call duration in seconds.",
|
|
"# TYPE hwlab_cloud_api_upstream_duration_seconds histogram",
|
|
...renderHistogram("hwlab_cloud_api_upstream_duration_seconds", upstreamSeries, UPSTREAM_BUCKETS_SECONDS),
|
|
"# HELP hwlab_cloud_api_performance_dropped_total Backend performance samples dropped before Prometheus export.",
|
|
"# TYPE hwlab_cloud_api_performance_dropped_total counter",
|
|
...renderCounters("hwlab_cloud_api_performance_dropped_total", droppedSeries),
|
|
"# HELP hwlab_workbench_projection_lag_events Workbench projection source seq lag in AgentRun events.",
|
|
"# TYPE hwlab_workbench_projection_lag_events histogram",
|
|
...renderHistogram("hwlab_workbench_projection_lag_events", projectionLagEventsSeries, PROJECTION_LAG_EVENT_BUCKETS),
|
|
"# HELP hwlab_workbench_projection_lag_seconds Workbench projection source time lag in seconds.",
|
|
"# TYPE hwlab_workbench_projection_lag_seconds histogram",
|
|
...renderHistogram("hwlab_workbench_projection_lag_seconds", projectionLagSecondsSeries, PROJECTION_LAG_SECONDS_BUCKETS),
|
|
"# HELP hwlab_workbench_projection_stuck_traces Low-cardinality gauge set to 1 when the observed projection is behind its source.",
|
|
"# TYPE hwlab_workbench_projection_stuck_traces gauge",
|
|
...renderGauges("hwlab_workbench_projection_stuck_traces", projectionStuckGaugeSeries),
|
|
"# HELP hwlab_workbench_projection_cursor_advance_total Workbench projection cursor advance events.",
|
|
"# TYPE hwlab_workbench_projection_cursor_advance_total counter",
|
|
...renderCounters("hwlab_workbench_projection_cursor_advance_total", projectionCursorAdvanceSeries),
|
|
"# HELP hwlab_workbench_terminal_projection_delay_seconds Delay from AgentRun terminal source to Workbench terminal projection.",
|
|
"# TYPE hwlab_workbench_terminal_projection_delay_seconds histogram",
|
|
...renderHistogram("hwlab_workbench_terminal_projection_delay_seconds", terminalProjectionDelaySeries, PROJECTION_LAG_SECONDS_BUCKETS),
|
|
"# HELP hwlab_workbench_turn_get_duration_seconds Workbench turn/read API duration in seconds.",
|
|
"# TYPE hwlab_workbench_turn_get_duration_seconds histogram",
|
|
...renderHistogram("hwlab_workbench_turn_get_duration_seconds", turnGetDurationSeries, WORKBENCH_TURN_DURATION_BUCKETS_SECONDS),
|
|
"# HELP hwlab_workbench_turn_get_timeout_total Workbench turn/read API timeout count.",
|
|
"# TYPE hwlab_workbench_turn_get_timeout_total counter",
|
|
...renderCounters("hwlab_workbench_turn_get_timeout_total", turnGetTimeoutSeries),
|
|
"# HELP hwlab_workbench_turn_get_response_bytes Workbench turn/read API response bytes.",
|
|
"# TYPE hwlab_workbench_turn_get_response_bytes histogram",
|
|
...renderHistogram("hwlab_workbench_turn_get_response_bytes", turnGetResponseBytesSeries, WORKBENCH_TURN_RESPONSE_BYTES_BUCKETS),
|
|
"# HELP workbench_cache_requests_total Workbench derived cache requests observed by Cloud API read path.",
|
|
"# TYPE workbench_cache_requests_total counter",
|
|
...renderCounters("workbench_cache_requests_total", cacheRequestSeries),
|
|
"# HELP workbench_cache_hit_ratio Workbench derived cache hit ratio by route and cache class.",
|
|
"# TYPE workbench_cache_hit_ratio gauge",
|
|
...renderWorkbenchCacheHitRatio(cacheRequestSeries),
|
|
"# HELP workbench_cache_operation_duration_seconds Workbench derived cache operation observation duration in seconds.",
|
|
"# TYPE workbench_cache_operation_duration_seconds histogram",
|
|
...renderHistogram("workbench_cache_operation_duration_seconds", cacheOperationDurationSeries, WORKBENCH_CACHE_OPERATION_BUCKETS_SECONDS),
|
|
"# HELP workbench_cache_payload_bytes Workbench derived cache payload size in bytes.",
|
|
"# TYPE workbench_cache_payload_bytes histogram",
|
|
...renderHistogram("workbench_cache_payload_bytes", cachePayloadBytesSeries, WORKBENCH_CACHE_PAYLOAD_BYTES_BUCKETS),
|
|
"# HELP workbench_cache_stale_total Workbench derived cache stale observations.",
|
|
"# TYPE workbench_cache_stale_total counter",
|
|
...renderCounters("workbench_cache_stale_total", cacheStaleSeries),
|
|
"# HELP workbench_cache_unavailable_total Workbench derived cache unavailable observations.",
|
|
"# TYPE workbench_cache_unavailable_total counter",
|
|
...renderCounters("workbench_cache_unavailable_total", cacheUnavailableSeries),
|
|
"# HELP workbench_db_query_avoided_total Workbench DB reads avoided by derived cache hits.",
|
|
"# TYPE workbench_db_query_avoided_total counter",
|
|
...renderCounters("workbench_db_query_avoided_total", dbQueryAvoidedSeries),
|
|
"# HELP hwlab_agentrun_result_duration_seconds AgentRun command result aggregation duration in seconds.",
|
|
"# TYPE hwlab_agentrun_result_duration_seconds histogram",
|
|
...renderHistogram("hwlab_agentrun_result_duration_seconds", agentRunResultDurationSeries, AGENTRUN_RESULT_BUCKETS_SECONDS),
|
|
"# HELP hwlab_agentrun_result_pages_scanned AgentRun result estimated pages scanned.",
|
|
"# TYPE hwlab_agentrun_result_pages_scanned histogram",
|
|
...renderHistogram("hwlab_agentrun_result_pages_scanned", agentRunResultPagesSeries, AGENTRUN_RESULT_PAGES_BUCKETS),
|
|
"# HELP hwlab_agentrun_result_events_scanned AgentRun result estimated events scanned.",
|
|
"# TYPE hwlab_agentrun_result_events_scanned histogram",
|
|
...renderHistogram("hwlab_agentrun_result_events_scanned", agentRunResultEventsSeries, AGENTRUN_RESULT_EVENTS_BUCKETS),
|
|
"# HELP hwlab_agentrun_result_timeout_total AgentRun result timeout count by refresh budget.",
|
|
"# TYPE hwlab_agentrun_result_timeout_total counter",
|
|
...renderCounters("hwlab_agentrun_result_timeout_total", agentRunResultTimeoutSeries),
|
|
"# HELP hwlab_workbench_projector_batch_duration_seconds Workbench projector/finalizer batch phase duration in seconds.",
|
|
"# TYPE hwlab_workbench_projector_batch_duration_seconds histogram",
|
|
...renderHistogram("hwlab_workbench_projector_batch_duration_seconds", projectorBatchDurationSeries, PROJECTOR_BATCH_BUCKETS_SECONDS),
|
|
"# HELP hwlab_workbench_projector_candidates_total Workbench projector/finalizer candidate count.",
|
|
"# TYPE hwlab_workbench_projector_candidates_total counter",
|
|
...renderCounters("hwlab_workbench_projector_candidates_total", projectorCandidatesSeries),
|
|
"# HELP hwlab_workbench_projector_events_processed_total Workbench projector/finalizer processed event count.",
|
|
"# TYPE hwlab_workbench_projector_events_processed_total counter",
|
|
...renderCounters("hwlab_workbench_projector_events_processed_total", projectorEventsProcessedSeries),
|
|
"# HELP hwlab_workbench_projector_errors_total Workbench projector/finalizer error count.",
|
|
"# TYPE hwlab_workbench_projector_errors_total counter",
|
|
...renderCounters("hwlab_workbench_projector_errors_total", projectorErrorsSeries),
|
|
"# HELP hwlab_workbench_projector_last_success_unixtime Last successful Workbench projector/finalizer sync unix time.",
|
|
"# TYPE hwlab_workbench_projector_last_success_unixtime gauge",
|
|
...renderGauges("hwlab_workbench_projector_last_success_unixtime", projectorLastSuccessSeries),
|
|
""
|
|
].join("\n");
|
|
}
|
|
|
|
function snapshot() {
|
|
return {
|
|
requestSeries: requestDurationSeries.size,
|
|
requestCount: [...requestTotalSeries.values()].reduce((sum, entry) => sum + entry.value, 0),
|
|
requestPhaseSeries: requestPhaseSeries.size,
|
|
requestPhaseCount: histogramSampleCount(requestPhaseSeries),
|
|
upstreamSeries: upstreamSeries.size,
|
|
upstreamCount: histogramSampleCount(upstreamSeries),
|
|
projectionLagSeries: projectionLagEventsSeries.size + projectionLagSecondsSeries.size,
|
|
turnReadSeries: turnGetDurationSeries.size,
|
|
cacheSeries: cacheRequestSeries.size + cacheOperationDurationSeries.size + cachePayloadBytesSeries.size + cacheStaleSeries.size + cacheUnavailableSeries.size + dbQueryAvoidedSeries.size,
|
|
agentRunResultSeries: agentRunResultDurationSeries.size,
|
|
projectorSeries: projectorBatchDurationSeries.size + projectorCandidatesSeries.size + projectorEventsProcessedSeries.size + projectorErrorsSeries.size,
|
|
droppedSeries: droppedSeries.size,
|
|
evidenceSamples: requestSamples.length,
|
|
cacheEvidenceSamples: cacheSamples.length
|
|
};
|
|
}
|
|
|
|
function evidence(input: { window?: unknown } = {}) {
|
|
const sampleWindow = resolveBackendEvidenceWindow(input.window);
|
|
const generatedAtMs = Date.now();
|
|
const observedAt = new Date(generatedAtMs).toISOString();
|
|
const cutoff = sampleWindow.milliseconds === null ? null : generatedAtMs - sampleWindow.milliseconds;
|
|
const windowSamples = requestSamples.filter((sample) => cutoff === null || (sample.atMs >= cutoff && sample.atMs <= generatedAtMs));
|
|
const windowCacheSamples = cacheSamples.filter((sample) => cutoff === null || (sample.atMs >= cutoff && sample.atMs <= generatedAtMs));
|
|
const rows = backendEvidenceRows(windowSamples);
|
|
const cache = backendCacheEvidenceRows(windowCacheSamples);
|
|
return {
|
|
schemaVersion: "hwlab-backend-performance-evidence-v1",
|
|
source: "cloud-api-backend-performance-store",
|
|
observedAt,
|
|
sampleWindow: {
|
|
id: sampleWindow.id,
|
|
label: sampleWindow.label,
|
|
seconds: sampleWindow.milliseconds === null ? null : Math.round(sampleWindow.milliseconds / 1000),
|
|
windowFrom: cutoff === null ? null : new Date(Math.max(0, cutoff)).toISOString(),
|
|
windowTo: observedAt
|
|
},
|
|
sampleCount: windowSamples.length,
|
|
retainedSampleCount: requestSamples.length,
|
|
cacheSampleCount: windowCacheSamples.length,
|
|
retainedCacheSampleCount: cacheSamples.length,
|
|
routeCount: new Set(rows.map((row) => row.route)).size,
|
|
rows,
|
|
cache,
|
|
valuesRedacted: true
|
|
};
|
|
}
|
|
|
|
return {
|
|
beginHttpRequest,
|
|
createManualContext,
|
|
recordWorkbenchProjection,
|
|
recordWorkbenchProjectionCursorAdvance,
|
|
recordWorkbenchTurnRead,
|
|
recordWorkbenchCache,
|
|
recordAgentRunResult,
|
|
recordWorkbenchProjectorBatch,
|
|
recordWorkbenchProjectorCandidate,
|
|
recordWorkbenchProjectorEvents,
|
|
recordWorkbenchProjectorError,
|
|
metricsText,
|
|
snapshot,
|
|
evidence
|
|
};
|
|
}
|
|
|
|
export function withBackendPerformanceContext<T>(context: unknown, callback: () => T): T {
|
|
return backendPerformanceStorage.run(context, callback);
|
|
}
|
|
|
|
export function currentBackendPerformanceContext(): any {
|
|
return backendPerformanceStorage.getStore() ?? null;
|
|
}
|
|
|
|
export function backendPerformanceRouteTemplate(input: unknown): string {
|
|
const raw = String(input ?? "").trim() || "/";
|
|
const pathOnly = raw.split(/[?#]/u, 1)[0] || "/";
|
|
let pathname = pathOnly;
|
|
try {
|
|
pathname = new URL(raw, "http://hwlab.local").pathname || pathOnly;
|
|
} catch {
|
|
// Keep pathOnly.
|
|
}
|
|
const parts = pathname.split("/").filter(Boolean).map((part) => routeSegmentTemplate(safeDecode(part)));
|
|
const path = `/${parts.join("/")}`;
|
|
return path.length > 140 ? `${path.slice(0, 137)}...` : path;
|
|
}
|
|
|
|
function workbenchTurnRouteTemplate(input: unknown): string {
|
|
const route = backendPerformanceRouteTemplate(input);
|
|
if (route === "/v1/workbench/turns/:id") return "/v1/workbench/turns/:traceId";
|
|
if (route === "/v1/agent/turns/:id") return "/v1/agent/turns/:traceId";
|
|
return route;
|
|
}
|
|
|
|
function workbenchCacheRouteTemplate(input: unknown): string {
|
|
const route = workbenchTurnRouteTemplate(input);
|
|
if (route === "/v1/workbench/traces/:id/events") return "/v1/workbench/traces/:traceId/events";
|
|
return route;
|
|
}
|
|
|
|
function resolveBackendEvidenceWindow(input: unknown) {
|
|
const key = String(input ?? DEFAULT_BACKEND_EVIDENCE_WINDOW).trim().toLowerCase();
|
|
if (Object.prototype.hasOwnProperty.call(BACKEND_EVIDENCE_WINDOWS, key)) return BACKEND_EVIDENCE_WINDOWS[key as keyof typeof BACKEND_EVIDENCE_WINDOWS];
|
|
return BACKEND_EVIDENCE_WINDOWS[DEFAULT_BACKEND_EVIDENCE_WINDOW];
|
|
}
|
|
|
|
function backendEvidenceRows(samples: BackendRequestSample[]) {
|
|
const groups = new Map<string, { sample: BackendRequestSample; durations: number[]; bytes: number[]; phases: Map<string, { phase: string; outcome: string; durations: number[] }>; firstAt: number; lastAt: number }>();
|
|
for (const sample of samples) {
|
|
const key = stableLabelKey({ route: sample.route, method: sample.method, statusClass: sample.statusClass, outcome: sample.outcome });
|
|
let group = groups.get(key);
|
|
if (!group) {
|
|
group = { sample, durations: [], bytes: [], phases: new Map(), firstAt: sample.atMs, lastAt: sample.atMs };
|
|
groups.set(key, group);
|
|
}
|
|
group.durations.push(sample.durationSeconds);
|
|
if (sample.responseBytes !== null) group.bytes.push(sample.responseBytes);
|
|
group.firstAt = Math.min(group.firstAt, sample.atMs);
|
|
group.lastAt = Math.max(group.lastAt, sample.atMs);
|
|
for (const phase of sample.phases) {
|
|
const phaseKey = stableLabelKey({ phase: phase.phase, outcome: phase.outcome });
|
|
let phaseGroup = group.phases.get(phaseKey);
|
|
if (!phaseGroup) {
|
|
phaseGroup = { phase: phase.phase, outcome: phase.outcome, durations: [] };
|
|
group.phases.set(phaseKey, phaseGroup);
|
|
}
|
|
phaseGroup.durations.push(phase.durationSeconds);
|
|
}
|
|
}
|
|
return [...groups.values()].map((group) => {
|
|
const duration = exactEvidenceStats(group.durations);
|
|
const responseBytes = group.bytes.length ? exactEvidenceStats(group.bytes) : null;
|
|
const phases = [...group.phases.values()].map((phaseGroup) => ({
|
|
phase: phaseGroup.phase,
|
|
outcome: phaseGroup.outcome,
|
|
...exactEvidenceStats(phaseGroup.durations)
|
|
})).sort((left, right) => (right.p95 - left.p95) || (right.count - left.count)).slice(0, 8);
|
|
return {
|
|
route: group.sample.route,
|
|
method: group.sample.method,
|
|
statusClass: group.sample.statusClass,
|
|
outcome: group.sample.outcome,
|
|
count: duration.count,
|
|
average: duration.average,
|
|
p50: duration.p50,
|
|
p75: duration.p75,
|
|
p95: duration.p95,
|
|
unit: "seconds",
|
|
firstObservedAt: new Date(group.firstAt).toISOString(),
|
|
lastObservedAt: new Date(group.lastAt).toISOString(),
|
|
responseBytes: responseBytes ? { count: responseBytes.count, average: Math.round(responseBytes.average), p50: Math.round(responseBytes.p50), p75: Math.round(responseBytes.p75), p95: Math.round(responseBytes.p95), unit: "bytes" } : null,
|
|
phases,
|
|
valuesRedacted: true
|
|
};
|
|
}).sort((left, right) => (right.p95 - left.p95) || (right.count - left.count));
|
|
}
|
|
|
|
function backendCacheEvidenceRows(samples: WorkbenchCacheEvidenceSample[]) {
|
|
const groups = new Map<string, {
|
|
route: string;
|
|
cacheKeyClass: string;
|
|
count: number;
|
|
hitCount: number;
|
|
missCount: number;
|
|
staleCount: number;
|
|
unavailableCount: number;
|
|
dbQueryAvoidedCount: number;
|
|
durations: number[];
|
|
payloads: number[];
|
|
ages: number[];
|
|
freshness: number[];
|
|
projectionSeqMax: number | null;
|
|
firstAt: number;
|
|
lastAt: number;
|
|
}>();
|
|
for (const sample of samples) {
|
|
const key = stableLabelKey({ route: sample.route, cache_key_class: sample.cacheKeyClass });
|
|
let group = groups.get(key);
|
|
if (!group) {
|
|
group = { route: sample.route, cacheKeyClass: sample.cacheKeyClass, count: 0, hitCount: 0, missCount: 0, staleCount: 0, unavailableCount: 0, dbQueryAvoidedCount: 0, durations: [], payloads: [], ages: [], freshness: [], projectionSeqMax: null, firstAt: sample.atMs, lastAt: sample.atMs };
|
|
groups.set(key, group);
|
|
}
|
|
group.count += 1;
|
|
if (sample.cacheStatus === "hit") group.hitCount += 1;
|
|
if (sample.cacheStatus === "miss") group.missCount += 1;
|
|
if (sample.cacheStatus === "stale") group.staleCount += 1;
|
|
if (sample.cacheStatus === "unavailable" || sample.cacheStatus === "set_failed" || sample.cacheStatus === "error") group.unavailableCount += 1;
|
|
if (sample.dbQueryAvoided) group.dbQueryAvoidedCount += 1;
|
|
if (sample.durationSeconds !== null) group.durations.push(sample.durationSeconds);
|
|
if (sample.payloadBytes !== null) group.payloads.push(sample.payloadBytes);
|
|
if (sample.cacheAgeMs !== null) group.ages.push(sample.cacheAgeMs);
|
|
if (sample.freshnessSloMs !== null) group.freshness.push(sample.freshnessSloMs);
|
|
if (sample.projectionSeq !== null) group.projectionSeqMax = Math.max(group.projectionSeqMax ?? 0, sample.projectionSeq);
|
|
group.firstAt = Math.min(group.firstAt, sample.atMs);
|
|
group.lastAt = Math.max(group.lastAt, sample.atMs);
|
|
}
|
|
return [...groups.values()].map((group) => {
|
|
const duration = exactEvidenceStats(group.durations);
|
|
const payloadBytes = group.payloads.length ? exactEvidenceStats(group.payloads) : null;
|
|
const cacheAgeMs = group.ages.length ? exactEvidenceStats(group.ages) : null;
|
|
const freshnessSloMs = group.freshness.length ? exactEvidenceStats(group.freshness) : null;
|
|
return {
|
|
route: group.route,
|
|
cacheKeyClass: group.cacheKeyClass,
|
|
count: group.count,
|
|
hitCount: group.hitCount,
|
|
missCount: group.missCount,
|
|
staleCount: group.staleCount,
|
|
unavailableCount: group.unavailableCount,
|
|
dbQueryAvoidedCount: group.dbQueryAvoidedCount,
|
|
hitRatio: group.count > 0 ? roundEvidenceValue(group.hitCount / group.count) : 0,
|
|
dbQueryAvoidedRatio: group.count > 0 ? roundEvidenceValue(group.dbQueryAvoidedCount / group.count) : 0,
|
|
unavailableRatio: group.count > 0 ? roundEvidenceValue(group.unavailableCount / group.count) : 0,
|
|
operationDuration: { ...duration, unit: "seconds" },
|
|
payloadBytes: payloadBytes ? { count: payloadBytes.count, average: Math.round(payloadBytes.average), p50: Math.round(payloadBytes.p50), p75: Math.round(payloadBytes.p75), p95: Math.round(payloadBytes.p95), unit: "bytes" } : null,
|
|
cacheAgeMs: cacheAgeMs ? { ...cacheAgeMs, unit: "milliseconds" } : null,
|
|
freshnessSloMs: freshnessSloMs ? { ...freshnessSloMs, unit: "milliseconds" } : null,
|
|
projectionSeqMax: group.projectionSeqMax,
|
|
firstObservedAt: new Date(group.firstAt).toISOString(),
|
|
lastObservedAt: new Date(group.lastAt).toISOString(),
|
|
valuesRedacted: true
|
|
};
|
|
}).sort((left, right) => (right.unavailableRatio - left.unavailableRatio) || (right.count - left.count) || left.route.localeCompare(right.route));
|
|
}
|
|
|
|
function exactEvidenceStats(values: number[]) {
|
|
const sorted = values.filter(Number.isFinite).sort((left, right) => left - right);
|
|
const count = sorted.length;
|
|
const average = count > 0 ? sorted.reduce((sum, value) => sum + value, 0) / count : 0;
|
|
return {
|
|
count,
|
|
average: roundEvidenceValue(average),
|
|
p50: roundEvidenceValue(exactEvidenceQuantile(sorted, 0.5)),
|
|
p75: roundEvidenceValue(exactEvidenceQuantile(sorted, 0.75)),
|
|
p95: roundEvidenceValue(exactEvidenceQuantile(sorted, 0.95))
|
|
};
|
|
}
|
|
|
|
function exactEvidenceQuantile(sortedValues: number[], quantile: number) {
|
|
if (sortedValues.length <= 0) return 0;
|
|
const index = Math.min(sortedValues.length - 1, Math.max(0, Math.ceil(sortedValues.length * quantile) - 1));
|
|
return sortedValues[index] ?? 0;
|
|
}
|
|
|
|
function roundEvidenceValue(value: number) {
|
|
if (!Number.isFinite(value)) return 0;
|
|
return Math.round(value * 1000) / 1000;
|
|
}
|
|
|
|
function responseEndChunkBytes(chunk: unknown, encoding: unknown): number | null {
|
|
if (chunk === undefined || chunk === null) return null;
|
|
if (Buffer.isBuffer(chunk)) return chunk.length;
|
|
if (typeof chunk === "string") return Buffer.byteLength(chunk, typeof encoding === "string" ? encoding as BufferEncoding : "utf8");
|
|
if (chunk instanceof Uint8Array) return chunk.byteLength;
|
|
return null;
|
|
}
|
|
|
|
function serverTimingHeader(totalMs: number, phases: Array<{ name: string; durationMs: number }>) {
|
|
const entries = phases.slice(-MAX_SERVER_TIMING_ENTRIES).map((phase) => `${serverTimingToken(phase.name)};dur=${roundDurationMs(phase.durationMs)}`);
|
|
entries.push(`total;dur=${roundDurationMs(totalMs)}`);
|
|
return entries.join(", ");
|
|
}
|
|
|
|
function recordHistogram(series: Map<string, HistogramSeries>, labels: Record<string, string>, value: number, buckets: number[], maxSeries: number) {
|
|
const key = stableLabelKey(labels);
|
|
let entry = series.get(key);
|
|
if (!entry) {
|
|
if (series.size >= maxSeries) return false;
|
|
entry = { labels, buckets: buckets.map(() => 0), sum: 0, count: 0 };
|
|
series.set(key, entry);
|
|
}
|
|
for (let index = 0; index < buckets.length; index += 1) {
|
|
if (value <= buckets[index]) entry.buckets[index] += 1;
|
|
}
|
|
entry.sum += value;
|
|
entry.count += 1;
|
|
return true;
|
|
}
|
|
|
|
function incrementCounter(series: Map<string, CounterSeries>, labels: Record<string, string>, maxSeries: number) {
|
|
const key = stableLabelKey(labels);
|
|
let entry = series.get(key);
|
|
if (!entry) {
|
|
if (series.size >= maxSeries) return false;
|
|
entry = { labels, value: 0 };
|
|
series.set(key, entry);
|
|
}
|
|
entry.value += 1;
|
|
return true;
|
|
}
|
|
|
|
function incrementCounterBy(series: Map<string, CounterSeries>, labels: Record<string, string>, value: number, maxSeries: number) {
|
|
const key = stableLabelKey(labels);
|
|
let entry = series.get(key);
|
|
if (!entry) {
|
|
if (series.size >= maxSeries) return false;
|
|
entry = { labels, value: 0 };
|
|
series.set(key, entry);
|
|
}
|
|
entry.value += value;
|
|
return true;
|
|
}
|
|
|
|
function setGauge(series: Map<string, GaugeSeries>, labels: Record<string, string>, value: number, maxSeries: number) {
|
|
const key = stableLabelKey(labels);
|
|
let entry = series.get(key);
|
|
if (!entry) {
|
|
if (series.size >= maxSeries) return false;
|
|
entry = { labels, value: 0 };
|
|
series.set(key, entry);
|
|
}
|
|
entry.value = Number.isFinite(value) ? value : 0;
|
|
return true;
|
|
}
|
|
|
|
function renderCounters(metricName: string, series: Map<string, CounterSeries>) {
|
|
return [...series.values()].map((entry) => `${metricName}{${renderLabels(entry.labels)}} ${entry.value}`);
|
|
}
|
|
|
|
function renderGauges(metricName: string, series: Map<string, GaugeSeries>) {
|
|
return [...series.values()].map((entry) => `${metricName}{${renderLabels(entry.labels)}} ${formatPrometheusValue(entry.value)}`);
|
|
}
|
|
|
|
function renderWorkbenchCacheHitRatio(series: Map<string, CounterSeries>) {
|
|
const groups = new Map<string, { labels: Record<string, string>; hit: number; total: number }>();
|
|
for (const entry of series.values()) {
|
|
const labels = { ...entry.labels };
|
|
const cacheStatus = labels.cache_status;
|
|
delete labels.cache_status;
|
|
const key = stableLabelKey(labels);
|
|
const group = groups.get(key) ?? { labels, hit: 0, total: 0 };
|
|
if (cacheStatus === "hit") group.hit += entry.value;
|
|
group.total += entry.value;
|
|
groups.set(key, group);
|
|
}
|
|
return [...groups.values()].map((group) => `${"workbench_cache_hit_ratio"}{${renderLabels(group.labels)}} ${formatPrometheusValue(group.total > 0 ? group.hit / group.total : 0)}`);
|
|
}
|
|
|
|
function renderHistogram(metricName: string, series: Map<string, HistogramSeries>, buckets: number[]) {
|
|
const lines: string[] = [];
|
|
for (const entry of series.values()) {
|
|
for (let index = 0; index < buckets.length; index += 1) {
|
|
lines.push(`${metricName}_bucket{${renderLabels({ ...entry.labels, le: String(buckets[index]) })}} ${entry.buckets[index]}`);
|
|
}
|
|
lines.push(`${metricName}_bucket{${renderLabels({ ...entry.labels, le: "+Inf" })}} ${entry.count}`);
|
|
lines.push(`${metricName}_sum{${renderLabels(entry.labels)}} ${entry.sum.toFixed(6)}`);
|
|
lines.push(`${metricName}_count{${renderLabels(entry.labels)}} ${entry.count}`);
|
|
}
|
|
return lines;
|
|
}
|
|
|
|
function histogramSampleCount(series: Map<string, HistogramSeries>) {
|
|
return [...series.values()].reduce((sum, entry) => sum + entry.count, 0);
|
|
}
|
|
|
|
function renderLabels(labels: Record<string, string>) {
|
|
return Object.entries(labels).map(([key, value]) => `${key}="${escapeLabelValue(value)}"`).join(",");
|
|
}
|
|
|
|
function stableLabelKey(labels: Record<string, string>) {
|
|
return Object.keys(labels).sort().map((key) => `${key}=${labels[key]}`).join("\u0000");
|
|
}
|
|
|
|
function routeSegmentTemplate(segment: string) {
|
|
if (/^\d+$/u.test(segment)) return ":id";
|
|
if (/^[a-z][a-z0-9]{1,12}_[A-Za-z0-9_.:-]+$/iu.test(segment)) return ":id";
|
|
if (/^[0-9a-f]{12,}$/iu.test(segment)) return ":id";
|
|
if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu.test(segment)) return ":id";
|
|
if (segment.length > 48) return ":id";
|
|
return sanitizePathSegment(segment);
|
|
}
|
|
|
|
function safeUrl(value: string) {
|
|
try { return new URL(value, "http://hwlab-cloud-api.local"); } catch { return new URL("/", "http://hwlab-cloud-api.local"); }
|
|
}
|
|
|
|
function safeDecode(value: string) {
|
|
try { return decodeURIComponent(value); } catch { return value; }
|
|
}
|
|
|
|
function sanitizePathSegment(value: string) {
|
|
const sanitized = value.replace(/[^A-Za-z0-9_.:-]/gu, "_");
|
|
return sanitized.slice(0, 64) || "_";
|
|
}
|
|
|
|
function normalizeMethod(value: unknown) {
|
|
const method = String(value ?? "GET").trim().toUpperCase();
|
|
return /^(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD)$/u.test(method) ? method : "OTHER";
|
|
}
|
|
|
|
function statusClass(value: unknown) {
|
|
const status = Number(value);
|
|
if (!Number.isFinite(status) || status <= 0) return "unknown";
|
|
return `${Math.floor(status / 100)}xx`;
|
|
}
|
|
|
|
function normalizeStatusClass(value: unknown) {
|
|
const text = String(value ?? "").trim().toLowerCase();
|
|
return /^(?:1xx|2xx|3xx|4xx|5xx|network|timeout|unknown)$/u.test(text) ? text : "unknown";
|
|
}
|
|
|
|
function normalizeStatusLabel(value: unknown) {
|
|
const text = sanitizeMetricName(value, "unknown");
|
|
return /^(?:ok|error|timeout|denied|network|cancelled|canceled|unknown|running|pending|completed|failed|blocked|degraded|advanced|unchanged|scheduled|seen|skipped|caught_up|projecting|stale|missing|hit|miss|stored|set_failed|unavailable|disabled)$/u.test(text) ? text : "unknown";
|
|
}
|
|
|
|
function normalizeCacheStatus(value: unknown) {
|
|
const text = normalizeStatusLabel(value);
|
|
return /^(?:hit|miss|stale|skipped|stored|set_failed|unavailable|disabled|error|unknown)$/u.test(text) ? text : "unknown";
|
|
}
|
|
|
|
function normalizeCacheOperation(value: unknown) {
|
|
const text = sanitizeMetricName(value, "read");
|
|
return /^(?:read|get|set|write|delete|ttl|ping)$/u.test(text) ? text : "read";
|
|
}
|
|
|
|
function normalizeCacheKeyClass(value: unknown) {
|
|
const text = sanitizeMetricName(value, "unknown").slice(0, 64);
|
|
return text || "unknown";
|
|
}
|
|
|
|
function normalizeOutcome(value: unknown) {
|
|
const text = sanitizeMetricName(value, "unknown");
|
|
return /^(?:ok|error|timeout|denied|network|cancelled|canceled|unknown)$/u.test(text) ? text : "unknown";
|
|
}
|
|
|
|
function normalizeProjectionStatus(value: unknown) {
|
|
const text = sanitizeMetricName(value, "unknown");
|
|
if (text === "caught_up" || text === "caughtup") return "caught_up";
|
|
return /^(?:projecting|caught_up|blocked|unknown|missing|stale|degraded|terminal|running)$/u.test(text) ? text : "unknown";
|
|
}
|
|
|
|
function isTerminalProjectionStatus(value: unknown) {
|
|
const status = normalizeProjectionStatus(value);
|
|
return status === "caught_up" || status === "terminal";
|
|
}
|
|
|
|
function normalizeReason(value: unknown) {
|
|
return sanitizeMetricName(value, "unknown").slice(0, 64) || "unknown";
|
|
}
|
|
|
|
function normalizeSourceLabel(value: unknown) {
|
|
const text = sanitizeMetricName(value, "unknown");
|
|
if (text === "agentrun_v0_1" || text === "agentrun_v01") return "agentrun_v01";
|
|
return text.slice(0, 64) || "unknown";
|
|
}
|
|
|
|
function normalizeProjectorPhase(value: unknown) {
|
|
const phase = sanitizeMetricName(value, "unknown");
|
|
return /^(?:candidate_scan|agentrun_events_fetch|event_map|trace_append|turn_finalize|session_write|status_effects|unknown)$/u.test(phase) ? phase : "unknown";
|
|
}
|
|
|
|
function normalizeBudgetLabel(value: unknown) {
|
|
const parsed = Number(value);
|
|
if (Number.isFinite(parsed) && parsed > 0) {
|
|
if (parsed <= 2500) return "turn_2_5s";
|
|
if (parsed <= 10000) return "short_10s";
|
|
if (parsed <= 30000) return "medium_30s";
|
|
if (parsed <= 120000) return "long_120s";
|
|
return "long_over_120s";
|
|
}
|
|
return normalizeReason(value ?? "unknown");
|
|
}
|
|
|
|
function agentRunEventCountBucket(value: number) {
|
|
if (value <= 500) return "0_500";
|
|
if (value <= 2000) return "501_2000";
|
|
if (value <= 5000) return "2001_5000";
|
|
return "5000_plus";
|
|
}
|
|
|
|
function sanitizeMetricName(value: unknown, fallback = "unknown") {
|
|
const text = String(value ?? "").trim().toLowerCase().replace(/[^a-z0-9_:-]+/gu, "_").replace(/[-:]+/gu, "_").replace(/^_+|_+$/gu, "");
|
|
return text || fallback;
|
|
}
|
|
|
|
function sanitizeLabelValue(value: unknown, fallback = "unknown") {
|
|
const text = String(value ?? "").trim();
|
|
if (!text) return fallback;
|
|
return text.replace(/[\n\r\t]/gu, " ").slice(0, 120);
|
|
}
|
|
|
|
function escapeLabelValue(value: string) {
|
|
return String(value).replace(/\\/gu, "\\\\").replace(/"/gu, "\\\"").replace(/\n/gu, "\\n");
|
|
}
|
|
|
|
function parsePositiveInteger(value: unknown, fallback: number) {
|
|
const parsed = Number.parseInt(String(value ?? ""), 10);
|
|
return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
|
|
}
|
|
|
|
function boundedDurationMs(value: unknown, maxMs: number) {
|
|
const parsed = Number(value);
|
|
if (!Number.isFinite(parsed) || parsed < 0) return 0;
|
|
return Math.min(parsed, maxMs);
|
|
}
|
|
|
|
function boundedCounterValue(value: unknown) {
|
|
const parsed = Number(value ?? 1);
|
|
if (!Number.isFinite(parsed) || parsed <= 0) return 1;
|
|
return Math.min(Math.floor(parsed), 1_000_000);
|
|
}
|
|
|
|
function finiteNonNegativeNumber(value: unknown): number | null {
|
|
const parsed = Number(value);
|
|
return Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
|
|
}
|
|
|
|
function booleanValue(value: unknown) {
|
|
if (value === true) return true;
|
|
const text = String(value ?? "").trim().toLowerCase();
|
|
return text === "true" || text === "1" || text === "yes";
|
|
}
|
|
|
|
function unixMs(value: unknown): number | null {
|
|
if (value instanceof Date) {
|
|
const time = value.getTime();
|
|
return Number.isFinite(time) ? time : null;
|
|
}
|
|
const numeric = Number(value);
|
|
if (Number.isFinite(numeric) && numeric > 0) return numeric > 10_000_000_000 ? numeric : numeric * 1000;
|
|
const parsed = Date.parse(String(value ?? ""));
|
|
return Number.isFinite(parsed) ? parsed : null;
|
|
}
|
|
|
|
function formatPrometheusValue(value: number) {
|
|
if (!Number.isFinite(value)) return "0";
|
|
return Number.isInteger(value) ? String(value) : value.toFixed(6);
|
|
}
|
|
|
|
function roundDurationMs(value: number) {
|
|
return Math.max(0, value).toFixed(1);
|
|
}
|
|
|
|
function serverTimingToken(value: string) {
|
|
const token = sanitizeMetricName(value, "phase").replace(/_/gu, "-");
|
|
return token || "phase";
|
|
}
|
|
|
|
function nowMs() {
|
|
if (typeof performance !== "undefined" && typeof performance.now === "function") return performance.now();
|
|
return Date.now();
|
|
}
|