@node-llm/monitor-otel 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.2.0] - 2026-11-10
+
+### Features
+
+- **Tags from spans.** `llm.tag.<key>` span attributes, and the Vercel AI SDK's telemetry metadata `tag.<key>`, become the call's tags, for the dashboard's tag filters in `@node-llm/monitor` 0.5.0.
+
+## [0.1.1] - 2026-07-04
+
+### Features
+
+- **Extended Token Accounting**: Extract and store cache, cache-creation, reasoning, and image token counts in `NodeLLMSpanProcessor`, matching the same accounting added to `@node-llm/monitor` 0.4.2.

package/README.md

@@ -59,10 +59,17 @@ The spans emitted by `ai` will be automatically intercepted, processed, and save
 new NodeLLMSpanProcessor(store, {
   captureContent: true, // Set to false to hide prompts/responses from logs
   filter: (span) => span.name.includes("my-app"), // Custom span filtering
+  includeNodeLLMSpans: false, // See "NodeLLM's own spans" below
   onError: (err, span) => console.error("Failed to process AI span", err)
 });
 ```
 
+### NodeLLM's own spans
+
+`@node-llm/core` can also create OpenTelemetry spans, with its `OpenTelemetry(otel)` middleware. The processor skips those spans by default (they carry a `node_llm.request_id` attribute), because the `Monitor` middleware already records the same calls and they would be counted twice.
+
+If NodeLLM reaches Monitor only through OpenTelemetry, without the `Monitor` middleware, set `includeNodeLLMSpans: true`.
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -36,6 +36,14 @@ interface NodeLLMSpanProcessorOptions {
      * Session ID extractor. By default, looks for ai.telemetry.metadata.sessionId
      */
     sessionIdExtractor?: (span: OTelReadableSpan) => string | undefined;
+    /**
+     * Whether to record spans that NodeLLM's own OpenTelemetry middleware
+     * created (they carry a `node_llm.request_id` attribute).
+     * Default: false. The Monitor middleware already records NodeLLM calls, so
+     * recording these spans too would count each call twice. Set to true when
+     * NodeLLM reaches Monitor only through OpenTelemetry.
+     */
+    includeNodeLLMSpans?: boolean;
     /**
      * Error handler for storage failures
      */

package/dist/index.js

@@ -18,6 +18,9 @@ function isAISpan(span) {
   const hasAIAttributes = span.attributes && (span.attributes["ai.operationId"] || span.attributes["gen_ai.system"] || span.attributes["gen_ai.request.model"]);
   return !!(hasAIPrefix || hasAIAttributes);
 }
+function isNodeLLMSpan(span) {
+  return span.attributes?.["node_llm.request_id"] !== void 0;
+}
 function isTopLevelAISpan(span) {
   const name = span.name;
   const operationId = span.attributes["ai.operationId"];
@@ -161,6 +164,15 @@ function generateRequestId(span) {
   const ctx = span.spanContext();
   return `otel_${ctx.traceId.slice(0, 8)}_${ctx.spanId.slice(0, 8)}`;
 }
+function extractTags(span) {
+  const tags = {};
+  for (const [name, value] of Object.entries(span.attributes ?? {})) {
+    const key = name.startsWith("llm.tag.") ? name.slice(8) : name.startsWith("ai.telemetry.metadata.tag.") ? name.slice(26) : void 0;
+    if (!key || value === void 0 || value === null || value === "") continue;
+    tags[key.slice(0, 64)] = String(value).slice(0, 200);
+  }
+  return Object.keys(tags).length ? tags : void 0;
+}
 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");
@@ -179,7 +191,7 @@ import { estimateCost } from "@node-llm/monitor";
 var NodeLLMSpanProcessor = class {
   store;
   options;
-  pendingWrites = [];
+  pendingWrites = /* @__PURE__ */ new Set();
   constructor(store, options = {}) {
     this.store = store;
     this.options = {
@@ -200,6 +212,9 @@ var NodeLLMSpanProcessor = class {
     if (!isAISpan(span)) {
       return;
     }
+    if (!this.options.includeNodeLLMSpans && isNodeLLMSpan(span)) {
+      return;
+    }
     if (this.options.filter && !this.options.filter(span)) {
       return;
     }
@@ -213,7 +228,8 @@ var NodeLLMSpanProcessor = class {
         console.error("[NodeLLMSpanProcessor] Error processing span:", error);
       }
     });
-    this.pendingWrites.push(writePromise);
+    this.pendingWrites.add(writePromise);
+    void writePromise.finally(() => this.pendingWrites.delete(writePromise));
   }
   /**
    * Process a single span and save as MonitoringEvent
@@ -296,6 +312,7 @@ var NodeLLMSpanProcessor = class {
         }
       };
     }
+    const tags = extractTags(span);
     if (span.status.code === 2) {
       payload.error = span.status.message || "Unknown error";
     }
@@ -310,7 +327,8 @@ var NodeLLMSpanProcessor = class {
       payload,
       createdAt: /* @__PURE__ */ new Date(),
       provider,
-      model
+      model,
+      ...tags ? { tags } : {}
     };
   }
   /**
@@ -318,7 +336,7 @@ var NodeLLMSpanProcessor = class {
    */
   async forceFlush() {
     await Promise.all(this.pendingWrites);
-    this.pendingWrites = [];
+    this.pendingWrites.clear();
   }
   /**
    * Shutdown the processor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@node-llm/monitor-otel",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "OpenTelemetry integration for NodeLLM Monitor",
   "main": "dist/index.js",
   "type": "module",
@@ -8,7 +8,7 @@
   "dependencies": {
     "@opentelemetry/api": "^1.7.0",
     "@opentelemetry/sdk-trace-base": "^1.18.1",
-    "@node-llm/monitor": "0.4.2"
+    "@node-llm/monitor": "0.5.0"
   },
   "devDependencies": {
     "@types/node": "^25.2.0",

package/src/NodeLLMSpanProcessor.ts

@@ -35,6 +35,7 @@ import type {
 } from "./types.js";
 import {
   isAISpan,
+  isNodeLLMSpan,
   isTopLevelAISpan,
   getOperationType,
   extractAIAttributes,
@@ -45,7 +46,8 @@ import {
   mapStatusToEventType,
   generateRequestId,
   extractSessionId,
-  parseJsonAttribute
+  parseJsonAttribute,
+  extractTags
 } from "./utils.js";
 import { estimateCost } from "@node-llm/monitor";
 
@@ -62,7 +64,7 @@ export class NodeLLMSpanProcessor implements OTelSpanProcessor {
   private readonly store: MonitoringStore;
   private readonly options: Required<Pick<NodeLLMSpanProcessorOptions, "captureContent">> &
     NodeLLMSpanProcessorOptions;
-  private pendingWrites: Promise<void>[] = [];
+  private pendingWrites = new Set<Promise<void>>();
 
   constructor(store: MonitoringStore, options: NodeLLMSpanProcessorOptions = {}) {
     this.store = store;
@@ -89,6 +91,11 @@ export class NodeLLMSpanProcessor implements OTelSpanProcessor {
       return;
     }
 
+    // Skip NodeLLM's own spans: the Monitor middleware already records those calls
+    if (!this.options.includeNodeLLMSpans && isNodeLLMSpan(span)) {
+      return;
+    }
+
     // Apply custom filter if provided
     if (this.options.filter && !this.options.filter(span)) {
       return;
@@ -109,7 +116,10 @@ export class NodeLLMSpanProcessor implements OTelSpanProcessor {
       }
     });
 
-    this.pendingWrites.push(writePromise);
+    // Track until settled so forceFlush can await in-flight writes without
+    // the set growing unboundedly in long-running processes.
+    this.pendingWrites.add(writePromise);
+    void writePromise.finally(() => this.pendingWrites.delete(writePromise));
   }
 
   /**
@@ -216,6 +226,8 @@ export class NodeLLMSpanProcessor implements OTelSpanProcessor {
       };
     }
 
+    const tags = extractTags(span);
+
     // Handle errors
     if (span.status.code === 2) {
       payload.error = span.status.message || "Unknown error";
@@ -232,7 +244,8 @@ export class NodeLLMSpanProcessor implements OTelSpanProcessor {
       payload,
       createdAt: new Date(),
       provider,
-      model
+      model,
+      ...(tags ? { tags } : {})
     };
   }
 
@@ -241,7 +254,7 @@ export class NodeLLMSpanProcessor implements OTelSpanProcessor {
    */
   async forceFlush(): Promise<void> {
     await Promise.all(this.pendingWrites);
-    this.pendingWrites = [];
+    this.pendingWrites.clear();
   }
 
   /**

package/src/index.ts

@@ -1 +1 @@
-export * from './NodeLLMSpanProcessor.js';
+export * from "./NodeLLMSpanProcessor.js";

package/src/types.ts

@@ -57,57 +57,57 @@ export type AIOperationType =
  */
 export interface AISpanAttributes {
   // Operation info
-  operationId?: string;
-  functionId?: string;
+  operationId?: string | undefined;
+  functionId?: string | undefined;
 
   // Model info
-  modelId?: string;
-  modelProvider?: string;
+  modelId?: string | undefined;
+  modelProvider?: string | undefined;
 
   // Request info
-  prompt?: string;
-  promptMessages?: string;
-  promptTools?: string;
+  prompt?: string | undefined;
+  promptMessages?: string | undefined;
+  promptTools?: string | undefined;
 
   // Response info
-  responseText?: string;
-  responseObject?: string;
-  responseToolCalls?: string;
-  responseFinishReason?: string;
-  responseId?: string;
-  responseModel?: string;
+  responseText?: string | undefined;
+  responseObject?: string | undefined;
+  responseToolCalls?: string | undefined;
+  responseFinishReason?: string | undefined;
+  responseId?: string | undefined;
+  responseModel?: string | undefined;
 
   // Usage
-  promptTokens?: number;
-  completionTokens?: number;
-  totalTokens?: number;
+  promptTokens?: number | undefined;
+  completionTokens?: number | undefined;
+  totalTokens?: number | undefined;
   // Cache/reasoning usage (forward-compatible AI SDK attributes - not yet
-  cachedInputTokens?: number;
-  reasoningTokens?: number;
+  cachedInputTokens?: number | undefined;
+  reasoningTokens?: number | undefined;
 
   // Timing (streaming)
-  msToFirstChunk?: number;
-  msToFinish?: number;
-  avgCompletionTokensPerSecond?: number;
+  msToFirstChunk?: number | undefined;
+  msToFinish?: number | undefined;
+  avgCompletionTokensPerSecond?: number | undefined;
 
   // Tool calls
-  toolCallName?: string;
-  toolCallId?: string;
-  toolCallArgs?: string;
-  toolCallResult?: string;
+  toolCallName?: string | undefined;
+  toolCallId?: string | undefined;
+  toolCallArgs?: string | undefined;
+  toolCallResult?: string | undefined;
 
   // GenAI semantic conventions
-  genAiSystem?: string;
-  genAiRequestModel?: string;
-  genAiResponseModel?: string;
-  genAiInputTokens?: number;
-  genAiOutputTokens?: number;
-  genAiCacheReadInputTokens?: number;
-  genAiCacheCreationInputTokens?: number;
-  genAiReasoningOutputTokens?: number;
+  genAiSystem?: string | undefined;
+  genAiRequestModel?: string | undefined;
+  genAiResponseModel?: string | undefined;
+  genAiInputTokens?: number | undefined;
+  genAiOutputTokens?: number | undefined;
+  genAiCacheReadInputTokens?: number | undefined;
+  genAiCacheCreationInputTokens?: number | undefined;
+  genAiReasoningOutputTokens?: number | undefined;
 
   // Custom metadata
-  metadata?: Record<string, unknown>;
+  metadata?: Record<string, unknown> | undefined;
 }
 
 /**
@@ -140,6 +140,15 @@ export interface NodeLLMSpanProcessorOptions {
    */
   sessionIdExtractor?: (span: OTelReadableSpan) => string | undefined;
 
+  /**
+   * Whether to record spans that NodeLLM's own OpenTelemetry middleware
+   * created (they carry a `node_llm.request_id` attribute).
+   * Default: false. The Monitor middleware already records NodeLLM calls, so
+   * recording these spans too would count each call twice. Set to true when
+   * NodeLLM reaches Monitor only through OpenTelemetry.
+   */
+  includeNodeLLMSpans?: boolean;
+
   /**
    * Error handler for storage failures
    */

package/src/utils.ts

@@ -39,6 +39,15 @@ export function isAISpan(span: OTelReadableSpan): boolean {
   return !!(hasAIPrefix || hasAIAttributes);
 }
 
+/**
+ * Check if a span was created by NodeLLM's OpenTelemetry middleware
+ * (`OpenTelemetry(otel)` from @node-llm/core), which tags each span with
+ * `node_llm.request_id`.
+ */
+export function isNodeLLMSpan(span: OTelReadableSpan): boolean {
+  return span.attributes?.["node_llm.request_id"] !== undefined;
+}
+
 /**
  * Check if this is a top-level operation span (not a .doGenerate/.doStream child)
  */
@@ -291,6 +300,24 @@ export function generateRequestId(span: OTelReadableSpan): string {
   return `otel_${ctx.traceId.slice(0, 8)}_${ctx.spanId.slice(0, 8)}`;
 }
 
+/**
+ * Tags from span attributes: `llm.tag.<key>` (for example llm.tag.project) and the Vercel AI SDK's
+ * `ai.telemetry.metadata.tag.<key>`. Plain strings only; undefined when there are none.
+ */
+export function extractTags(span: OTelReadableSpan): Record<string, string> | undefined {
+  const tags: Record<string, string> = {};
+  for (const [name, value] of Object.entries(span.attributes ?? {})) {
+    const key = name.startsWith("llm.tag.")
+      ? name.slice(8)
+      : name.startsWith("ai.telemetry.metadata.tag.")
+        ? name.slice(26)
+        : undefined;
+    if (!key || value === undefined || value === null || value === "") continue;
+    tags[key.slice(0, 64)] = String(value).slice(0, 200);
+  }
+  return Object.keys(tags).length ? tags : undefined;
+}
+
 /**
  * Extract session ID from span attributes
  */

package/test/NodeLLMSpanProcessor.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import { NodeLLMSpanProcessor } from "../src/NodeLLMSpanProcessor.js";
-import { MonitoringStore, MonitoringEvent } from "@node-llm/monitor";
+import type { MonitoringStore, MonitoringEvent } from "@node-llm/monitor";
 
 describe("NodeLLMSpanProcessor", () => {
   let mockStore: MonitoringStore;
@@ -97,6 +97,37 @@ describe("NodeLLMSpanProcessor", () => {
     expect(event.payload.usage.reasoningTokens).toBe(15);
   });
 
+  it("should skip spans created by NodeLLM's OpenTelemetry middleware", async () => {
+    const span = createMockSpan("chat gpt-4o", {
+      attributes: {
+        "gen_ai.system": "openai",
+        "gen_ai.request.model": "gpt-4o",
+        "node_llm.request_id": "req-1"
+      }
+    });
+
+    processor.onEnd(span);
+    await processor.forceFlush();
+
+    expect(mockStore.saveEvent).not.toHaveBeenCalled();
+  });
+
+  it("should record NodeLLM spans when includeNodeLLMSpans is set", async () => {
+    processor = new NodeLLMSpanProcessor(mockStore, { includeNodeLLMSpans: true });
+    const span = createMockSpan("chat gpt-4o", {
+      attributes: {
+        "gen_ai.system": "openai",
+        "gen_ai.request.model": "gpt-4o",
+        "node_llm.request_id": "req-1"
+      }
+    });
+
+    processor.onEnd(span);
+    await processor.forceFlush();
+
+    expect(mockStore.saveEvent).toHaveBeenCalled();
+  });
+
   it("should ignore non-AI spans", async () => {
     const span = createMockSpan("http.get");
 

package/test/integration.test.ts

@@ -52,7 +52,7 @@ async function getFullEvent(
 async function getFirstEvent(store: MemoryAdapter): Promise<MonitoringEvent | undefined> {
   const traces = await getTraceSummaries(store);
   if (traces.length === 0) return undefined;
-  return getFullEvent(store, traces[0].requestId);
+  return getFullEvent(store, traces[0]!.requestId);
 }
 
 describe("NodeLLMSpanProcessor Integration", () => {
@@ -71,7 +71,7 @@ describe("NodeLLMSpanProcessor Integration", () => {
 
       const traces = await getTraceSummaries(store);
       expect(traces).toHaveLength(1);
-      expect(traces[0].provider).toBe("openai");
+      expect(traces[0]!.provider).toBe("openai");
     });
 
     it("should normalize openai.chat to openai", async () => {
@@ -79,7 +79,7 @@ describe("NodeLLMSpanProcessor Integration", () => {
       await processor.forceFlush();
 
       const traces = await getTraceSummaries(store);
-      expect(traces[0].provider).toBe("openai");
+      expect(traces[0]!.provider).toBe("openai");
     });
 
     it("should normalize anthropic.messages to anthropic", async () => {
@@ -87,7 +87,7 @@ describe("NodeLLMSpanProcessor Integration", () => {
       await processor.forceFlush();
 
       const traces = await getTraceSummaries(store);
-      expect(traces[0].provider).toBe("anthropic");
+      expect(traces[0]!.provider).toBe("anthropic");
     });
 
     it("should normalize google.generativeai to google", async () => {
@@ -95,7 +95,7 @@ describe("NodeLLMSpanProcessor Integration", () => {
       await processor.forceFlush();
 
       const traces = await getTraceSummaries(store);
-      expect(traces[0].provider).toBe("google");
+      expect(traces[0]!.provider).toBe("google");
     });
   });
 
@@ -105,7 +105,7 @@ describe("NodeLLMSpanProcessor Integration", () => {
       await processor.forceFlush();
 
       const traces = await getTraceSummaries(store);
-      expect(traces[0].model).toBe("gpt-4o-mini");
+      expect(traces[0]!.model).toBe("gpt-4o-mini");
     });
 
     it("should extract correct model from Anthropic spans", async () => {
@@ -113,7 +113,7 @@ describe("NodeLLMSpanProcessor Integration", () => {
       await processor.forceFlush();
 
       const traces = await getTraceSummaries(store);
-      expect(traces[0].model).toBe("claude-3-5-sonnet-20241022");
+      expect(traces[0]!.model).toBe("claude-3-5-sonnet-20241022");
     });
 
     it("should extract correct model from genAi format spans", async () => {
@@ -121,7 +121,7 @@ describe("NodeLLMSpanProcessor Integration", () => {
       await processor.forceFlush();
 
       const traces = await getTraceSummaries(store);
-      expect(traces[0].model).toBe("claude-3-opus");
+      expect(traces[0]!.model).toBe("claude-3-opus");
     });
   });
 
@@ -354,7 +354,7 @@ describe("NodeLLMSpanProcessor Integration", () => {
       await processor.forceFlush();
 
       const traces = await getTraceSummaries(store);
-      expect(traces[0].model).toBe("text-embedding-3-small");
+      expect(traces[0]!.model).toBe("text-embedding-3-small");
 
       const event = await getFirstEvent(store);
       expect(event!.payload.operationType).toBe("ai.embed");
@@ -365,7 +365,7 @@ describe("NodeLLMSpanProcessor Integration", () => {
       await processor.forceFlush();
 
       const traces = await getTraceSummaries(store);
-      expect(traces[0].model).toBe("text-embedding-3-large");
+      expect(traces[0]!.model).toBe("text-embedding-3-large");
 
       const event = await getFirstEvent(store);
       expect(event!.payload.operationType).toBe("ai.embedMany");
@@ -379,8 +379,8 @@ describe("NodeLLMSpanProcessor Integration", () => {
 
       const traces = await getTraceSummaries(store);
       // Cost should be calculated based on token counts
-      expect(traces[0].cost).toBeGreaterThan(0);
-      expect(typeof traces[0].cost).toBe("number");
+      expect(traces[0]!.cost).toBeGreaterThan(0);
+      expect(typeof traces[0]!.cost).toBe("number");
     });
 
     it("should estimate cost for Anthropic Claude", async () => {
@@ -388,7 +388,7 @@ describe("NodeLLMSpanProcessor Integration", () => {
       await processor.forceFlush();
 
       const traces = await getTraceSummaries(store);
-      expect(traces[0].cost).toBeGreaterThan(0);
+      expect(traces[0]!.cost).toBeGreaterThan(0);
     });
   });
 
@@ -399,7 +399,7 @@ describe("NodeLLMSpanProcessor Integration", () => {
 
       const traces = await getTraceSummaries(store);
       // Start: [1706918400, 0], End: [1706918401, 500000000] = 1500ms
-      expect(traces[0].duration).toBe(1500);
+      expect(traces[0]!.duration).toBe(1500);
     });
 
     it("should calculate correct duration for streaming spans", async () => {
@@ -408,7 +408,7 @@ describe("NodeLLMSpanProcessor Integration", () => {
 
       const traces = await getTraceSummaries(store);
       // Start: [1706918500, 0], End: [1706918502, 340000000] = 2340ms
-      expect(traces[0].duration).toBe(2340);
+      expect(traces[0]!.duration).toBe(2340);
     });
   });
 

package/test/utils.test.ts

@@ -13,7 +13,7 @@ import {
   normalizeModelName,
   normalizeProviderName
 } from "../src/utils.js";
-import { OTelReadableSpan } from "../src/types.js";
+import type { OTelReadableSpan } from "../src/types.js";
 
 describe("otel utils", () => {
   const mockSpanContext = () => ({
@@ -308,3 +308,19 @@ describe("otel utils", () => {
     });
   });
 });
+
+describe("extractTags", () => {
+  it("reads llm.tag.* and ai.telemetry.metadata.tag.* attributes as plain tags", async () => {
+    const { extractTags } = await import("../src/utils.js");
+    const span = {
+      attributes: {
+        "llm.tag.project": "Checkout",
+        "ai.telemetry.metadata.tag.env": "staging",
+        "llm.tag.empty": "",
+        other: "x"
+      }
+    } as any;
+    expect(extractTags(span)).toEqual({ project: "Checkout", env: "staging" });
+    expect(extractTags({ attributes: {} } as any)).toBeUndefined();
+  });
+});