@growth-labs/monitoring 0.1.0 → 0.1.1

package/src/tail/index.ts

@@ -0,0 +1,71 @@
+import { createAlerter } from '../alerting/index.js'
+import {
+	errorMessage,
+	type NotifyConfig,
+	type SamplingConfig,
+	type TailAlertingConfig,
+} from '../types.js'
+import { categorize, type TraceItem } from './categorize.js'
+import { computeFingerprint } from './fingerprint.js'
+import { persistErrorEvent } from './persist.js'
+import { redact } from './redact.js'
+import { shouldKeep } from './sample.js'
+
+export interface TailWorkerConfig {
+	realmId: string
+	d1Binding: string
+	waeBinding: string
+	notifyConfig: NotifyConfig
+	alertingConfig?: TailAlertingConfig
+	sampling: SamplingConfig
+}
+
+export function createTailWorker(config: TailWorkerConfig) {
+	const alerter = createAlerter({
+		notifyConfig: config.notifyConfig,
+		alertingConfig: config.alertingConfig,
+	})
+
+	async function tailHandler(events: TraceItem[], env: Record<string, unknown>): Promise<void> {
+		const db = env[config.d1Binding] as D1Database | undefined
+		const wae = env[config.waeBinding] as
+			| { writeDataPoint(dataPoint: unknown): unknown }
+			| undefined
+		if (!db) {
+			console.error(`[monitoring] missing D1 binding env.${config.d1Binding}`)
+			return
+		}
+		for (const traceEvent of events) {
+			for (const rawEvent of categorize(traceEvent, {
+				slowRequestThresholdMs: config.sampling.slowRequestThresholdMs,
+			})) {
+				try {
+					const fingerprint = await computeFingerprint(rawEvent)
+					const withFingerprint = { ...rawEvent, fingerprint }
+					if (
+						!shouldKeep(withFingerprint.category, config.sampling, {
+							surface: withFingerprint.surface,
+							activeIncidentSurfaces: alerter.activeIncidentSurfaces,
+						})
+					) {
+						continue
+					}
+					const redacted = redact(withFingerprint) as typeof withFingerprint
+					await persistErrorEvent(db, wae, { realmId: config.realmId }, redacted)
+					await alerter.handleErrorEvent(withFingerprint, db, env)
+				} catch (error) {
+					console.error(`[monitoring] failed to process tail event: ${errorMessage(error)}`)
+				}
+			}
+		}
+	}
+
+	return { tail: tailHandler, tailHandler }
+}
+
+export type { CategorizedEvent, ErrorCategory, TraceItem } from './categorize.js'
+export { categorize, normalizePath } from './categorize.js'
+export { computeFingerprint, normalizeMessage } from './fingerprint.js'
+export { persistErrorEvent, severityFromCategory } from './persist.js'
+export { redact, redactString, redactSurface } from './redact.js'
+export { shouldKeep } from './sample.js'

package/src/tail/persist.ts

@@ -0,0 +1,93 @@
+import { type ErrorSeverity, errorMessage, generateId, type IdFactory } from '../types.js'
+import type { CategorizedEvent, ErrorCategory } from './categorize.js'
+
+interface PersistConfig {
+	realmId: string
+}
+
+interface AnalyticsEngineBinding {
+	writeDataPoint(dataPoint: unknown): Promise<unknown> | unknown
+}
+
+export interface FingerprintedEvent extends CategorizedEvent {
+	fingerprint: string
+}
+
+export async function persistErrorEvent(
+	db: D1Database,
+	wae: AnalyticsEngineBinding | undefined,
+	config: PersistConfig,
+	event: FingerprintedEvent,
+	idFactory: IdFactory = generateId,
+): Promise<void> {
+	const severity = severityFromCategory(event.category)
+	try {
+		await db
+			.prepare(`
+				INSERT INTO gl_errors
+					(id, realm_key, surface, severity, message, stack, request_id, status_code, duration_ms, occurred_at, fingerprint)
+				VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+			`)
+			.bind(
+				idFactory(),
+				config.realmId,
+				event.surface,
+				severity,
+				event.message,
+				event.stack ?? null,
+				event.requestId ?? null,
+				event.statusCode ?? null,
+				event.durationMs ?? null,
+				Math.floor(event.occurredAt / 1000),
+				event.fingerprint,
+			)
+			.run()
+	} catch (error) {
+		console.error(`[monitoring] failed to persist error event: ${errorMessage(error)}`)
+	}
+
+	if (!wae) return
+	try {
+		await wae.writeDataPoint({
+			blobs: [
+				severity,
+				config.realmId,
+				'',
+				'',
+				event.surface,
+				'',
+				'',
+				'',
+				'',
+				'',
+				'',
+				'',
+				'',
+				'',
+				'',
+				'',
+				'',
+				event.category,
+				event.fingerprint,
+				'',
+			],
+			doubles: [event.occurredAt, event.statusCode ?? 0, event.durationMs ?? 0],
+			indexes: [severity],
+		})
+	} catch (error) {
+		console.error(`[monitoring] failed to write WAE error event: ${errorMessage(error)}`)
+	}
+}
+
+export function severityFromCategory(category: ErrorCategory): ErrorSeverity {
+	switch (category) {
+		case 'exception':
+			return 'exception'
+		case 'console-warn':
+		case 'slow-request':
+			return 'warning'
+		case 'fivexx':
+		case 'console-error':
+			return 'error'
+	}
+}

package/src/tail/redact.ts

@@ -0,0 +1,30 @@
+import type { CategorizedEvent } from './categorize.js'
+
+const MAX_MESSAGE_LENGTH = 2000
+const MAX_STACK_LENGTH = 4000
+
+export function redact(event: CategorizedEvent): CategorizedEvent {
+	return {
+		...event,
+		message: truncate(redactString(event.message), MAX_MESSAGE_LENGTH),
+		stack: event.stack ? truncate(redactString(event.stack), MAX_STACK_LENGTH) : undefined,
+		surface: redactSurface(event.surface),
+	}
+}
+
+export function redactString(value: string): string {
+	return value
+		.replace(/\b[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\b/g, '[redacted-email]')
+		.replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, '[redacted-jwt]')
+		.replace(/\bcfut_[A-Za-z0-9_-]+\b/g, '[redacted-cf-token]')
+		.replace(/\bsk-[A-Za-z0-9_-]{20,}\b/g, '[redacted-api-key]')
+		.replace(/\b(?=[A-Za-z0-9]{32,}\b)(?=[A-Za-z0-9]*\d)[A-Za-z0-9]+\b/g, '[redacted-token]')
+}
+
+export function redactSurface(surface: string): string {
+	return surface.replace(/\?[^\s]+/, '')
+}
+
+function truncate(value: string, maxLength: number): string {
+	return value.length > maxLength ? value.slice(0, maxLength) : value
+}

package/src/tail/sample.ts

@@ -0,0 +1,34 @@
+import type { SamplingConfig } from '../types.js'
+import type { ErrorCategory } from './categorize.js'
+
+interface SamplingOptions {
+	surface?: string
+	activeIncidentSurfaces?: Set<string>
+}
+
+export function shouldKeep(
+	category: ErrorCategory,
+	config: SamplingConfig,
+	options: SamplingOptions = {},
+): boolean {
+	if (options.surface && options.activeIncidentSurfaces?.has(options.surface)) return true
+	const pct = pctForCategory(category, config)
+	if (pct >= 1) return true
+	if (pct <= 0) return false
+	return Math.random() < pct
+}
+
+function pctForCategory(category: ErrorCategory, config: SamplingConfig): number {
+	switch (category) {
+		case 'exception':
+			return config.exceptionsPct
+		case 'fivexx':
+			return config.fivexxPct
+		case 'console-error':
+			return config.consoleErrorPct
+		case 'console-warn':
+			return config.consoleWarnPct
+		case 'slow-request':
+			return config.slowRequestsPct
+	}
+}

package/src/types.ts

@@ -0,0 +1,111 @@
+export type CheckType = 'get' | 'post' | 'happy_path'
+export type CheckStatus = 'pass' | 'fail' | 'timeout'
+export type AlertSeverity = 'info' | 'warning' | 'critical'
+export type ErrorSeverity = 'error' | 'warning' | 'exception'
+
+export interface CheckResult {
+	id?: string
+	status: CheckStatus
+	statusCode?: number
+	latencyMs: number
+	errorMessage?: string
+	checkedAt?: number
+}
+
+export interface PersistedCheckResult extends CheckResult {
+	id: string
+	checkedAt: number
+}
+
+export interface NotifyConfig {
+	channels: Array<'slack' | 'email'>
+	emailProvider?: 'cloudflare' | 'resend'
+}
+
+export interface ProbeAlertingConfig {
+	consecutiveFailuresToOpen?: number
+	consecutiveSuccessesToClose?: number
+	minSeverity?: 'warning' | 'critical'
+}
+
+export interface TailAlertingConfig {
+	newErrorDedupWindowMs?: number
+	rateSpikeThreshold?: number
+	rateSpikeWindowMs?: number
+	surfaceDownThresholdPct?: number
+	surfaceDownWindowMs?: number
+}
+
+export interface ThresholdConfig extends ProbeAlertingConfig, TailAlertingConfig {}
+
+export interface SamplingConfig {
+	exceptionsPct: number
+	fivexxPct: number
+	consoleErrorPct: number
+	consoleWarnPct: number
+	slowRequestsPct: number
+	slowRequestThresholdMs: number
+}
+
+export interface RuntimeFetch {
+	fetcher?: typeof fetch
+}
+
+export interface UptimeIncident {
+	id: string
+	surface: string
+	opened_at: number
+	closed_at: number | null
+	trigger_check_id: string | null
+	resolve_check_id: string | null
+	severity: 'warning' | 'critical'
+	notes: string | null
+}
+
+export interface SurfaceStatus {
+	name: string
+	status: 'green' | 'yellow' | 'red'
+	lastCheckedAt: number | null
+	uptime7d: number
+}
+
+export interface ErrorRollup {
+	fingerprint: string
+	surface: string
+	message: string
+	count: number
+	lastOccurredAt: number
+}
+
+export interface StatusPageSurfaceConfig {
+	name: string
+}
+
+export interface StatusPageConfig {
+	realm: string
+	d1Binding?: string
+	surfaces: StatusPageSurfaceConfig[]
+}
+
+export interface ScheduledEventLike {
+	cron: string
+}
+
+export interface ExecutionContextLike {
+	waitUntil(promise: Promise<unknown>): void
+}
+
+export type IdFactory = () => string
+
+export function generateId(): string {
+	return crypto.randomUUID()
+}
+
+export function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error)
+}
+
+export function isTimeoutMessage(message: string): boolean {
+	const lower = message.toLowerCase()
+	return lower.includes('timed out') || lower.includes('timeout') || lower.includes('aborted')
+}

package/src/virtual.d.ts

@@ -0,0 +1,4 @@
+declare module 'virtual:growth-labs/monitoring/status-page/config' {
+	import type { StatusPageConfig } from './types.js'
+	export const config: Required<Pick<StatusPageConfig, 'realm' | 'd1Binding' | 'surfaces'>>
+}