@mandujs/core 0.20.7 → 0.20.9

package/src/observability/index.ts

@@ -6,3 +6,13 @@ export {
   type EventHandler,
 } from "./event-bus";
 export { connectLoggerToEventBus } from "./logger-adapter";
+// Phase 6: SQLite 영구 저장 + 시계열 쿼리
+export {
+  startSqliteStore,
+  stopSqliteStore,
+  queryEvents,
+  queryStats,
+  exportJsonl,
+  exportOtlp,
+  type QueryOptions,
+} from "./sqlite-store";

package/src/observability/sqlite-store.ts

@@ -0,0 +1,254 @@
+/**
+ * Phase 6-1: SQLite 영구 저장소
+ *
+ * EventBus 이벤트를 .mandu/observability.db에 저장한다.
+ * Bun 내장 bun:sqlite를 사용하여 추가 의존성 없음.
+ *
+ * - 시계열 쿼리 지원 (Phase 6-2)
+ * - JSONL/OTLP 내보내기 지원 (Phase 6-3)
+ */
+
+import path from "path";
+import fs from "fs";
+import type { ObservabilityEvent, EventType, ObservabilitySeverity } from "./event-bus";
+import { eventBus } from "./event-bus";
+
+interface SqliteDatabase {
+  exec(sql: string): void;
+  prepare(sql: string): {
+    run(...params: unknown[]): { lastInsertRowid: number | bigint };
+    all(...params: unknown[]): unknown[];
+    get(...params: unknown[]): unknown;
+  };
+  close(): void;
+}
+
+let dbInstance: SqliteDatabase | null = null;
+let unsubscribe: (() => void) | null = null;
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS events (
+  id TEXT PRIMARY KEY,
+  correlation_id TEXT,
+  type TEXT NOT NULL,
+  severity TEXT NOT NULL,
+  source TEXT NOT NULL,
+  message TEXT NOT NULL,
+  data TEXT,
+  duration_ms INTEGER,
+  timestamp INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_type ON events(type);
+CREATE INDEX IF NOT EXISTS idx_correlation ON events(correlation_id);
+CREATE INDEX IF NOT EXISTS idx_timestamp ON events(timestamp);
+CREATE INDEX IF NOT EXISTS idx_severity ON events(severity);
+`;
+
+/**
+ * SQLite 저장소 초기화 및 EventBus 구독
+ */
+export async function startSqliteStore(rootDir: string): Promise<void> {
+  if (dbInstance) return; // 이미 시작됨
+
+  const dbDir = path.join(rootDir, ".mandu");
+  const dbPath = path.join(dbDir, "observability.db");
+
+  try {
+    fs.mkdirSync(dbDir, { recursive: true });
+  } catch { /* exists */ }
+
+  // bun:sqlite 동적 import (Bun 환경에서만 동작)
+  let Database: new (path: string) => SqliteDatabase;
+  try {
+    const mod = await import("bun:sqlite");
+    Database = mod.Database as unknown as typeof Database;
+  } catch {
+    console.warn("[Mandu Observability] bun:sqlite unavailable — SQLite store disabled");
+    return;
+  }
+
+  const db = new Database(dbPath);
+  db.exec(SCHEMA);
+  dbInstance = db;
+
+  const insert = db.prepare(`
+    INSERT OR REPLACE INTO events (id, correlation_id, type, severity, source, message, data, duration_ms, timestamp)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+
+  unsubscribe = eventBus.on("*", (event) => {
+    try {
+      insert.run(
+        event.id,
+        event.correlationId ?? null,
+        event.type,
+        event.severity,
+        event.source,
+        event.message,
+        event.data ? JSON.stringify(event.data) : null,
+        event.duration ?? null,
+        event.timestamp,
+      );
+    } catch {
+      // 저장 실패는 silent — 메모리 EventBus는 계속 동작
+    }
+  });
+}
+
+/**
+ * SQLite 저장소 중지
+ */
+export function stopSqliteStore(): void {
+  unsubscribe?.();
+  unsubscribe = null;
+  dbInstance?.close();
+  dbInstance = null;
+}
+
+/**
+ * Phase 6-2: 시계열 쿼리
+ */
+export interface QueryOptions {
+  type?: EventType;
+  severity?: ObservabilitySeverity;
+  source?: string;
+  correlationId?: string;
+  sinceMs?: number;        // 절대 timestamp
+  untilMs?: number;
+  limit?: number;
+}
+
+export function queryEvents(options: QueryOptions = {}): ObservabilityEvent[] {
+  if (!dbInstance) return [];
+
+  const conditions: string[] = [];
+  const params: unknown[] = [];
+
+  if (options.type) { conditions.push("type = ?"); params.push(options.type); }
+  if (options.severity) { conditions.push("severity = ?"); params.push(options.severity); }
+  if (options.source) { conditions.push("source = ?"); params.push(options.source); }
+  if (options.correlationId) { conditions.push("correlation_id = ?"); params.push(options.correlationId); }
+  if (options.sinceMs) { conditions.push("timestamp >= ?"); params.push(options.sinceMs); }
+  if (options.untilMs) { conditions.push("timestamp <= ?"); params.push(options.untilMs); }
+
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const limit = options.limit ?? 100;
+
+  const sql = `SELECT * FROM events ${where} ORDER BY timestamp DESC LIMIT ${limit}`;
+  const rows = dbInstance.prepare(sql).all(...params) as Array<{
+    id: string;
+    correlation_id: string | null;
+    type: string;
+    severity: string;
+    source: string;
+    message: string;
+    data: string | null;
+    duration_ms: number | null;
+    timestamp: number;
+  }>;
+
+  return rows.map((r) => ({
+    id: r.id,
+    correlationId: r.correlation_id ?? undefined,
+    type: r.type as EventType,
+    severity: r.severity as ObservabilitySeverity,
+    source: r.source,
+    message: r.message,
+    data: r.data ? JSON.parse(r.data) : undefined,
+    duration: r.duration_ms ?? undefined,
+    timestamp: r.timestamp,
+  }));
+}
+
+/**
+ * Phase 6-2: 시계열 통계 (시간 window 기반)
+ */
+export function queryStats(windowMs: number): Record<string, { count: number; errors: number; avgDuration: number }> {
+  if (!dbInstance) return {};
+
+  const since = Date.now() - windowMs;
+  const sql = `
+    SELECT
+      type,
+      COUNT(*) as count,
+      SUM(CASE WHEN severity = 'error' THEN 1 ELSE 0 END) as errors,
+      AVG(duration_ms) as avg_duration
+    FROM events
+    WHERE timestamp >= ?
+    GROUP BY type
+  `;
+  const rows = dbInstance.prepare(sql).all(since) as Array<{
+    type: string;
+    count: number;
+    errors: number;
+    avg_duration: number | null;
+  }>;
+
+  const result: Record<string, { count: number; errors: number; avgDuration: number }> = {};
+  for (const r of rows) {
+    result[r.type] = {
+      count: r.count,
+      errors: r.errors,
+      avgDuration: r.avg_duration ?? 0,
+    };
+  }
+  return result;
+}
+
+/**
+ * Phase 6-3: JSONL 내보내기
+ */
+export function exportJsonl(options: QueryOptions = {}): string {
+  const events = queryEvents({ ...options, limit: options.limit ?? 10_000 });
+  return events.map((e) => JSON.stringify(e)).join("\n");
+}
+
+/**
+ * Phase 6-3: OpenTelemetry 호환 JSON 내보내기
+ * (단순화된 trace 형식)
+ */
+export function exportOtlp(options: QueryOptions = {}): string {
+  const events = queryEvents({ ...options, limit: options.limit ?? 10_000 });
+
+  const spans = events.map((e) => ({
+    traceId: e.correlationId ?? e.id,
+    spanId: e.id,
+    name: e.message,
+    kind: "SPAN_KIND_INTERNAL",
+    startTimeUnixNano: BigInt(e.timestamp) * 1_000_000n,
+    endTimeUnixNano: BigInt(e.timestamp + (e.duration ?? 0)) * 1_000_000n,
+    attributes: [
+      { key: "type", value: { stringValue: e.type } },
+      { key: "severity", value: { stringValue: e.severity } },
+      { key: "source", value: { stringValue: e.source } },
+      ...(e.data
+        ? Object.entries(e.data).map(([k, v]) => ({
+            key: k,
+            value: { stringValue: typeof v === "string" ? v : JSON.stringify(v) },
+          }))
+        : []),
+    ],
+    status: { code: e.severity === "error" ? 2 : 1 },
+  }));
+
+  // BigInt → string for JSON serialization
+  return JSON.stringify(
+    {
+      resourceSpans: [
+        {
+          resource: { attributes: [{ key: "service.name", value: { stringValue: "mandu" } }] },
+          scopeSpans: [{ scope: { name: "mandu-observability" }, spans }],
+        },
+      ],
+    },
+    (_k, v) => (typeof v === "bigint" ? v.toString() : v),
+    2,
+  );
+}
+
+/**
+ * 데이터베이스 인스턴스 (테스트용)
+ */
+export function getDb(): SqliteDatabase | null {
+  return dbInstance;
+}

package/src/runtime/server.ts

@@ -40,6 +40,7 @@ import {
 } from "./cors";
 import { validateImportPath } from "./security";
 import { KITCHEN_PREFIX, KitchenHandler, recordRequest } from "../kitchen/kitchen-handler";
+import { eventBus } from "../observability/event-bus";
 import {
   type MiddlewareFn,
   type MiddlewareConfig,
@@ -759,6 +760,103 @@ interface StaticFileResult {
 }
 
 const INTERNAL_CACHE_ENDPOINT = "/_mandu/cache";
+const INTERNAL_EVENTS_ENDPOINT = "/__mandu/events";
+
+function handleEventsStreamRequest(req: Request): Response {
+  const url = new URL(req.url);
+  const filterType = url.searchParams.get("type") || undefined;
+  const filterSeverity = url.searchParams.get("severity") || undefined;
+  const filterSource = url.searchParams.get("source") || undefined;
+  const filterTrace = url.searchParams.get("trace") || undefined;
+
+  const matches = (e: import("../observability/event-bus").ObservabilityEvent): boolean => {
+    if (filterType && e.type !== filterType) return false;
+    if (filterSeverity && e.severity !== filterSeverity) return false;
+    if (filterSource && e.source !== filterSource) return false;
+    if (filterTrace && e.correlationId !== filterTrace) return false;
+    return true;
+  };
+
+  let unsubscribe: (() => void) | null = null;
+  let heartbeat: ReturnType<typeof setInterval> | null = null;
+
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      const encoder = new TextEncoder();
+      const send = (data: string, eventName?: string) => {
+        try {
+          const prefix = eventName ? `event: ${eventName}\n` : "";
+          controller.enqueue(encoder.encode(`${prefix}data: ${data}\n\n`));
+        } catch {
+          // Stream closed
+        }
+      };
+
+      // Replay recent events that match filters
+      const recent = eventBus.getRecent();
+      for (const e of recent) {
+        if (matches(e)) send(JSON.stringify(e));
+      }
+
+      // Subscribe to live events
+      unsubscribe = eventBus.on("*", (event) => {
+        if (matches(event)) send(JSON.stringify(event));
+      });
+
+      // Heartbeat (comment line) every 15s to keep connection alive
+      heartbeat = setInterval(() => {
+        try {
+          controller.enqueue(encoder.encode(`: heartbeat\n\n`));
+        } catch {
+          // ignore
+        }
+      }, 15000);
+
+      // Tear down when client disconnects
+      const signal = req.signal;
+      if (signal) {
+        signal.addEventListener("abort", () => {
+          if (unsubscribe) { unsubscribe(); unsubscribe = null; }
+          if (heartbeat) { clearInterval(heartbeat); heartbeat = null; }
+          try { controller.close(); } catch { /* noop */ }
+        });
+      }
+    },
+    cancel() {
+      if (unsubscribe) { unsubscribe(); unsubscribe = null; }
+      if (heartbeat) { clearInterval(heartbeat); heartbeat = null; }
+    },
+  });
+
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-store, must-revalidate",
+      "Connection": "keep-alive",
+      "X-Accel-Buffering": "no",
+    },
+  });
+}
+
+function handleEventsRecentRequest(req: Request): Response {
+  const url = new URL(req.url);
+  const count = url.searchParams.get("count");
+  const type = url.searchParams.get("type") || undefined;
+  const severity = url.searchParams.get("severity") || undefined;
+  const windowParam = url.searchParams.get("windowMs");
+  const windowMs = windowParam ? Number(windowParam) : undefined;
+
+  const events = eventBus.getRecent(
+    count ? Number(count) : undefined,
+    {
+      type: type as import("../observability/event-bus").EventType | undefined,
+      severity: severity as import("../observability/event-bus").ObservabilitySeverity | undefined,
+    },
+  );
+  const stats = eventBus.getStats(windowMs);
+  return Response.json({ events, stats });
+}
 
 function createStaticErrorResponse(status: 400 | 403 | 404 | 500): Response {
   const body = {
@@ -1021,6 +1119,8 @@ async function handleInternalCacheControlRequest(
 
 async function handleRequest(req: Request, router: Router, registry: ServerRegistry): Promise<Response> {
   const requestStart = Date.now();
+  // Phase 1-4: Correlation ID — 한 요청에서 발생하는 모든 이벤트를 추적
+  const correlationId = req.headers.get("x-mandu-request-id") ?? crypto.randomUUID();
   const result = await handleRequestInternal(req, router, registry);
 
   if (!result.ok) {
@@ -1032,10 +1132,20 @@ async function handleRequest(req: Request, router: Router, registry: ServerRegis
       }
       const url = new URL(req.url);
       const p = url.pathname;
-      if (!p.startsWith("/.mandu/") && !p.startsWith("/__kitchen")) {
+      if (!p.startsWith("/.mandu/") && !p.startsWith("/__kitchen") && !p.startsWith("/__mandu/")) {
         const elapsed = Date.now() - requestStart;
         console.log(`[${new Date().toLocaleTimeString()}] ${req.method} ${p} ${errorResponse.status} ${elapsed}ms`);
-        recordRequest({ id: crypto.randomUUID(), method: req.method, path: p, status: errorResponse.status, duration: elapsed, timestamp: Date.now() });
+        recordRequest({ id: correlationId, method: req.method, path: p, status: errorResponse.status, duration: elapsed, timestamp: Date.now() });
+        // Phase 1-2: HTTP 요청 → EventBus
+        eventBus.emit({
+          type: "http",
+          severity: errorResponse.status >= 500 ? "error" : errorResponse.status >= 400 ? "warn" : "info",
+          source: "server",
+          correlationId,
+          message: `${req.method} ${p} ${errorResponse.status}`,
+          duration: elapsed,
+          data: { method: req.method, path: p, status: errorResponse.status, error: true },
+        });
       }
     }
     return errorResponse;
@@ -1051,13 +1161,23 @@ async function handleRequest(req: Request, router: Router, registry: ServerRegis
       result.value.headers.set("Cache-Control", "no-cache, no-store, must-revalidate");
     }
 
-    if (!p.startsWith("/.mandu/") && !p.startsWith("/__kitchen")) {
+    if (!p.startsWith("/.mandu/") && !p.startsWith("/__kitchen") && !p.startsWith("/__mandu/")) {
       const elapsed = Date.now() - requestStart;
       const status = result.value.status;
       const cacheHdr = result.value.headers.get("X-Mandu-Cache") ?? "";
       const cacheTag = cacheHdr ? ` ${cacheHdr}` : "";
       console.log(`[${new Date().toLocaleTimeString()}] ${req.method} ${p} ${status} ${elapsed}ms${cacheTag}`);
-      recordRequest({ id: crypto.randomUUID(), method: req.method, path: p, status, duration: elapsed, timestamp: Date.now(), cacheStatus: cacheHdr || undefined });
+      recordRequest({ id: correlationId, method: req.method, path: p, status, duration: elapsed, timestamp: Date.now(), cacheStatus: cacheHdr || undefined });
+      // Phase 1-2: HTTP 요청 → EventBus
+      eventBus.emit({
+        type: "http",
+        severity: status >= 500 ? "error" : status >= 400 ? "warn" : "info",
+        source: "server",
+        correlationId,
+        message: `${req.method} ${p} ${status}${cacheTag}`,
+        duration: elapsed,
+        data: { method: req.method, path: p, status, cache: cacheHdr || undefined },
+      });
     }
   }
 
@@ -1688,6 +1808,14 @@ async function handleRequestInternal(
     return ok(await handleInternalCacheControlRequest(req, settings));
   }
 
+  // 1.7. Internal observability EventBus stream + recent snapshot
+  if (pathname === INTERNAL_EVENTS_ENDPOINT) {
+    return ok(handleEventsStreamRequest(req));
+  }
+  if (pathname === `${INTERNAL_EVENTS_ENDPOINT}/recent`) {
+    return ok(handleEventsRecentRequest(req));
+  }
+
   // 2. Kitchen dev dashboard (dev mode only)
   if (settings.isDev && pathname.startsWith(KITCHEN_PREFIX) && registry.kitchen) {
     const kitchenResponse = await registry.kitchen.handle(req, pathname);