@node-llm/monitor-otel 0.1.0 → 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NodeLLM contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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"];
@@ -75,6 +78,8 @@ function extractAIAttributes(span) {
     // Usage - AI SDK attributes
     promptTokens: getNumber(attrs, "ai.usage.promptTokens"),
     completionTokens: getNumber(attrs, "ai.usage.completionTokens"),
+    cachedInputTokens: getNumber(attrs, "ai.usage.cachedInputTokens"),
+    reasoningTokens: getNumber(attrs, "ai.usage.reasoningTokens"),
     // Timing (streaming)
     msToFirstChunk: getNumber(attrs, "ai.response.msToFirstChunk"),
     msToFinish: getNumber(attrs, "ai.response.msToFinish"),
@@ -90,6 +95,9 @@ function extractAIAttributes(span) {
     genAiResponseModel: getString(attrs, "gen_ai.response.model"),
     genAiInputTokens: getNumber(attrs, "gen_ai.usage.input_tokens"),
     genAiOutputTokens: getNumber(attrs, "gen_ai.usage.output_tokens"),
+    genAiCacheReadInputTokens: getNumber(attrs, "gen_ai.usage.cache_read.input_tokens"),
+    genAiCacheCreationInputTokens: getNumber(attrs, "gen_ai.usage.cache_creation.input_tokens"),
+    genAiReasoningOutputTokens: getNumber(attrs, "gen_ai.usage.reasoning.output_tokens"),
     // Custom metadata
     metadata: Object.keys(metadata).length > 0 ? metadata : void 0
   };
@@ -156,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");
@@ -174,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 = {
@@ -195,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;
     }
@@ -208,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
@@ -229,6 +250,9 @@ var NodeLLMSpanProcessor = class {
     const duration = calculateDurationMs(span.startTime, span.endTime);
     const promptTokens = attrs.promptTokens ?? attrs.genAiInputTokens ?? 0;
     const completionTokens = attrs.completionTokens ?? attrs.genAiOutputTokens ?? 0;
+    const cachedTokens = attrs.cachedInputTokens ?? attrs.genAiCacheReadInputTokens ?? 0;
+    const cacheCreationTokens = attrs.genAiCacheCreationInputTokens ?? 0;
+    const reasoningTokens = attrs.reasoningTokens ?? attrs.genAiReasoningOutputTokens ?? 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);
@@ -239,7 +263,10 @@ var NodeLLMSpanProcessor = class {
       usage: {
         promptTokens,
         completionTokens,
-        totalTokens: promptTokens + completionTokens
+        totalTokens: promptTokens + completionTokens,
+        ...cachedTokens > 0 && { cachedTokens },
+        ...cacheCreationTokens > 0 && { cacheCreationTokens },
+        ...reasoningTokens > 0 && { reasoningTokens }
       },
       // Streaming metrics
       ...attrs.msToFirstChunk !== void 0 && {
@@ -285,6 +312,7 @@ var NodeLLMSpanProcessor = class {
         }
       };
     }
+    const tags = extractTags(span);
     if (span.status.code === 2) {
       payload.error = span.status.message || "Unknown error";
     }
@@ -299,7 +327,8 @@ var NodeLLMSpanProcessor = class {
       payload,
       createdAt: /* @__PURE__ */ new Date(),
       provider,
-      model
+      model,
+      ...tags ? { tags } : {}
     };
   }
   /**
@@ -307,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,20 +1,14 @@
 {
   "name": "@node-llm/monitor-otel",
-  "version": "0.1.0",
+  "version": "0.2.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"
+    "@opentelemetry/sdk-trace-base": "^1.18.1",
+    "@node-llm/monitor": "0.5.0"
   },
   "devDependencies": {
     "@types/node": "^25.2.0",
@@ -22,5 +16,11 @@
     "tsup": "^8.0.1",
     "typescript": "^5.3.3",
     "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "lint": "eslint .",
+    "test": "vitest run"
   }
-}
+}

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));
   }
 
   /**
@@ -137,6 +147,9 @@ export class NodeLLMSpanProcessor implements OTelSpanProcessor {
     // Calculate token counts (prefer AI SDK attributes, fallback to GenAI conventions)
     const promptTokens = attrs.promptTokens ?? attrs.genAiInputTokens ?? 0;
     const completionTokens = attrs.completionTokens ?? attrs.genAiOutputTokens ?? 0;
+    const cachedTokens = attrs.cachedInputTokens ?? attrs.genAiCacheReadInputTokens ?? 0;
+    const cacheCreationTokens = attrs.genAiCacheCreationInputTokens ?? 0;
+    const reasoningTokens = attrs.reasoningTokens ?? attrs.genAiReasoningOutputTokens ?? 0;
 
     // Estimate cost
     const cost = estimateCost(provider, model, promptTokens, completionTokens);
@@ -159,7 +172,10 @@ export class NodeLLMSpanProcessor implements OTelSpanProcessor {
       usage: {
         promptTokens,
         completionTokens,
-        totalTokens: promptTokens + completionTokens
+        totalTokens: promptTokens + completionTokens,
+        ...(cachedTokens > 0 && { cachedTokens }),
+        ...(cacheCreationTokens > 0 && { cacheCreationTokens }),
+        ...(reasoningTokens > 0 && { reasoningTokens })
       },
       // Streaming metrics
       ...(attrs.msToFirstChunk !== undefined && {
@@ -210,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";
@@ -226,7 +244,8 @@ export class NodeLLMSpanProcessor implements OTelSpanProcessor {
       payload,
       createdAt: new Date(),
       provider,
-      model
+      model,
+      ...(tags ? { tags } : {})
     };
   }
 
@@ -235,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,51 +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 | 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;
+  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;
 }
 
 /**
@@ -134,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)
  */
@@ -131,6 +140,8 @@ export function extractAIAttributes(span: OTelReadableSpan): AISpanAttributes {
     // Usage - AI SDK attributes
     promptTokens: getNumber(attrs, "ai.usage.promptTokens"),
     completionTokens: getNumber(attrs, "ai.usage.completionTokens"),
+    cachedInputTokens: getNumber(attrs, "ai.usage.cachedInputTokens"),
+    reasoningTokens: getNumber(attrs, "ai.usage.reasoningTokens"),
 
     // Timing (streaming)
     msToFirstChunk: getNumber(attrs, "ai.response.msToFirstChunk"),
@@ -149,6 +160,9 @@ export function extractAIAttributes(span: OTelReadableSpan): AISpanAttributes {
     genAiResponseModel: getString(attrs, "gen_ai.response.model"),
     genAiInputTokens: getNumber(attrs, "gen_ai.usage.input_tokens"),
     genAiOutputTokens: getNumber(attrs, "gen_ai.usage.output_tokens"),
+    genAiCacheReadInputTokens: getNumber(attrs, "gen_ai.usage.cache_read.input_tokens"),
+    genAiCacheCreationInputTokens: getNumber(attrs, "gen_ai.usage.cache_creation.input_tokens"),
+    genAiReasoningOutputTokens: getNumber(attrs, "gen_ai.usage.reasoning.output_tokens"),
 
     // Custom metadata
     metadata: Object.keys(metadata).length > 0 ? metadata : undefined
@@ -286,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;
@@ -72,6 +72,62 @@ describe("NodeLLMSpanProcessor", () => {
     expect(event.payload.usage.totalTokens).toBe(225);
   });
 
+  it("should include cache/reasoning token usage from GenAI spans", async () => {
+    const span = createMockSpan("gen_ai.chat", {
+      attributes: {
+        "ai.model.id": undefined,
+        "ai.model.provider": undefined,
+        "gen_ai.system": "anthropic",
+        "gen_ai.request.model": "claude-3-5-sonnet",
+        "gen_ai.usage.input_tokens": 150,
+        "gen_ai.usage.output_tokens": 75,
+        "gen_ai.usage.cache_read.input_tokens": 100,
+        "gen_ai.usage.cache_creation.input_tokens": 20,
+        "gen_ai.usage.reasoning.output_tokens": 15
+      }
+    });
+
+    processor.onEnd(span);
+    await processor.forceFlush();
+
+    const event = (mockStore.saveEvent as any).mock.calls[0][0];
+
+    expect(event.payload.usage.cachedTokens).toBe(100);
+    expect(event.payload.usage.cacheCreationTokens).toBe(20);
+    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 = () => ({
@@ -106,6 +106,38 @@ describe("otel utils", () => {
       expect(attrs.genAiOutputTokens).toBe(25);
     });
 
+    it("should extract OTel GenAI cache/reasoning token attributes", () => {
+      const span = {
+        attributes: {
+          "gen_ai.usage.input_tokens": 100,
+          "gen_ai.usage.output_tokens": 50,
+          "gen_ai.usage.cache_read.input_tokens": 75,
+          "gen_ai.usage.cache_creation.input_tokens": 25,
+          "gen_ai.usage.reasoning.output_tokens": 10
+        }
+      } as any;
+
+      const attrs = extractAIAttributes(span);
+      expect(attrs.genAiCacheReadInputTokens).toBe(75);
+      expect(attrs.genAiCacheCreationInputTokens).toBe(25);
+      expect(attrs.genAiReasoningOutputTokens).toBe(10);
+    });
+
+    it("should extract Vercel AI SDK cache/reasoning token attributes", () => {
+      const span = {
+        attributes: {
+          "ai.usage.promptTokens": 100,
+          "ai.usage.completionTokens": 50,
+          "ai.usage.cachedInputTokens": 60,
+          "ai.usage.reasoningTokens": 12
+        }
+      } as any;
+
+      const attrs = extractAIAttributes(span);
+      expect(attrs.cachedInputTokens).toBe(60);
+      expect(attrs.reasoningTokens).toBe(12);
+    });
+
     it("should extract custom metadata", () => {
       const span = {
         attributes: {
@@ -276,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();
+  });
+});