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

package/src/events.ts

@@ -1,71 +1,89 @@
 /**
- * Event and state types shared between the dashboard event listener, the
+ * Event and state types shared between the dashboard instrumentation, the
  * dashboard server, and the browser client (over the SSE wire).
  */
 
 /** Classifies what a span represents in the service lifecycle. */
-export type SpanKind = 'initialize' | 'dispose' | 'call';
+export type SpanKind = 'initialize' | 'dispose' | 'call'
 
 /** Emitted when a traced function starts executing. */
 export interface SpanStart {
-  type: 'start';
+  type: 'start'
   /** Monotonically increasing span id, unique per tracer. */
-  id: number;
+  id: number
   /** Id of the span that was active when this one started, if any. */
-  parentId: number | null;
+  parentId: number | null
   /** The qualified span name, e.g. "Database.query". */
-  name: string;
+  name: string
   /** The service the span belongs to, or null if it could not be attributed. */
-  service: string | null;
+  service: string | null
   /** The method or lifecycle step, e.g. "query" or "initialize". */
-  method: string;
-  kind: SpanKind;
+  method: string
+  kind: SpanKind
   /** Epoch milliseconds. */
-  time: number;
+  time: number
+  /** Method arguments serialized to JSON, when capture is enabled. */
+  args?: string
 }
 
 /** Emitted when a traced function finishes (or throws/rejects). */
 export interface SpanEnd {
-  type: 'end';
+  type: 'end'
   /** Matches the id of the corresponding SpanStart. */
-  id: number;
+  id: number
   /** Epoch milliseconds. */
-  time: number;
-  durationMs: number;
+  time: number
+  durationMs: number
   /** The error message when the traced function threw or rejected. */
-  error: string | null;
+  error: string | null
+  /** Return / resolved value serialized to JSON, when capture is enabled. */
+  result?: string
 }
 
-export type SpanEvent = SpanStart | SpanEnd;
+export type SpanEvent = SpanStart | SpanEnd
 
 export type ServiceStatus =
   | 'pending'
   | 'initializing'
   | 'ready'
   | 'error'
-  | 'disposed';
+  | 'disposed'
+
+/** Aggregated counters for a single method of a service. */
+export interface MethodStats {
+  /** Number of completed call spans for this method. */
+  calls: number
+  /** Number of those calls that ended with an error. */
+  errors: number
+  /** Sum of completed call durations, for averaging. */
+  totalMs: number
+  /** Duration of the most recently completed call. */
+  lastMs: number
+}
 
 /** Aggregated per-service counters maintained by the dashboard. */
 export interface ServiceStats {
-  status: ServiceStatus;
+  status: ServiceStatus
   /** Duration of the last successful initialization, if any. */
-  initMs: number | null;
+  initMs: number | null
   /** Number of completed method-call spans. */
-  calls: number;
+  calls: number
   /** Number of spans (of any kind) that ended with an error. */
-  errors: number;
+  errors: number
   /** Sum of completed method-call durations, for averaging. */
-  totalCallMs: number;
+  totalCallMs: number
+  /** Per-method call breakdown, keyed by method name. */
+  methods: Record<string, MethodStats>
 }
 
 export interface GraphNode {
-  name: string;
+  name: string
 }
 
 /** A dependency edge: `from` depends on `to`. */
 export interface GraphEdge {
-  from: string;
-  to: string;
+  from: string
+  to: string
 }
 
 /**
@@ -74,21 +92,23 @@ export interface GraphEdge {
  * updated per-service stats so the client needs no correlation logic.
  */
 export interface WireEvent {
-  span: SpanEvent;
+  span: SpanEvent
   /** Service of the span; on end events resolved from the matching start. */
-  service: string | null;
-  method: string;
-  kind: SpanKind;
+  service: string | null
+  method: string
+  kind: SpanKind
   /** Service of the parent span, when the span was started by another service. */
-  parentService: string | null;
+  parentService: string | null
+  /** Serialized arguments; on end events resolved from the matching start. */
+  args: string | null
   /** Updated stats for `service`, present when the event changed them. */
-  stats: ServiceStats | null;
+  stats: ServiceStats | null
 }
 
 /** Full state sent to a client when it connects. */
 export interface DashboardSnapshot {
-  nodes: GraphNode[];
-  edges: GraphEdge[];
-  services: Record<string, ServiceStats>;
-  recent: WireEvent[];
+  nodes: GraphNode[]
+  edges: GraphEdge[]
+  services: Record<string, ServiceStats>
+  recent: WireEvent[]
 }

package/src/index.ts

@@ -1,5 +1,5 @@
-export * from './events';
-export * from './dashboardEventListener';
-export * from './dashboardClient';
-export * from './dashboardServer';
-export * from './moduleGraph';
+export * from './events'
+export * from './dashboardInstrumentation'
+export * from './dashboardClient'
+export * from './dashboardServer'
+export * from './moduleGraph'

package/src/moduleGraph.ts

@@ -2,12 +2,12 @@ import {
   ServiceKey,
   ServiceModule,
   ServiceSelectorKey,
-} from '@composed-di/core';
-import { GraphEdge, GraphNode } from './events';
+} from '@composed-di/core'
+import { GraphEdge, GraphNode } from './events'
 
 export interface ModuleGraph {
-  nodes: GraphNode[];
-  edges: GraphEdge[];
+  nodes: GraphNode[]
+  edges: GraphEdge[]
 }
 
 /**
@@ -18,20 +18,20 @@ export interface ModuleGraph {
 export function moduleGraph(module: ServiceModule): ModuleGraph {
   const nodes = module.factories.map((factory) => ({
     name: factory.provides.name,
-  }));
+  }))
 
   const edges = module.factories.flatMap((factory) =>
     factory.dependsOn.flatMap((dependency: ServiceKey<unknown>) => {
       const targets =
         dependency instanceof ServiceSelectorKey
           ? dependency.values
-          : [dependency];
+          : [dependency]
       return targets.map((target) => ({
         from: factory.provides.name,
         to: target.name,
-      }));
+      }))
     }),
-  );
+  )
 
-  return { nodes, edges };
+  return { nodes, edges }
 }

package/src/dashboardEventListener.ts

@@ -1,104 +0,0 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
-import { performance } from 'node:perf_hooks';
-import type {
-  DisposeContext,
-  EventSpan,
-  InitializeContext,
-  MethodCallContext,
-  ServiceEventListener,
-} from '@composed-di/core';
-import { SpanEvent, SpanKind } from './events';
-
-/** The span context propagated across sync and async call boundaries. */
-interface SpanContext {
-  id: number;
-}
-
-/**
- * A ServiceEventListener 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). Because a listener does
- *   not control the invocation of the operation it observes, the context
- *   is entered with `enterWith` and can outlive the span within the same
- *   synchronous frame; the dashboard tolerates this, as parents are only
- *   resolved among still-open spans.
- * - Emits events synchronously to subscribers; it never buffers.
- */
-export class DashboardEventListener implements ServiceEventListener {
-  private readonly context = new AsyncLocalStorage<SpanContext>();
-  private readonly listeners = new Set<(event: SpanEvent) => void>();
-  private nextId = 1;
-
-  /**
-   * 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): EventSpan {
-    return this.startSpan(key.name, 'initialize', 'initialize');
-  }
-
-  onDispose({ key }: DisposeContext): EventSpan {
-    return this.startSpan(key.name, 'dispose', 'dispose');
-  }
-
-  onMethodCall({ key, methodName }: MethodCallContext): EventSpan {
-    return this.startSpan(key.name, methodName, 'call');
-  }
-
-  private startSpan(service: string, method: string, kind: SpanKind): EventSpan {
-    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(),
-    });
-
-    const startedAt = performance.now();
-    let ended = false;
-    const end = (error: string | null) => {
-      if (ended) return;
-      ended = true;
-      this.emit({
-        type: 'end',
-        id,
-        time: Date.now(),
-        durationMs: performance.now() - startedAt,
-        error,
-      });
-    };
-
-    // The observed operation runs right after this hook returns, in the
-    // same synchronous frame, so entering the context here makes this span
-    // the parent of any spans started inside the operation.
-    this.context.enterWith({ id });
-
-    return {
-      end: () => end(null),
-      error: (error) => end(errorMessage(error)),
-    };
-  }
-
-  private emit(event: SpanEvent): void {
-    this.listeners.forEach((listener) => listener(event));
-  }
-}
-
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}