@node-llm/monitor-otel 0.1.0

package/README.md

@@ -0,0 +1,68 @@
+# @node-llm/monitor-otel 📡
+
+![OpenTelemetry](https://img.shields.io/badge/OpenTelemetry-Enabled-blue)
+![npm](https://img.shields.io/npm/v/@node-llm/monitor-otel)
+
+OpenTelemetry integration for NodeLLM Monitor. Bridging the gap between standard OTel tracing and AI-specific observability.
+
+## Features
+
+- 🔌 **Zero-Code Instrumentation**: Automatically capture AI spans from libraries like Vercel AI SDK.
+- 🧠 **AI-Aware**: Extracts model names, token usage, cost, and tool calls from OTel attributes.
+- 🎯 **Native Routing**: Forwards AI spans directly to your NodeLLM Monitor store.
+- 🔍 **Streaming Support**: Captures Time-to-First-Token (TTFT) and average tokens/sec.
+
+## Installation
+
+```bash
+pnpm add @node-llm/monitor @node-llm/monitor-otel
+```
+
+## Usage
+
+### 1. Basic Setup
+
+```ts
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { Monitor } from "@node-llm/monitor";
+import { NodeLLMSpanProcessor } from "@node-llm/monitor-otel";
+
+// 1. Initialize your monitor store
+const monitor = Monitor.memory();
+
+// 2. Add the SpanProcessor to your OTel provider
+const provider = new NodeTracerProvider();
+provider.addSpanProcessor(new NodeLLMSpanProcessor(monitor.getStore()));
+provider.register();
+```
+
+### 2. Instrumented Libraries (e.g., Vercel AI SDK)
+
+```ts
+import { generateText } from "ai";
+import { openai } from "@ai-sdk/openai";
+
+const result = await generateText({
+  model: openai("gpt-4o"),
+  prompt: "What is quantum gravity?",
+  experimental_telemetry: { isEnabled: true } // Enable OTel spans
+});
+```
+
+The spans emitted by `ai` will be automatically intercepted, processed, and saved to your NodeLLM Monitor dashboard.
+
+## Configuration
+
+`NodeLLMSpanProcessor` accepts an optional options object:
+
+```ts
+new NodeLLMSpanProcessor(store, {
+  captureContent: true, // Set to false to hide prompts/responses from logs
+  filter: (span) => span.name.includes("my-app"), // Custom span filtering
+  onError: (err, span) => console.error("Failed to process AI span", err)
+});
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,116 @@
+import * as _node_llm_monitor from '@node-llm/monitor';
+import { MonitoringStore } from '@node-llm/monitor';
+import { Span, Context } from '@opentelemetry/api';
+import { SpanProcessor, ReadableSpan } from '@opentelemetry/sdk-trace-base';
+
+/**
+ * Minimal Span interface matching OpenTelemetry ReadableSpan
+ */
+type OTelReadableSpan = ReadableSpan;
+type OTelSpan = Span;
+type OTelContext = Context;
+/**
+ * SpanProcessor interface matching OpenTelemetry SDK
+ */
+type OTelSpanProcessor = SpanProcessor;
+/**
+ * Configuration for the NodeLLM SpanProcessor
+ */
+interface NodeLLMSpanProcessorOptions {
+    /**
+     * Whether to capture prompt/response content.
+     * Default: true (respects Vercel AI SDK's recordInputs/recordOutputs settings)
+     */
+    captureContent?: boolean;
+    /**
+     * Filter function to decide which spans to process.
+     * Return true to process, false to skip.
+     * Default: processes all ai.* spans
+     */
+    filter?: (span: OTelReadableSpan) => boolean;
+    /**
+     * Custom transform function to modify the monitoring event before saving.
+     */
+    transform?: (event: _node_llm_monitor.MonitoringEvent, span: OTelReadableSpan) => _node_llm_monitor.MonitoringEvent;
+    /**
+     * Session ID extractor. By default, looks for ai.telemetry.metadata.sessionId
+     */
+    sessionIdExtractor?: (span: OTelReadableSpan) => string | undefined;
+    /**
+     * Error handler for storage failures
+     */
+    onError?: (error: Error, span: OTelReadableSpan) => void;
+}
+
+/**
+ * NodeLLM SpanProcessor for OpenTelemetry
+ *
+ * This SpanProcessor intercepts OpenTelemetry spans emitted by the Vercel AI SDK
+ * (and other OTel-instrumented LLM libraries) and converts them to NodeLLM Monitor events.
+ *
+ * Usage:
+ * ```ts
+ * import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+ * import { NodeLLMSpanProcessor } from "@node-llm/monitor/otel";
+ * import { PrismaAdapter } from "@node-llm/monitor/adapters/prisma";
+ *
+ * const store = new PrismaAdapter(prisma);
+ * const provider = new NodeTracerProvider();
+ * provider.addSpanProcessor(new NodeLLMSpanProcessor(store));
+ * provider.register();
+ *
+ * // Now Vercel AI SDK's experimental_telemetry will flow to node-llm-monitor
+ * await generateText({
+ *   model: openai("gpt-4o"),
+ *   prompt: "Hello",
+ *   experimental_telemetry: { isEnabled: true }
+ * });
+ * ```
+ */
+
+/**
+ * OpenTelemetry SpanProcessor that routes AI spans to NodeLLM Monitor storage.
+ *
+ * This processor:
+ * 1. Filters for AI-related spans (ai.generateText, ai.streamText, etc.)
+ * 2. Extracts LLM-specific attributes (model, tokens, cost, etc.)
+ * 3. Converts to MonitoringEvent format
+ * 4. Saves to the configured MonitoringStore
+ */
+declare class NodeLLMSpanProcessor implements OTelSpanProcessor {
+    private readonly store;
+    private readonly options;
+    private pendingWrites;
+    constructor(store: MonitoringStore, options?: NodeLLMSpanProcessorOptions);
+    /**
+     * Called when a span starts. We don't need to do anything here
+     * since we process spans on completion.
+     */
+    onStart(_span: OTelSpan, _parentContext: OTelContext): void;
+    /**
+     * Called when a span ends. This is where we extract data and save events.
+     */
+    onEnd(span: OTelReadableSpan): void;
+    /**
+     * Process a single span and save as MonitoringEvent
+     */
+    private processSpan;
+    /**
+     * Convert an OTel span to a MonitoringEvent
+     */
+    private spanToEvent;
+    /**
+     * Flush all pending writes
+     */
+    forceFlush(): Promise<void>;
+    /**
+     * Shutdown the processor
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Factory function to create a SpanProcessor with simpler API
+ */
+declare function createOTelProcessor(store: MonitoringStore, options?: NodeLLMSpanProcessorOptions): NodeLLMSpanProcessor;
+
+export { NodeLLMSpanProcessor, createOTelProcessor };

package/dist/index.js

@@ -0,0 +1,325 @@
+// src/NodeLLMSpanProcessor.ts
+import { randomUUID } from "crypto";
+
+// src/utils.ts
+var AI_OPERATION_PREFIXES = [
+  "ai.generateText",
+  "ai.streamText",
+  "ai.generateObject",
+  "ai.streamObject",
+  "ai.embed",
+  "ai.embedMany",
+  "ai.toolCall",
+  "gen_ai."
+  // Standard OTel prefix
+];
+function isAISpan(span) {
+  const hasAIPrefix = AI_OPERATION_PREFIXES.some((prefix) => span.name.startsWith(prefix));
+  const hasAIAttributes = span.attributes && (span.attributes["ai.operationId"] || span.attributes["gen_ai.system"] || span.attributes["gen_ai.request.model"]);
+  return !!(hasAIPrefix || hasAIAttributes);
+}
+function isTopLevelAISpan(span) {
+  const name = span.name;
+  const operationId = span.attributes["ai.operationId"];
+  const isDoSpan = name.includes(".doGenerate") || name.includes(".doStream") || name.includes(".doEmbed");
+  const isToolCall = operationId === "ai.toolCall" || name === "ai.toolCall";
+  return !isDoSpan || isToolCall;
+}
+function getOperationType(span) {
+  const operationId = span.attributes["ai.operationId"];
+  if (operationId) {
+    return operationId;
+  }
+  for (const prefix of AI_OPERATION_PREFIXES) {
+    if (span.name.startsWith(prefix)) {
+      return span.name.split(" ")[0];
+    }
+  }
+  return void 0;
+}
+function getString(attrs, key) {
+  const value = attrs[key];
+  return typeof value === "string" ? value : void 0;
+}
+function getNumber(attrs, key) {
+  const value = attrs[key];
+  return typeof value === "number" ? value : void 0;
+}
+function extractAIAttributes(span) {
+  const attrs = span.attributes;
+  const metadata = {};
+  for (const [key, value] of Object.entries(attrs)) {
+    if (key.startsWith("ai.telemetry.metadata.")) {
+      const metaKey = key.replace("ai.telemetry.metadata.", "");
+      metadata[metaKey] = value;
+    }
+  }
+  return {
+    // Operation info
+    operationId: getString(attrs, "ai.operationId"),
+    functionId: getString(attrs, "ai.telemetry.functionId") || getString(attrs, "resource.name"),
+    // Model info
+    modelId: getString(attrs, "ai.model.id"),
+    modelProvider: getString(attrs, "ai.model.provider"),
+    // Request info
+    prompt: getString(attrs, "ai.prompt"),
+    promptMessages: getString(attrs, "ai.prompt.messages"),
+    promptTools: getString(attrs, "ai.prompt.tools"),
+    // Response info
+    responseText: getString(attrs, "ai.response.text"),
+    responseObject: getString(attrs, "ai.response.object"),
+    responseToolCalls: getString(attrs, "ai.response.toolCalls"),
+    responseFinishReason: getString(attrs, "ai.response.finishReason"),
+    responseId: getString(attrs, "ai.response.id"),
+    responseModel: getString(attrs, "ai.response.model"),
+    // Usage - AI SDK attributes
+    promptTokens: getNumber(attrs, "ai.usage.promptTokens"),
+    completionTokens: getNumber(attrs, "ai.usage.completionTokens"),
+    // Timing (streaming)
+    msToFirstChunk: getNumber(attrs, "ai.response.msToFirstChunk"),
+    msToFinish: getNumber(attrs, "ai.response.msToFinish"),
+    avgCompletionTokensPerSecond: getNumber(attrs, "ai.response.avgCompletionTokensPerSecond"),
+    // Tool calls
+    toolCallName: getString(attrs, "ai.toolCall.name"),
+    toolCallId: getString(attrs, "ai.toolCall.id"),
+    toolCallArgs: getString(attrs, "ai.toolCall.args"),
+    toolCallResult: getString(attrs, "ai.toolCall.result"),
+    // GenAI semantic conventions (OpenTelemetry standard)
+    genAiSystem: getString(attrs, "gen_ai.system"),
+    genAiRequestModel: getString(attrs, "gen_ai.request.model"),
+    genAiResponseModel: getString(attrs, "gen_ai.response.model"),
+    genAiInputTokens: getNumber(attrs, "gen_ai.usage.input_tokens"),
+    genAiOutputTokens: getNumber(attrs, "gen_ai.usage.output_tokens"),
+    // Custom metadata
+    metadata: Object.keys(metadata).length > 0 ? metadata : void 0
+  };
+}
+function hrTimeToDate(hrTime) {
+  const [seconds, nanoseconds] = hrTime;
+  return new Date(seconds * 1e3 + nanoseconds / 1e6);
+}
+function calculateDurationMs(startTime, endTime) {
+  const startMs = startTime[0] * 1e3 + startTime[1] / 1e6;
+  const endMs = endTime[0] * 1e3 + endTime[1] / 1e6;
+  return Math.round(endMs - startMs);
+}
+function extractProvider(attrs) {
+  if (attrs.modelProvider) {
+    return normalizeProviderName(attrs.modelProvider);
+  }
+  if (attrs.genAiSystem) {
+    return normalizeProviderName(attrs.genAiSystem);
+  }
+  const modelId = attrs.modelId || attrs.genAiRequestModel || "";
+  if (modelId.startsWith("gpt-") || modelId.includes("openai")) {
+    return "openai";
+  }
+  if (modelId.startsWith("claude-") || modelId.includes("anthropic")) {
+    return "anthropic";
+  }
+  if (modelId.startsWith("gemini-") || modelId.includes("google")) {
+    return "google";
+  }
+  if (modelId.startsWith("deepseek-")) {
+    return "deepseek";
+  }
+  if (modelId.includes("llama") || modelId.includes("mistral")) {
+    return "meta";
+  }
+  return "unknown";
+}
+function normalizeProviderName(provider) {
+  if (provider.includes(".")) {
+    return provider.split(".")[0] || provider;
+  }
+  return provider;
+}
+function extractModel(attrs) {
+  const rawModel = attrs.responseModel || attrs.modelId || attrs.genAiResponseModel || attrs.genAiRequestModel || "unknown";
+  return normalizeModelName(rawModel);
+}
+function normalizeModelName(model) {
+  if (model.includes("/")) {
+    const parts = model.split("/");
+    return parts[parts.length - 1] || model;
+  }
+  return model;
+}
+function mapStatusToEventType(statusCode, operationType) {
+  const isError = statusCode === 2;
+  if (operationType?.includes("toolCall")) {
+    return isError ? "tool.error" : "tool.end";
+  }
+  return isError ? "request.error" : "request.end";
+}
+function generateRequestId(span) {
+  const ctx = span.spanContext();
+  return `otel_${ctx.traceId.slice(0, 8)}_${ctx.spanId.slice(0, 8)}`;
+}
+function extractSessionId(span) {
+  const attrs = span.attributes;
+  return getString(attrs, "ai.telemetry.metadata.sessionId") || getString(attrs, "ai.telemetry.metadata.session_id") || getString(attrs, "session.id") || getString(attrs, "sessionId");
+}
+function parseJsonAttribute(value) {
+  if (!value) return void 0;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return void 0;
+  }
+}
+
+// src/NodeLLMSpanProcessor.ts
+import { estimateCost } from "@node-llm/monitor";
+var NodeLLMSpanProcessor = class {
+  store;
+  options;
+  pendingWrites = [];
+  constructor(store, options = {}) {
+    this.store = store;
+    this.options = {
+      captureContent: true,
+      ...options
+    };
+  }
+  /**
+   * Called when a span starts. We don't need to do anything here
+   * since we process spans on completion.
+   */
+  onStart(_span, _parentContext) {
+  }
+  /**
+   * Called when a span ends. This is where we extract data and save events.
+   */
+  onEnd(span) {
+    if (!isAISpan(span)) {
+      return;
+    }
+    if (this.options.filter && !this.options.filter(span)) {
+      return;
+    }
+    if (!isTopLevelAISpan(span)) {
+      return;
+    }
+    const writePromise = this.processSpan(span).catch((error) => {
+      if (this.options.onError) {
+        this.options.onError(error, span);
+      } else {
+        console.error("[NodeLLMSpanProcessor] Error processing span:", error);
+      }
+    });
+    this.pendingWrites.push(writePromise);
+  }
+  /**
+   * Process a single span and save as MonitoringEvent
+   */
+  async processSpan(span) {
+    const event = this.spanToEvent(span);
+    const finalEvent = this.options.transform ? this.options.transform(event, span) : event;
+    await this.store.saveEvent(finalEvent);
+  }
+  /**
+   * Convert an OTel span to a MonitoringEvent
+   */
+  spanToEvent(span) {
+    const attrs = extractAIAttributes(span);
+    const operationType = getOperationType(span);
+    const provider = extractProvider(attrs);
+    const model = extractModel(attrs);
+    const duration = calculateDurationMs(span.startTime, span.endTime);
+    const promptTokens = attrs.promptTokens ?? attrs.genAiInputTokens ?? 0;
+    const completionTokens = attrs.completionTokens ?? attrs.genAiOutputTokens ?? 0;
+    const cost = estimateCost(provider, model, promptTokens, completionTokens);
+    const requestId = this.options.sessionIdExtractor ? generateRequestId(span) : generateRequestId(span);
+    const sessionId = this.options.sessionIdExtractor ? this.options.sessionIdExtractor(span) : extractSessionId(span);
+    const payload = {
+      operationType,
+      functionId: attrs.functionId,
+      finishReason: attrs.responseFinishReason,
+      usage: {
+        promptTokens,
+        completionTokens,
+        totalTokens: promptTokens + completionTokens
+      },
+      // Streaming metrics
+      ...attrs.msToFirstChunk !== void 0 && {
+        msToFirstChunk: attrs.msToFirstChunk
+      },
+      ...attrs.msToFinish !== void 0 && { msToFinish: attrs.msToFinish },
+      ...attrs.avgCompletionTokensPerSecond !== void 0 && {
+        avgCompletionTokensPerSecond: attrs.avgCompletionTokensPerSecond
+      },
+      // Custom metadata
+      ...attrs.metadata && { metadata: attrs.metadata },
+      // OpenTelemetry trace context
+      otel: {
+        traceId: span.spanContext().traceId,
+        spanId: span.spanContext().spanId,
+        parentSpanId: span.parentSpanId
+      }
+    };
+    if (this.options.captureContent) {
+      if (attrs.prompt) {
+        payload.prompt = attrs.prompt;
+      }
+      if (attrs.promptMessages) {
+        payload.messages = parseJsonAttribute(attrs.promptMessages);
+      }
+      if (attrs.responseText) {
+        payload.result = attrs.responseText;
+      }
+      if (attrs.responseObject) {
+        payload.object = parseJsonAttribute(attrs.responseObject);
+      }
+      if (attrs.responseToolCalls) {
+        payload.toolCalls = parseJsonAttribute(attrs.responseToolCalls);
+      }
+    }
+    if (operationType === "ai.toolCall") {
+      payload.tool = {
+        name: attrs.toolCallName,
+        id: attrs.toolCallId,
+        ...this.options.captureContent && {
+          args: parseJsonAttribute(attrs.toolCallArgs),
+          result: parseJsonAttribute(attrs.toolCallResult)
+        }
+      };
+    }
+    if (span.status.code === 2) {
+      payload.error = span.status.message || "Unknown error";
+    }
+    return {
+      id: randomUUID(),
+      eventType: mapStatusToEventType(span.status.code, operationType),
+      requestId,
+      sessionId,
+      time: hrTimeToDate(span.startTime),
+      duration,
+      cost,
+      payload,
+      createdAt: /* @__PURE__ */ new Date(),
+      provider,
+      model
+    };
+  }
+  /**
+   * Flush all pending writes
+   */
+  async forceFlush() {
+    await Promise.all(this.pendingWrites);
+    this.pendingWrites = [];
+  }
+  /**
+   * Shutdown the processor
+   */
+  async shutdown() {
+    await this.forceFlush();
+  }
+};
+function createOTelProcessor(store, options) {
+  return new NodeLLMSpanProcessor(store, options);
+}
+export {
+  NodeLLMSpanProcessor,
+  createOTelProcessor
+};

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@node-llm/monitor-otel",
+  "version": "0.1.0",
+  "description": "OpenTelemetry integration for NodeLLM Monitor",
+  "main": "dist/index.js",
+  "type": "module",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "lint": "eslint .",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@node-llm/monitor": "workspace:*",
+    "@opentelemetry/api": "^1.7.0",
+    "@opentelemetry/sdk-trace-base": "^1.18.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "eslint": "^8.56.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^4.0.18"
+  }
+}