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
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>
210 lines
7.1 KiB
TypeScript
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;
|