Files
0pt/src/analytics/slo/usage-events.ts
T
Claude Opus 5 ed6e62809d
CI (SIAX Cloud) / quality (push) Successful in 54s
CI (SIAX Cloud) / integration (push) Successful in 49s
CI (SIAX Cloud) / security (push) Successful in 28s
Security Scan (SIAX Cloud) / security (push) Successful in 30s
CI (SIAX Cloud) / quality (pull_request) Successful in 58s
CI (SIAX Cloud) / integration (pull_request) Successful in 1m6s
CI (SIAX Cloud) / security (pull_request) Successful in 33s
Security Scan (SIAX Cloud) / security (pull_request) Successful in 39s
feat(analytics): BI-P103 — BI SLOs measured from AUD0's usage events, or declared unmeasured
aud0#34 merged seven BI usage event types and recorded that zero producers
emit them. This makes 0pt the producer and derives the SLOs from those events
rather than opening a second, private measurement path that would disagree
with aud0 during an incident.

Three honest verdicts instead of one number:

  insufficient_data     an availability objective over an empty window is
                        SILENCE, not 100%. Every objective in an empty window
                        comes back insufficient_data and fully_measured is
                        false. A started query with no terminal event counts
                        as unresolved — not as a success.
  not_measurable_here   dashboard FRESHNESS is a property of the dataset
                        (BI-P026/BI-P105 watermark) and report DELIVERY is
                        N0TIFY's receipt. Neither is in aud0's seven types, so
                        both are declared unmeasured rather than proxied by
                        completion.
  low_confidence        a p99 over 12 samples is the 12th-slowest request
                        wearing a percentile's clothes. Reported with its
                        sample size and not judged.

The producer is an allowlist built field by named field, never a spread. The
test feeds it an execution record carrying SQL text, a database error message
quoting a personnummer, filter VALUES, a tenant id and a result sample, then
greps the emitted events — after first proving the grep finds those strings in
the input, so a clean result cannot be a broken detector.

14 tests.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-07 04:01:16 +02:00

210 lines
7.1 KiB
TypeScript

/**
* src/analytics/slo/usage-events.ts
* ==================================
* BI-P103's measurement path: 0pt emits the AUD0 BI usage events (aud0#34,
* BI-P076) that the SLO evaluator then reads.
*
* aud0 says it plainly in docs/BI_ANALYTICS_USAGE.md: "Zero real producers
* emit these seven types today." An SLO computed from a second, private
* telemetry path would be a number nobody else can audit, so 0pt becomes a
* producer instead of inventing one.
*
* THE PAYLOAD IS AN ALLOWLIST, BUILT FIELD BY NAMED FIELD. AUD0's ingest
* refuses result-bearing payloads with a 400 and its schemas are `.strict()`,
* so a leak here is a 400 rather than a breach — but a producer that has to be
* refused is a producer that is broken. `biUsageEventsForExecution` therefore
* never spreads an execution record; it names each field, and
* tests/analytics/bi-slo.test.ts feeds it a record carrying SQL text, an error
* message, a tenant id and a result sample, then asserts none of it appears in
* the output.
*
* WHAT IS DELIBERATELY NOT SENT: `compiled_query_hash` goes out as
* `query_hash` (aud0 requires a 64-hex digest and nothing else), the statement
* never leaves 0pt at all, `error_code` travels but `error_message` does not,
* and `row_count` travels but no row does.
*/
/** The seven event types, named exactly as aud0 registers them. */
export const AUD0_BI_EVENT_TYPES = [
'aud0.analytics_query_started',
'aud0.analytics_query_completed',
'aud0.analytics_query_failed',
'aud0.dashboard_viewed',
'aud0.report_generated',
'aud0.dataset_exported',
'aud0.metric_queried',
] as const;
export type Aud0BiEventType = (typeof AUD0_BI_EVENT_TYPES)[number];
/** aud0's closed surface list (BI_SURFACES). */
export const BI_SURFACES = ['dashboard', 'report', 'explore', 'api', 'scheduled', 'notebook'] as const;
export type BiSurface = (typeof BI_SURFACES)[number];
export interface Aud0BiEvent {
event_type: Aud0BiEventType;
/** Bounded, allowlisted metadata. Never a result, a statement or a message. */
payload: Record<string, string | number | boolean | string[]>;
/** Occurrence time, used by the SLO window. */
occurred_at: string;
}
/**
* The 0pt-side view of one execution. Intentionally a SUPERSET of what may be
* emitted — it carries the fields 0pt genuinely has, including the ones that
* must never leave — so that the mapping below is a real filter rather than a
* rename.
*/
export interface ExecutionTelemetry {
query_id: string;
/** 64-hex; anything else is dropped rather than reshaped. */
compiled_query_hash?: string;
/** NEVER emitted. Present here because 0pt has it. */
compiled_sql?: string;
/** NEVER emitted. */
error_message?: string;
error_code?: string;
/** NEVER emitted — a consumer must not be able to name a tenant, BI-P016. */
tenant_id?: string;
dataset_id?: string;
engine?: string;
surface?: BiSurface;
state: 'succeeded' | 'failed' | 'cancelled' | 'running';
started_at: string;
finished_at?: string;
duration_ms?: number;
row_count?: number;
bytes_scanned?: number;
cache_hit?: boolean;
filter_keys?: string[];
/** NEVER emitted: filter VALUES are facts about a subject. */
filter_values?: Record<string, string[]>;
/** NEVER emitted. */
result_sample?: unknown;
metric_name?: string;
dimension_keys?: string[];
granularity?: string;
dashboard_id?: string;
widget_count?: number;
}
const SHA256 = /^[0-9a-f]{64}$/;
const MAX_KEY_NAMES = 50;
const MAX_SHORT_TEXT = 120;
function shortText(v: string | undefined): string | undefined {
if (!v) return undefined;
return v.slice(0, MAX_SHORT_TEXT);
}
function keyNames(v: string[] | undefined): string[] | undefined {
if (!v || v.length === 0) return undefined;
return v.slice(0, MAX_KEY_NAMES).map((k) => k.slice(0, MAX_SHORT_TEXT));
}
function put(
payload: Record<string, string | number | boolean | string[]>,
key: string,
value: string | number | boolean | string[] | undefined,
): void {
if (value === undefined) return;
payload[key] = value;
}
/**
* Map one execution to its AUD0 usage events.
*
* A running execution emits only `started`: a query that has not finished is
* neither a success nor a failure, and the SLO evaluator counts it as
* unresolved rather than quietly as one or the other.
*/
export function biUsageEventsForExecution(t: ExecutionTelemetry): Aud0BiEvent[] {
const base: Record<string, string | number | boolean | string[]> = {};
put(base, 'query_id', t.query_id);
if (t.compiled_query_hash && SHA256.test(t.compiled_query_hash)) {
put(base, 'query_hash', t.compiled_query_hash);
}
put(base, 'dataset_id', t.dataset_id);
put(base, 'engine', shortText(t.engine));
put(base, 'surface', t.surface);
put(base, 'filter_keys', keyNames(t.filter_keys));
const events: Aud0BiEvent[] = [
{ event_type: 'aud0.analytics_query_started', payload: { ...base }, occurred_at: t.started_at },
];
if (t.state === 'succeeded') {
const payload = { ...base };
put(payload, 'duration_ms', t.duration_ms);
put(payload, 'row_count', t.row_count);
put(payload, 'bytes_scanned', t.bytes_scanned);
put(payload, 'cache_hit', t.cache_hit);
events.push({
event_type: 'aud0.analytics_query_completed',
payload,
occurred_at: t.finished_at ?? t.started_at,
});
} else if (t.state === 'failed' || t.state === 'cancelled') {
const payload = { ...base };
put(payload, 'duration_ms', t.duration_ms);
// A CODE. `error_message` is never mapped, at any length.
put(
payload,
'error_code',
shortText(t.error_code ?? (t.state === 'cancelled' ? 'CANCELLED' : undefined)),
);
events.push({
event_type: 'aud0.analytics_query_failed',
payload,
occurred_at: t.finished_at ?? t.started_at,
});
}
if (t.metric_name) {
const payload: Record<string, string | number | boolean | string[]> = {};
put(payload, 'metric_name', shortText(t.metric_name));
put(payload, 'dataset_id', t.dataset_id);
put(payload, 'surface', t.surface);
put(payload, 'engine', shortText(t.engine));
put(payload, 'dimension_keys', keyNames(t.dimension_keys));
put(payload, 'granularity', shortText(t.granularity));
put(payload, 'row_count', t.row_count);
put(payload, 'duration_ms', t.duration_ms);
events.push({
event_type: 'aud0.metric_queried',
payload,
occurred_at: t.finished_at ?? t.started_at,
});
}
if (t.dashboard_id) {
const payload: Record<string, string | number | boolean | string[]> = {};
put(payload, 'dashboard_id', t.dashboard_id);
put(payload, 'widget_count', t.widget_count);
put(payload, 'duration_ms', t.duration_ms);
put(payload, 'surface', t.surface ?? 'dashboard');
events.push({ event_type: 'aud0.dashboard_viewed', payload, occurred_at: t.started_at });
}
return events;
}
/** Every payload key this producer can ever emit. Pinned by test. */
export const EMITTABLE_PAYLOAD_KEYS = [
'query_id',
'query_hash',
'dataset_id',
'engine',
'surface',
'filter_keys',
'duration_ms',
'row_count',
'bytes_scanned',
'cache_hit',
'error_code',
'metric_name',
'dimension_keys',
'granularity',
'dashboard_id',
'widget_count',
] as const;