@composed-di/observability 0.5.0-alpha → 0.7.0-alpha

package/src/dashboardInstrumentation.ts

@@ -0,0 +1,153 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { performance } from 'node:perf_hooks'
+import { ServiceInstrumentation } from '@composed-di/instrumentation-core'
+import type {
+  DisposeContext,
+  OperationSpan,
+  InitializeContext,
+  MethodCallContext,
+} from '@composed-di/instrumentation-core'
+import { SpanEvent, SpanKind } from './events'
+
+/** The span context propagated across sync and async call boundaries. */
+interface SpanContext {
+  id: number
+}
+
+export interface DashboardInstrumentationOptions {
+  /** Longest serialized value kept; longer ones are truncated. Default 200. */
+  maxValueLength?: number
+}
+
+/**
+ * A ServiceInstrumentation that turns service events into structured
+ * start/end span events for the realtime dashboard.
+ *
+ * - Uses AsyncLocalStorage to link spans to the span that was active when
+ *   they started, which lets the dashboard draw cross-service call edges
+ *   (e.g. UserService.getUser -> Database.query). The observed operation
+ *   is invoked through the span's `run` wrapper, so the context is scoped
+ *   to the operation and its async continuations.
+ * - Emits events synchronously to subscribers; it never buffers.
+ *
+ * Arguments and results are serialized onto spans exactly when
+ * `instrument()` (inherited from ServiceInstrumentation) delivers them —
+ * capture and redaction policy live in the InstrumentOptions, not here.
+ * Pass `capture: { arguments: true, results: true }` there to see values
+ * in the dashboard.
+ */
+export class DashboardInstrumentation extends ServiceInstrumentation {
+  private readonly context = new AsyncLocalStorage<SpanContext>()
+  private readonly listeners = new Set<(event: SpanEvent) => void>()
+  private nextId = 1
+  private readonly maxValueLength: number
+
+  constructor({ maxValueLength = 200 }: DashboardInstrumentationOptions = {}) {
+    super()
+    this.maxValueLength = maxValueLength
+  }
+
+  /**
+   * Subscribes to span events.
+   *
+   * @returns A function that removes the subscription.
+   */
+  subscribe(listener: (event: SpanEvent) => void): () => void {
+    this.listeners.add(listener)
+    return () => this.listeners.delete(listener)
+  }
+
+  onInitialize({ key }: InitializeContext): OperationSpan {
+    return this.startSpan(key.name, 'initialize', 'initialize')
+  }
+
+  onDispose({ key }: DisposeContext): OperationSpan {
+    return this.startSpan(key.name, 'dispose', 'dispose')
+  }
+
+  onMethodCall({ key, methodName, args }: MethodCallContext): OperationSpan {
+    // Args are present exactly when argument capture is enabled in the
+    // InstrumentOptions; they arrive already redacted.
+    return this.startSpan(
+      key.name,
+      methodName,
+      'call',
+      args ? this.serialize(args) : undefined,
+    )
+  }
+
+  private startSpan(
+    service: string,
+    method: string,
+    kind: SpanKind,
+    args?: string,
+  ): OperationSpan {
+    const id = this.nextId++
+    const parent = this.context.getStore()
+
+    this.emit({
+      type: 'start',
+      id,
+      parentId: parent?.id ?? null,
+      name: `${service}.${method}`,
+      service,
+      method,
+      kind,
+      time: Date.now(),
+      args,
+    })
+
+    const startedAt = performance.now()
+    let ended = false
+    const end = (error: string | null, result?: string) => {
+      if (ended) return
+      ended = true
+      this.emit({
+        type: 'end',
+        id,
+        time: Date.now(),
+        durationMs: performance.now() - startedAt,
+        error,
+        result,
+      })
+    }
+
+    return {
+      // Running the operation inside this span's context makes it the
+      // parent of any spans started within.
+      run: (fn) => this.context.run({ id }, fn),
+      end: (outcome) => {
+        if (outcome.type === 'failure') {
+          end(errorMessage(outcome.error))
+        } else {
+          // A value is present exactly when result capture is enabled in
+          // the InstrumentOptions; it arrives already redacted.
+          end(
+            null,
+            'value' in outcome ? this.serialize(outcome.value) : undefined,
+          )
+        }
+      },
+    }
+  }
+
+  private serialize(value: unknown): string {
+    let text: string
+    try {
+      text = JSON.stringify(value) ?? String(value)
+    } catch {
+      text = '[unserializable]'
+    }
+    return text.length > this.maxValueLength
+      ? text.slice(0, this.maxValueLength) + '…'
+      : text
+  }
+
+  private emit(event: SpanEvent): void {
+    this.listeners.forEach((listener) => listener(event))
+  }
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}

package/src/dashboardServer.ts

@@ -3,12 +3,15 @@ import {
   IncomingMessage,
   Server,
   ServerResponse,
-} from 'node:http';
-import { AddressInfo } from 'node:net';
-import { ServiceModule } from '@composed-di/core';
-import { DashboardEventListener } from './dashboardEventListener';
-import { ModuleGraph, moduleGraph } from './moduleGraph';
-import { renderDashboardHtml } from './dashboardHtml';
+} from 'node:http'
+import { AddressInfo } from 'node:net'
+import { ServiceModule } from '@composed-di/core'
+import {
+  DashboardInstrumentation,
+  DashboardInstrumentationOptions,
+} from './dashboardInstrumentation'
+import { ModuleGraph, moduleGraph } from './moduleGraph'
+import { renderDashboardHtml } from './dashboardHtml'
 import {
   DashboardSnapshot,
   GraphEdge,
@@ -18,14 +21,14 @@ import {
   SpanKind,
   SpanStart,
   WireEvent,
-} from './events';
+} from './events'
 
-export interface ServiceDashboardOptions {
+export interface ServiceDashboardOptions extends DashboardInstrumentationOptions {
   /** How many recent events to keep for late-joining clients. Default 200. */
-  recentEventLimit?: number;
+  recentEventLimit?: number
 }
 
-const HEARTBEAT_INTERVAL_MS = 15_000;
+const HEARTBEAT_INTERVAL_MS = 15_000
 
 /**
  * A realtime dashboard server for observed ServiceModules.
@@ -43,7 +46,7 @@ const HEARTBEAT_INTERVAL_MS = 15_000;
  * accepts `POST /v1/graph` (the dependency graph) and `POST /v1/events`
  * (batched span events).
  *
- * **In-process:** create the module with `dashboard.listener`, call
+ * **In-process:** create the module with `dashboard.instrumentation`, call
  * `dashboard.attach(module)`, and `listen` from the same process.
  *
  * @example
@@ -54,40 +57,48 @@ const HEARTBEAT_INTERVAL_MS = 15_000;
  *
  * // application process
  * const client = new DashboardClient({ url: 'http://localhost:4321' });
- * const module = ServiceModule.from(factories, client.listener);
+ * const module = ServiceModule.from(
+ *   client.instrumentation.instrument(factories, {
+ *     capture: { arguments: true, results: true },
+ *   }),
+ * );
  * client.attach(module);
  * ```
  */
 export class ServiceDashboard {
-  /** Pass this as the second argument to ServiceModule.from. */
-  readonly listener = new DashboardEventListener();
+  /** Call `.instrument()` on this to wrap the factories composing the module. */
+  readonly instrumentation: DashboardInstrumentation
 
-  private nodes: GraphNode[] = [];
-  private edges: GraphEdge[] = [];
-  private services = new Map<string, ServiceStats>();
+  private nodes: GraphNode[] = []
+  private edges: GraphEdge[] = []
+  private services = new Map<string, ServiceStats>()
   /** Open spans, so end events can be resolved to their start metadata. */
-  private openSpans = new Map<number, SpanStart>();
-  private recent: WireEvent[] = [];
-  private readonly recentEventLimit: number;
+  private openSpans = new Map<number, SpanStart>()
+  private recent: WireEvent[] = []
+  private readonly recentEventLimit: number
   /** Whether any graph was registered; ingest is refused (409) before that. */
-  private graphRegistered = false;
+  private graphRegistered = false
 
-  private clients = new Set<ServerResponse>();
-  private server: Server | null = null;
-  private heartbeat: NodeJS.Timeout | null = null;
+  private clients = new Set<ServerResponse>()
+  private server: Server | null = null
+  private heartbeat: NodeJS.Timeout | null = null
 
-  constructor({ recentEventLimit = 200 }: ServiceDashboardOptions = {}) {
-    this.recentEventLimit = recentEventLimit;
-    this.listener.subscribe((event) => this.onSpanEvent(event));
+  constructor({
+    recentEventLimit = 200,
+    ...instrumentationOptions
+  }: ServiceDashboardOptions = {}) {
+    this.instrumentation = new DashboardInstrumentation(instrumentationOptions)
+    this.recentEventLimit = recentEventLimit
+    this.instrumentation.subscribe((event) => this.onSpanEvent(event))
   }
 
   /**
    * In-process mode: reads the dependency graph out of the module. Call
-   * this with the module that was created with this dashboard's listener.
+   * this with the module that was created with this dashboard's instrumentation.
    */
   attach(module: ServiceModule): this {
-    this.registerGraph(moduleGraph(module));
-    return this;
+    this.registerGraph(moduleGraph(module))
+    return this
   }
 
   /**
@@ -96,15 +107,13 @@ export class ServiceDashboard {
    * through `POST /v1/graph`.
    */
   registerGraph(graph: ModuleGraph): void {
-    this.graphRegistered = true;
-    this.nodes = graph.nodes;
-    this.edges = graph.edges;
-    this.services = new Map(
-      this.nodes.map((node) => [node.name, freshStats()]),
-    );
-    this.openSpans.clear();
-    this.recent = [];
-    this.broadcastSnapshot();
+    this.graphRegistered = true
+    this.nodes = graph.nodes
+    this.edges = graph.edges
+    this.services = new Map(this.nodes.map((node) => [node.name, freshStats()]))
+    this.openSpans.clear()
+    this.recent = []
+    this.broadcastSnapshot()
   }
 
   /**
@@ -119,11 +128,11 @@ export class ServiceDashboard {
         event.service !== null &&
         !this.services.has(event.service)
       ) {
-        this.nodes.push({ name: event.service });
-        this.services.set(event.service, freshStats());
-        this.broadcastSnapshot();
+        this.nodes.push({ name: event.service })
+        this.services.set(event.service, freshStats())
+        this.broadcastSnapshot()
       }
-      this.onSpanEvent(event);
+      this.onSpanEvent(event)
     }
   }
 
@@ -134,7 +143,7 @@ export class ServiceDashboard {
       edges: this.edges,
       services: Object.fromEntries(this.services),
       recent: this.recent,
-    };
+    }
   }
 
   /**
@@ -146,43 +155,43 @@ export class ServiceDashboard {
    */
   listen(port = 4321, host = '127.0.0.1'): Promise<string> {
     if (this.server) {
-      throw new Error('Dashboard server is already listening');
+      throw new Error('Dashboard server is already listening')
     }
     const server = createServer((request, response) => {
-      void this.route(request, response);
-    });
-    this.server = server;
+      void this.route(request, response)
+    })
+    this.server = server
     this.heartbeat = setInterval(() => {
-      this.clients.forEach((client) => client.write(': ping\n\n'));
-    }, HEARTBEAT_INTERVAL_MS);
+      this.clients.forEach((client) => client.write(': ping\n\n'))
+    }, HEARTBEAT_INTERVAL_MS)
     // Don't let an idle dashboard keep the process alive on its own.
-    this.heartbeat.unref();
+    this.heartbeat.unref()
 
     return new Promise((resolve, reject) => {
-      server.once('error', reject);
+      server.once('error', reject)
       server.listen(port, host, () => {
-        const address = server.address() as AddressInfo;
+        const address = server.address() as AddressInfo
         const shownHost =
-          host === '0.0.0.0' || host === '::' ? 'localhost' : host;
-        resolve(`http://${shownHost}:${address.port}`);
-      });
-    });
+          host === '0.0.0.0' || host === '::' ? 'localhost' : host
+        resolve(`http://${shownHost}:${address.port}`)
+      })
+    })
   }
 
   /** Stops the server and disconnects all clients. */
   async close(): Promise<void> {
     if (this.heartbeat) {
-      clearInterval(this.heartbeat);
-      this.heartbeat = null;
+      clearInterval(this.heartbeat)
+      this.heartbeat = null
     }
-    this.clients.forEach((client) => client.end());
-    this.clients.clear();
-    const server = this.server;
-    this.server = null;
+    this.clients.forEach((client) => client.end())
+    this.clients.clear()
+    const server = this.server
+    this.server = null
     if (server) {
       await new Promise<void>((resolve, reject) => {
-        server.close((error) => (error ? reject(error) : resolve()));
-      });
+        server.close((error) => (error ? reject(error) : resolve()))
+      })
     }
   }
 
@@ -190,60 +199,60 @@ export class ServiceDashboard {
     request: IncomingMessage,
     response: ServerResponse,
   ): Promise<void> {
-    const path = request.url?.split('?')[0];
-    const route = `${request.method} ${path}`;
+    const path = request.url?.split('?')[0]
+    const route = `${request.method} ${path}`
     try {
       switch (route) {
         case 'GET /':
           response.writeHead(200, {
             'content-type': 'text/html; charset=utf-8',
-          });
-          response.end(renderDashboardHtml());
-          return;
+          })
+          response.end(renderDashboardHtml())
+          return
         case 'GET /events':
-          this.acceptEventStream(response);
-          return;
+          this.acceptEventStream(response)
+          return
         case 'GET /snapshot':
-          response.writeHead(200, { 'content-type': 'application/json' });
-          response.end(JSON.stringify(this.snapshot()));
-          return;
+          response.writeHead(200, { 'content-type': 'application/json' })
+          response.end(JSON.stringify(this.snapshot()))
+          return
         case 'POST /v1/graph': {
-          const graph = await readJsonBody(request);
+          const graph = await readJsonBody(request)
           if (!Array.isArray(graph?.nodes) || !Array.isArray(graph?.edges)) {
-            throw new BadRequestError('expected { nodes: [], edges: [] }');
+            throw new BadRequestError('expected { nodes: [], edges: [] }')
           }
-          this.registerGraph(graph);
-          response.writeHead(204);
-          response.end();
-          return;
+          this.registerGraph(graph)
+          response.writeHead(204)
+          response.end()
+          return
         }
         case 'POST /v1/events': {
-          const body = await readJsonBody(request);
+          const body = await readJsonBody(request)
           if (!Array.isArray(body?.events)) {
-            throw new BadRequestError('expected { events: [] }');
+            throw new BadRequestError('expected { events: [] }')
           }
           // A restarted server has no graph; tell the client to re-register
           // before it sends events, so context isn't rendered nodeless.
           if (!this.graphRegistered) {
-            response.writeHead(409, { 'content-type': 'text/plain' });
-            response.end('no graph registered; POST /v1/graph first');
-            return;
+            response.writeHead(409, { 'content-type': 'text/plain' })
+            response.end('no graph registered; POST /v1/graph first')
+            return
           }
-          this.ingest(body.events);
-          response.writeHead(204);
-          response.end();
-          return;
+          this.ingest(body.events)
+          response.writeHead(204)
+          response.end()
+          return
         }
         default:
-          response.writeHead(404, { 'content-type': 'text/plain' });
-          response.end('Not found');
+          response.writeHead(404, { 'content-type': 'text/plain' })
+          response.end('Not found')
       }
     } catch (error) {
-      const badRequest = error instanceof BadRequestError;
+      const badRequest = error instanceof BadRequestError
       response.writeHead(badRequest ? 400 : 500, {
         'content-type': 'text/plain',
-      });
-      response.end(badRequest ? error.message : 'Internal error');
+      })
+      response.end(badRequest ? error.message : 'Internal error')
     }
   }
 
@@ -252,10 +261,10 @@ export class ServiceDashboard {
       'content-type': 'text/event-stream',
       'cache-control': 'no-cache',
       connection: 'keep-alive',
-    });
-    response.write(sseMessage('snapshot', this.snapshot()));
-    this.clients.add(response);
-    response.on('close', () => this.clients.delete(response));
+    })
+    response.write(sseMessage('snapshot', this.snapshot()))
+    this.clients.add(response)
+    response.on('close', () => this.clients.delete(response))
   }
 
   /**
@@ -263,88 +272,100 @@ export class ServiceDashboard {
    * broadcasts the enriched event to connected clients.
    */
   private onSpanEvent(event: SpanEvent): void {
-    let wire: WireEvent;
+    let wire: WireEvent
 
     if (event.type === 'start') {
-      this.openSpans.set(event.id, event);
-      const stats = this.applyStart(event);
+      this.openSpans.set(event.id, event)
+      const stats = this.applyStart(event)
       wire = {
         span: event,
         service: event.service,
         method: event.method,
         kind: event.kind,
         parentService: this.parentServiceOf(event),
+        args: event.args ?? null,
         // Copy so the recent-events buffer keeps at-the-time values.
-        stats: stats ? { ...stats } : null,
-      };
+        stats: stats ? copyStats(stats) : null,
+      }
     } else {
-      const start = this.openSpans.get(event.id);
-      this.openSpans.delete(event.id);
-      const stats = start ? this.applyEnd(start, event) : null;
+      const start = this.openSpans.get(event.id)
+      this.openSpans.delete(event.id)
+      const stats = start ? this.applyEnd(start, event) : null
       wire = {
         span: event,
         service: start?.service ?? null,
         method: start?.method ?? '?',
         kind: start?.kind ?? 'call',
         parentService: start ? this.parentServiceOf(start) : null,
-        stats: stats ? { ...stats } : null,
-      };
+        args: start?.args ?? null,
+        stats: stats ? copyStats(stats) : null,
+      }
     }
 
-    this.recent.push(wire);
+    this.recent.push(wire)
     if (this.recent.length > this.recentEventLimit) {
-      this.recent.splice(0, this.recent.length - this.recentEventLimit);
+      this.recent.splice(0, this.recent.length - this.recentEventLimit)
     }
-    const message = sseMessage('span', wire);
-    this.clients.forEach((client) => client.write(message));
+    const message = sseMessage('span', wire)
+    this.clients.forEach((client) => client.write(message))
   }
 
   private applyStart(event: SpanStart): ServiceStats | null {
-    const stats = event.service ? this.services.get(event.service) : undefined;
-    if (!stats) return null;
+    const stats = event.service ? this.services.get(event.service) : undefined
+    if (!stats) return null
     if (event.kind === 'initialize') {
-      stats.status = 'initializing';
+      stats.status = 'initializing'
     }
-    return stats;
+    return stats
   }
 
   private applyEnd(
     start: SpanStart,
     event: { durationMs: number; error: string | null },
   ): ServiceStats | null {
-    const stats = start.service ? this.services.get(start.service) : undefined;
-    if (!stats) return null;
+    const stats = start.service ? this.services.get(start.service) : undefined
+    if (!stats) return null
 
     if (event.error !== null) {
-      stats.errors += 1;
+      stats.errors += 1
     }
     const transitions: Record<SpanKind, () => void> = {
       initialize: () => {
-        stats.status = event.error !== null ? 'error' : 'ready';
-        if (event.error === null) stats.initMs = event.durationMs;
+        stats.status = event.error !== null ? 'error' : 'ready'
+        if (event.error === null) stats.initMs = event.durationMs
       },
       dispose: () => {
-        if (event.error === null) stats.status = 'disposed';
+        if (event.error === null) stats.status = 'disposed'
       },
       call: () => {
-        stats.calls += 1;
-        stats.totalCallMs += event.durationMs;
+        stats.calls += 1
+        stats.totalCallMs += event.durationMs
+        const method = (stats.methods[start.method] ??= {
+          calls: 0,
+          errors: 0,
+          totalMs: 0,
+          lastMs: 0,
+        })
+        method.calls += 1
+        method.totalMs += event.durationMs
+        method.lastMs = event.durationMs
+        if (event.error !== null) method.errors += 1
       },
-    };
-    transitions[start.kind]();
-    return stats;
+    }
+    transitions[start.kind]()
+    return stats
   }
 
   /** Walks to the parent span to find which service triggered this one. */
   private parentServiceOf(event: SpanStart): string | null {
-    if (event.parentId === null) return null;
-    return this.openSpans.get(event.parentId)?.service ?? null;
+    if (event.parentId === null) return null
+    return this.openSpans.get(event.parentId)?.service ?? null
   }
 
   /** Pushes the full state to all connected clients, e.g. on graph changes. */
   private broadcastSnapshot(): void {
-    const message = sseMessage('snapshot', this.snapshot());
-    this.clients.forEach((client) => client.write(message));
+    const message = sseMessage('snapshot', this.snapshot())
+    this.clients.forEach((client) => client.write(message))
   }
 }
 
@@ -355,37 +376,51 @@ function freshStats(): ServiceStats {
     calls: 0,
     errors: 0,
     totalCallMs: 0,
-  };
+    methods: {},
+  }
+}
+
+/** Deep enough that the recent-events buffer keeps at-the-time values. */
+function copyStats(stats: ServiceStats): ServiceStats {
+  return {
+    ...stats,
+    methods: Object.fromEntries(
+      Object.entries(stats.methods).map(([name, method]) => [
+        name,
+        { ...method },
+      ]),
+    ),
+  }
 }
 
 class BadRequestError extends Error {}
 
-const MAX_BODY_BYTES = 5 * 1024 * 1024;
+const MAX_BODY_BYTES = 5 * 1024 * 1024
 
 function readJsonBody(request: IncomingMessage): Promise<any> {
   return new Promise((resolve, reject) => {
-    const chunks: Buffer[] = [];
-    let size = 0;
+    const chunks: Buffer[] = []
+    let size = 0
     request.on('data', (chunk: Buffer) => {
-      size += chunk.length;
+      size += chunk.length
       if (size > MAX_BODY_BYTES) {
-        reject(new BadRequestError('request body too large'));
-        request.destroy();
-        return;
+        reject(new BadRequestError('request body too large'))
+        request.destroy()
+        return
       }
-      chunks.push(chunk);
-    });
+      chunks.push(chunk)
+    })
     request.on('end', () => {
       try {
-        resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+        resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')))
       } catch {
-        reject(new BadRequestError('invalid JSON body'));
+        reject(new BadRequestError('invalid JSON body'))
       }
-    });
-    request.on('error', reject);
-  });
+    })
+    request.on('error', reject)
+  })
 }
 
 function sseMessage(event: string, data: unknown): string {
-  return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+  return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`
 }