@loopstack/observability-examples 0.1.0 → 0.1.2

package/src/workflows/tracing/interceptors/tracing.interceptor.ts

@@ -0,0 +1,31 @@
+import { Logger } from '@nestjs/common';
+import { ToolEnvelope, ToolExecutionContext, ToolInterceptor, UseToolInterceptor } from '@loopstack/common';
+import { ToolTraceService } from '../services/tool-trace.service';
+
+@UseToolInterceptor({ priority: 10 })
+export class TracingInterceptor implements ToolInterceptor {
+  private readonly logger = new Logger(TracingInterceptor.name);
+
+  constructor(private readonly traceStore: ToolTraceService) {}
+
+  async intercept(context: ToolExecutionContext, next: () => Promise<ToolEnvelope>): Promise<ToolEnvelope> {
+    const toolName = context.tool.constructor.name;
+    const workflowId = context.runContext.workflowId;
+    const startTime = performance.now();
+
+    try {
+      const result = await next();
+      this.trace(toolName, workflowId, startTime, true);
+      return result;
+    } catch (error) {
+      this.trace(toolName, workflowId, startTime, false);
+      throw error;
+    }
+  }
+
+  private trace(toolName: string, workflowId: string, startTime: number, success: boolean): void {
+    const durationMs = Math.round(performance.now() - startTime);
+    this.traceStore.record({ toolName, workflowId, durationMs, success });
+    this.logger.log(`${toolName} — ${success ? 'ok' : 'failed'} in ${durationMs}ms (workflow ${workflowId})`);
+  }
+}

package/src/workflows/tracing/services/tool-trace.service.ts

@@ -0,0 +1,26 @@
+import { Injectable } from '@nestjs/common';
+
+export interface ToolTraceEntry {
+  toolName: string;
+  workflowId: string;
+  durationMs: number;
+  success: boolean;
+}
+
+const MAX_ENTRIES = 100;
+
+@Injectable()
+export class ToolTraceService {
+  private readonly entries: ToolTraceEntry[] = [];
+
+  record(entry: ToolTraceEntry): void {
+    this.entries.push(entry);
+    if (this.entries.length > MAX_ENTRIES) {
+      this.entries.shift();
+    }
+  }
+
+  forWorkflow(workflowId: string): ToolTraceEntry[] {
+    return this.entries.filter((entry) => entry.workflowId === workflowId);
+  }
+}

package/src/workflows/tracing/tools/simulate-work.tool.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import { BaseTool, Tool, ToolEnvelope } from '@loopstack/common';
+
+const SimulateWorkSchema = z.object({
+  label: z.string(),
+  delayMs: z.number().min(0).max(5000),
+});
+
+type SimulateWorkArgs = z.infer<typeof SimulateWorkSchema>;
+
+export interface SimulateWorkToolResult {
+  label: string;
+  delayMs: number;
+}
+
+export const SimulateWorkToolResultSchema = z.strictObject({
+  label: z.string(),
+  delayMs: z.number(),
+});
+
+@Tool({
+  name: 'simulate_work',
+  description: 'Sleeps for the given duration so interceptors have something to measure.',
+  schema: SimulateWorkSchema,
+  resultSchema: SimulateWorkToolResultSchema,
+  effects: 'none',
+})
+export class SimulateWorkTool extends BaseTool<SimulateWorkArgs, object, SimulateWorkToolResult> {
+  protected async handle(args: SimulateWorkArgs): Promise<ToolEnvelope<SimulateWorkToolResult>> {
+    await new Promise((resolve) => setTimeout(resolve, args.delayMs));
+    return { data: { label: args.label, delayMs: args.delayMs } };
+  }
+}

package/src/workflows/tracing/tracing-example.workflow.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { BaseWorkflow, MarkdownDocument, Transition, Workflow } from '@loopstack/common';
+import type { RunContext } from '@loopstack/common';
+import { ToolTraceService } from './services/tool-trace.service';
+import { SimulateWorkTool } from './tools/simulate-work.tool';
+
+const TracingExampleArgsSchema = z.object({
+  steps: z.number().min(1).max(10).default(3),
+});
+
+type TracingExampleArgs = z.infer<typeof TracingExampleArgsSchema>;
+
+@Workflow({
+  title: 'Observability - Tracing Interceptor Example',
+  description:
+    'Demonstrates a custom ToolInterceptor — @UseToolInterceptor() registers it app-wide, it measures every tool execution and stores trace entries in an injectable service. The workflow runs a few tool calls and renders the collected trace.',
+  schema: TracingExampleArgsSchema,
+})
+export class TracingExampleWorkflow extends BaseWorkflow<TracingExampleArgs> {
+  constructor(
+    private readonly simulateWorkTool: SimulateWorkTool,
+    private readonly traceStore: ToolTraceService,
+  ) {
+    super();
+  }
+
+  @Transition({ to: 'end' })
+  async runAndTrace(_state: object, ctx: RunContext<TracingExampleArgs>) {
+    for (let i = 1; i <= ctx.args.steps; i++) {
+      await this.simulateWorkTool.call({ label: `step-${i}`, delayMs: i * 100 });
+    }
+
+    const entries = this.traceStore.forWorkflow(ctx.workflowId);
+
+    await this.documentStore.save(MarkdownDocument, {
+      markdown: [
+        '## Tool Trace',
+        '',
+        'Collected by `TracingInterceptor` — it wraps every tool call in this app.',
+        '',
+        '| Tool | Duration | Status |',
+        '| ---- | -------- | ------ |',
+        ...entries.map((e) => `| \`${e.toolName}\` | ${e.durationMs}ms | ${e.success ? '✅ ok' : '❌ failed'} |`),
+      ].join('\n'),
+    });
+  }
+}