Files
waggle-os/packages/core/src/telemetry.ts
Oleg Maslov 0c3e2ead3b
Some checks failed
Installer Smoke / installer-smoke (push) Has been cancelled
moving
2026-09-02 10:10:29 +02:00

325 lines
11 KiB
TypeScript

/**
* TelemetryStore — local, privacy-first event tracking.
*
* All data stays in ~/.waggle/telemetry.db (SQLite).
* Default: OFF. User opts in via Settings toggle.
* No cloud reporting in M2 — data is queryable via local API only.
*
* NEVER tracked: message content, memory content, file paths,
* API keys, personal info, IP addresses, device IDs.
*/
import Database from 'better-sqlite3';
import type { Database as DatabaseType } from 'better-sqlite3';
import path from 'node:path';
import fs from 'node:fs';
/* ── Schema ── */
const TELEMETRY_SCHEMA = `
CREATE TABLE IF NOT EXISTS telemetry_events (
id INTEGER PRIMARY KEY AUTOINCREMENT,
event TEXT NOT NULL,
properties TEXT NOT NULL DEFAULT '{}',
created_at TEXT NOT NULL DEFAULT (datetime('now'))
);
CREATE INDEX IF NOT EXISTS idx_telemetry_event ON telemetry_events (event, created_at);
CREATE INDEX IF NOT EXISTS idx_telemetry_date ON telemetry_events (created_at);
`;
/* ── Event constants ── */
export const TELEMETRY_EVENTS = {
// Onboarding funnel
ONBOARDING_START: 'onboarding_start',
ONBOARDING_STEP: 'onboarding_step',
ONBOARDING_COMPLETE: 'onboarding_complete',
ONBOARDING_SKIP: 'onboarding_skip',
// Session engagement
SESSION_START: 'session_start',
SESSION_END: 'session_end',
// Infrastructure
EMBEDDING_PROVIDER: 'embedding_provider',
LLM_PROVIDER: 'llm_provider',
// Feature usage
TEMPLATE_SELECTED: 'template_selected',
WORKSPACE_CREATED: 'workspace_created',
FIRST_AGENT_RESPONSE: 'first_agent_response',
SLASH_COMMAND_USED: 'slash_command_used',
// App lifecycle
APP_START: 'app_start',
APP_ERROR: 'app_error',
} as const;
/* ── Types ── */
export interface TelemetryEvent {
id: number;
event: string;
properties: Record<string, unknown>;
created_at: string;
}
export interface TelemetrySummary {
enabled: boolean;
totalEvents: number;
firstEvent: string | null;
lastEvent: string | null;
onboardingCompleted: boolean;
totalSessions: number;
embeddingProvider: string | null;
templatesUsed: string[];
eventBreakdown: Record<string, number>;
}
/* ── Store ── */
export class TelemetryStore {
private db: DatabaseType;
private enabled: boolean;
constructor(dataDir: string, enabled = false) {
this.enabled = enabled;
const dbPath = path.join(dataDir, 'telemetry.db');
this.db = new Database(dbPath);
this.db.pragma('journal_mode = WAL');
this.db.exec(TELEMETRY_SCHEMA);
}
/** Track an event. No-op if telemetry is disabled. */
track(event: string, properties?: Record<string, unknown>): void {
if (!this.enabled) return;
this.db.prepare(
'INSERT INTO telemetry_events (event, properties) VALUES (?, ?)'
).run(event, JSON.stringify(properties ?? {}));
}
/** Enable/disable telemetry at runtime. */
setEnabled(enabled: boolean): void {
this.enabled = enabled;
}
/** Whether telemetry is currently enabled. */
isEnabled(): boolean {
return this.enabled;
}
/** Get aggregated summary. */
getSummary(): TelemetrySummary {
const total = (this.db.prepare(
'SELECT COUNT(*) as cnt FROM telemetry_events'
).get() as { cnt: number }).cnt;
const first = this.db.prepare(
'SELECT MIN(created_at) as d FROM telemetry_events'
).get() as { d: string | null };
const last = this.db.prepare(
'SELECT MAX(created_at) as d FROM telemetry_events'
).get() as { d: string | null };
const onboarded = (this.db.prepare(
"SELECT COUNT(*) as cnt FROM telemetry_events WHERE event = 'onboarding_complete'"
).get() as { cnt: number }).cnt > 0;
const sessions = (this.db.prepare(
"SELECT COUNT(*) as cnt FROM telemetry_events WHERE event = 'session_start'"
).get() as { cnt: number }).cnt;
const embRow = this.db.prepare(
"SELECT properties FROM telemetry_events WHERE event = 'embedding_provider' ORDER BY created_at DESC LIMIT 1"
).get() as { properties: string } | undefined;
const embProvider = embRow
? (JSON.parse(embRow.properties) as Record<string, unknown>).provider as string ?? null
: null;
const tplRows = this.db.prepare(
"SELECT DISTINCT json_extract(properties, '$.templateId') as tid FROM telemetry_events WHERE event IN ('template_selected', 'workspace_created') AND json_extract(properties, '$.templateId') IS NOT NULL"
).all() as Array<{ tid: string }>;
const breakdownRows = this.db.prepare(
'SELECT event, COUNT(*) as cnt FROM telemetry_events GROUP BY event ORDER BY cnt DESC'
).all() as Array<{ event: string; cnt: number }>;
const breakdown: Record<string, number> = {};
for (const row of breakdownRows) {
breakdown[row.event] = row.cnt;
}
return {
enabled: this.enabled,
totalEvents: total,
firstEvent: first.d,
lastEvent: last.d,
onboardingCompleted: onboarded,
totalSessions: sessions,
embeddingProvider: embProvider,
templatesUsed: tplRows.map(r => r.tid),
eventBreakdown: breakdown,
};
}
/** Get raw events with optional filters. */
getEvents(options?: { event?: string; since?: string; until?: string; limit?: number }): TelemetryEvent[] {
const conditions: string[] = [];
const params: unknown[] = [];
if (options?.event) {
conditions.push('event = ?');
params.push(options.event);
}
if (options?.since) {
conditions.push('created_at >= ?');
params.push(options.since);
}
if (options?.until) {
conditions.push('created_at <= ?');
params.push(options.until);
}
const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
const limit = options?.limit ?? 100;
const rows = this.db.prepare(
`SELECT id, event, properties, created_at FROM telemetry_events ${where} ORDER BY created_at DESC LIMIT ?`
).all(...params, limit) as Array<{ id: number; event: string; properties: string; created_at: string }>;
return rows.map(r => ({
id: r.id,
event: r.event,
properties: JSON.parse(r.properties) as Record<string, unknown>,
created_at: r.created_at,
}));
}
/** Delete all telemetry data (user right-to-delete). */
clear(): { deleted: number } {
const result = this.db.prepare('DELETE FROM telemetry_events').run();
return { deleted: result.changes };
}
/** Close the database connection. */
close(): void {
this.db.close();
}
}
/* ── Collector ── */
const COLLECTOR_SCHEMA = `
CREATE TABLE IF NOT EXISTS collector_events (
id INTEGER PRIMARY KEY AUTOINCREMENT,
category TEXT NOT NULL,
name TEXT NOT NULL,
count INTEGER NOT NULL DEFAULT 1,
date TEXT NOT NULL,
created_at TEXT NOT NULL DEFAULT (datetime('now'))
);
CREATE INDEX IF NOT EXISTS idx_collector_date ON collector_events (date);
CREATE UNIQUE INDEX IF NOT EXISTS idx_collector_name_date ON collector_events (name, date);
`;
/**
* TelemetryCollector — higher-level daily-aggregated event tracker.
*
* Records tool usage, commands, errors, and capability gaps by day.
* Privacy-safe: only category + name + count, no content or PII.
*/
export class TelemetryCollector {
private db: DatabaseType;
private enabled: boolean;
private dataDir: string;
constructor(dataDir: string, enabled = false) {
this.dataDir = dataDir;
this.enabled = enabled;
const dbPath = path.join(dataDir, 'telemetry.db');
this.db = new Database(dbPath);
this.db.pragma('journal_mode = WAL');
this.db.exec(COLLECTOR_SCHEMA);
}
recordToolUse(toolName: string): void {
if (!this.enabled) return;
this.upsertEvent('tool', toolName);
}
recordCommand(command: string): void {
if (!this.enabled) return;
this.upsertEvent('command', command);
}
recordError(errorName: string): void {
if (!this.enabled) return;
this.upsertEvent('error', errorName);
}
recordCapabilityGap(capability: string): void {
if (!this.enabled) return;
this.upsertEvent('capability_gap', capability);
}
recordSession(durationMs: number, interactionCount: number): void {
if (!this.enabled) return;
const today = new Date().toISOString().split('T')[0];
this.db.prepare(
`INSERT INTO collector_events (category, name, count, date) VALUES ('session', 'duration_total_ms', ?, ?)
ON CONFLICT(name, date) DO UPDATE SET count = count + excluded.count`
).run(durationMs, today);
this.db.prepare(
`INSERT INTO collector_events (category, name, count, date) VALUES ('session', 'interaction_count', ?, ?)
ON CONFLICT(name, date) DO UPDATE SET count = count + excluded.count`
).run(interactionCount, today);
this.db.prepare(
`INSERT INTO collector_events (category, name, count, date) VALUES ('session', 'session_count', 1, ?)
ON CONFLICT(name, date) DO UPDATE SET count = count + 1`
).run(today);
}
private upsertEvent(category: string, name: string): void {
const today = new Date().toISOString().split('T')[0];
this.db.prepare(
`INSERT INTO collector_events (category, name, count, date) VALUES (?, ?, 1, ?)
ON CONFLICT(name, date) DO UPDATE SET count = count + 1`
).run(category, name, today);
}
getReport(days = 7): {
totalEvents: number;
events: Array<{ name: string; count: number; category: string; date: string }>;
dateRange: { from: string | null };
} {
const since = new Date();
since.setDate(since.getDate() - days);
const sinceStr = since.toISOString().split('T')[0];
const rows = this.db.prepare(
`SELECT name, SUM(count) as total_count, category, date
FROM collector_events WHERE date >= ?
GROUP BY name, category, date ORDER BY date DESC, name`
).all(sinceStr) as Array<{ name: string; total_count: number; category: string; date: string }>;
const totalEvents = rows.reduce((sum, r) => sum + r.total_count, 0);
const events = rows.map(r => ({ name: r.name, count: r.total_count, category: r.category, date: r.date }));
const firstRow = this.db.prepare(
'SELECT MIN(date) as first_date FROM collector_events'
).get() as { first_date: string | null };
return { totalEvents, events, dateRange: { from: firstRow.first_date } };
}
/** Write events to telemetry.json for external consumption. */
flush(): void {
const rows = this.db.prepare(
'SELECT name, count, category, date FROM collector_events ORDER BY date DESC, name'
).all() as Array<{ name: string; count: number; category: string; date: string }>;
fs.writeFileSync(
path.join(this.dataDir, 'telemetry.json'),
JSON.stringify(rows, null, 2),
);
}
setEnabled(enabled: boolean): void { this.enabled = enabled; }
isEnabled(): boolean { return this.enabled; }
close(): void { this.db.close(); }
}