@introspection-sdk/introspection-node 0.4.2 → 0.4.4

package/src/otel/integrations/index.ts

@@ -0,0 +1,151 @@
+/**
+ * Integration discovery + setup loader for `introspection.init()`.
+ *
+ * Mirrors the Python SDK's registry: built-in integrations are resolved
+ * lazily (a missing framework just skips its shim), `setupOnce` runs at most
+ * once per identifier per process, and an integration may `deactivate` others.
+ */
+
+import { logger } from "../../utils.js";
+import {
+  DidNotEnable,
+  type Integration,
+  type IntegrationHandles,
+  type IntegrationSetupContext,
+} from "./base.js";
+
+export { DidNotEnable };
+export type { Integration, IntegrationHandles, IntegrationSetupContext };
+
+/**
+ * Built-in integrations, loaded lazily. Each thunk dynamically imports an
+ * integration module; that module imports its framework at the top level, so
+ * if the framework is not installed the import rejects and the integration is
+ * skipped. Order matters only for `deactivates` resolution (handled below).
+ */
+const BUILTIN_INTEGRATIONS: ReadonlyArray<
+  () => Promise<{ default: Integration }>
+> = [
+  () => import("./anthropic.js"),
+  () => import("./gemini.js"),
+  () => import("./openai-agents.js"),
+  () => import("./vercel.js"),
+  () => import("./claude-agent.js"),
+  () => import("./langchain.js"),
+  () => import("./mastra.js"),
+  () => import("./pi.js"),
+];
+
+const installed = new Set<string>();
+// Teardown callbacks returned by integration setupOnce (e.g. uninstrument a
+// prototype patch), run by teardownIntegrations() on shutdown.
+const teardowns: Array<() => void> = [];
+
+/**
+ * Distinguish "framework package not installed" (expected — skip quietly) from
+ * a real error inside an installed integration (a bug we shouldn't hide).
+ */
+export function isModuleNotFound(e: unknown): boolean {
+  const code = (e as { code?: string } | null)?.code;
+  if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
+    return true;
+  }
+  const msg = e instanceof Error ? e.message : String(e);
+  return /Cannot find (module|package)|Failed to resolve/i.test(msg);
+}
+
+/**
+ * Return the built-in integrations whose framework is importable.
+ *
+ * Each module's top-level framework import determines availability: a missing
+ * package makes the dynamic import reject, which we log at debug and skip. Any
+ * OTHER failure (a real error inside an installed integration) is surfaced at
+ * warn level rather than silently swallowed — it's a bug, not an absent peer.
+ */
+export async function discoverIntegrations(): Promise<Integration[]> {
+  const found: Integration[] = [];
+  for (const load of BUILTIN_INTEGRATIONS) {
+    try {
+      const mod = await load();
+      if (mod.default) found.push(mod.default);
+    } catch (e) {
+      if (isModuleNotFound(e)) {
+        logger.debug(
+          `Skipping integration (framework not installed): ${String(e)}`,
+        );
+      } else {
+        logger.warn(
+          `Integration failed to load with an unexpected error (skipping): ${String(e)}`,
+        );
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * Run each integration's `setupOnce` once, honouring `deactivates`.
+ *
+ * @returns the set of identifiers installed so far this process.
+ */
+export function setupIntegrations(
+  integrations: Integration[],
+  ctx: IntegrationSetupContext,
+): Set<string> {
+  // First-wins de-dupe by identifier.
+  const byId = new Map<string, Integration>();
+  for (const integration of integrations) {
+    if (!byId.has(integration.identifier)) {
+      byId.set(integration.identifier, integration);
+    }
+  }
+
+  const disabled = new Set<string>();
+  for (const integration of byId.values()) {
+    for (const id of integration.deactivates ?? []) disabled.add(id);
+  }
+
+  for (const [identifier, integration] of byId) {
+    if (disabled.has(identifier)) {
+      logger.debug(
+        `Skipping ${identifier} (deactivated by another integration)`,
+      );
+      continue;
+    }
+    if (installed.has(identifier)) continue;
+    try {
+      const teardown = integration.setupOnce(ctx);
+      if (typeof teardown === "function") teardowns.push(teardown);
+      installed.add(identifier);
+    } catch (e) {
+      if (e instanceof DidNotEnable) {
+        logger.debug(`Could not enable ${identifier}: ${e.message}`);
+        continue;
+      }
+      throw e;
+    }
+  }
+
+  return new Set(installed);
+}
+
+/**
+ * Run every integration teardown and clear the run-once guard, so the next
+ * `setupIntegrations()` (e.g. after `introspection.shutdown()` + a fresh
+ * `init()`) re-installs against the rebuilt provider instead of being skipped.
+ */
+export function teardownIntegrations(): void {
+  for (const teardown of teardowns.splice(0)) {
+    try {
+      teardown();
+    } catch (e) {
+      logger.debug(`Error tearing down integration: ${String(e)}`);
+    }
+  }
+  installed.clear();
+}
+
+/** Clear the run-once guard (running teardowns). Test-only utility. */
+export function resetInstalledForTests(): void {
+  teardownIntegrations();
+}

package/src/otel/integrations/langchain.ts

@@ -0,0 +1,45 @@
+/**
+ * LangChain / LangGraph integration.
+ *
+ * The callback handler is attached per-invoke (`chain.invoke(input, { callbacks
+ * })`), so this integration builds the handler — pre-bound to the `init()`
+ * token — and publishes it via `introspection.getLangchainHandler()`.
+ *
+ * Deactivates the Anthropic integration: when LangChain drives the Anthropic
+ * model, the handler already traces the call, so the prototype-level Anthropic
+ * patch would double-trace it.
+ */
+
+// Presence gate.
+import "@langchain/core/callbacks/base";
+
+import { IntrospectionCallbackHandler } from "../langchain-handler.js";
+import type { Integration } from "./base.js";
+
+const integration: Integration = {
+  identifier: "langchain",
+  // Intentional, and matches the Python SDK: when @langchain/core is present,
+  // auto-discovery skips the always-on raw-Anthropic prototype patch so a
+  // LangChain → ChatAnthropic call isn't traced twice (once by LangChain's
+  // callback handler, once by the raw `messages.create` patch).
+  //
+  // Trade-off (by design): if an app has BOTH @langchain/core installed AND
+  // makes raw `@anthropic-ai/sdk` calls outside LangChain, those raw calls
+  // won't be auto-traced. To trace them, instrument explicitly with
+  // `new AnthropicInstrumentor().instrumentClass(...)`, or call
+  // `init({ autoDiscover: false, integrations: [anthropicIntegration] })`.
+  deactivates: ["anthropic"],
+  setupOnce({ token, serviceName, baseUrl, advanced, handles }) {
+    handles.langchainHandler = new IntrospectionCallbackHandler({
+      token,
+      serviceName,
+      baseUrl,
+      additionalHeaders: advanced?.additionalHeaders,
+      advanced: advanced?.spanExporter
+        ? { spanExporter: advanced.spanExporter }
+        : undefined,
+    });
+  },
+};
+
+export default integration;

package/src/otel/integrations/mastra.ts

@@ -0,0 +1,30 @@
+/**
+ * Mastra integration.
+ *
+ * The Mastra exporter is wired into Mastra's `observability.configs` rather
+ * than globally, so this integration builds the exporter — pre-bound to the
+ * `init()` token — and publishes it via `introspection.getMastraExporter()`.
+ *
+ * Importing `../mastra-exporter.js` (which requires `@mastra/observability`)
+ * is the presence gate: a missing Mastra makes discovery skip this shim.
+ */
+
+import { IntrospectionMastraExporter } from "../mastra-exporter.js";
+import type { Integration } from "./base.js";
+
+const integration: Integration = {
+  identifier: "mastra",
+  setupOnce({ token, baseUrl, advanced, handles }) {
+    handles.mastraExporter = new IntrospectionMastraExporter({
+      token,
+      baseUrl,
+      additionalHeaders: advanced?.additionalHeaders,
+      debug: advanced?.debug,
+      advanced: advanced?.spanExporter
+        ? { spanExporter: advanced.spanExporter }
+        : undefined,
+    });
+  },
+};
+
+export default integration;

package/src/otel/integrations/openai-agents.ts

@@ -0,0 +1,31 @@
+/**
+ * OpenAI Agents SDK integration.
+ *
+ * Registers an {@link IntrospectionTracingProcessor} with the Agents SDK's
+ * global trace pipeline. `addTraceProcessor` appends, preserving any processors
+ * other integrations (e.g. a vendor exporter) already registered.
+ */
+
+import { addTraceProcessor } from "@openai/agents";
+
+import { IntrospectionTracingProcessor } from "../tracing-processor.js";
+import type { Integration } from "./base.js";
+
+const integration: Integration = {
+  identifier: "openai_agents",
+  setupOnce({ token, serviceName, baseUrl, advanced }) {
+    addTraceProcessor(
+      new IntrospectionTracingProcessor({
+        token,
+        serviceName,
+        baseUrl,
+        additionalHeaders: advanced?.additionalHeaders,
+        advanced: advanced?.spanExporter
+          ? { spanExporter: advanced.spanExporter }
+          : undefined,
+      }),
+    );
+  },
+};
+
+export default integration;

package/src/otel/integrations/pi.ts

@@ -0,0 +1,24 @@
+/**
+ * Pi Agent SDK integration.
+ *
+ * The Pi instrumentor wraps a specific `Agent` instance, so this integration
+ * builds the instrumentor — bound to the shared provider's global tracer — and
+ * publishes it via `introspection.instrumentPi(agent, meta)`.
+ */
+
+// Presence gate.
+import "@mariozechner/pi-agent-core";
+
+import { IntrospectionPiInstrumentor } from "../pi.js";
+import type { Integration } from "./base.js";
+
+const integration: Integration = {
+  identifier: "pi",
+  setupOnce({ handles }) {
+    // The instrumentor emits onto the global tracer, which `init()` has just
+    // registered with the shared IntrospectionSpanProcessor.
+    handles.piInstrumentor = new IntrospectionPiInstrumentor();
+  },
+};
+
+export default integration;

package/src/otel/integrations/vercel.ts

@@ -0,0 +1,24 @@
+/**
+ * Vercel AI SDK integration.
+ *
+ * The AI SDK emits `ai.*` / `gen_ai.*` attributes natively via OTel when
+ * `experimental_telemetry` is enabled. The shared provider already carries an
+ * {@link IntrospectionSpanProcessor}, which converts those `ai.*` attributes to
+ * canonical `gen_ai.*` semconv at span end — so there is nothing to patch here.
+ * This integration exists so auto-discovery reports the AI SDK as detected and
+ * (via its top-level import) is skipped when `ai` is not installed.
+ */
+
+// Presence gate: a missing `ai` package makes this module's import reject.
+import "ai";
+
+import type { Integration } from "./base.js";
+
+const integration: Integration = {
+  identifier: "vercel",
+  setupOnce() {
+    // No-op: the shared IntrospectionSpanProcessor converts AI SDK spans.
+  },
+};
+
+export default integration;

package/src/{langchain-handler.ts → otel/langchain-handler.ts}

@@ -34,6 +34,7 @@ import type { ChainValues } from "@langchain/core/utils/types";
 
 import {
   context as otelContext,
+  propagation,
   ROOT_CONTEXT,
   SpanStatusCode,
   trace as otelTrace,
@@ -51,8 +52,8 @@ import { resourceFromAttributes } from "@opentelemetry/resources";
 import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 import { randomUUID } from "crypto";
 
-import { logger, withOtlpHttpsProxy } from "./utils.js";
-import { VERSION } from "./version.js";
+import { logger, withOtlpHttpsProxy } from "../utils.js";
+import { VERSION } from "../version.js";
 import type {
   InputMessage,
   OutputMessage,
@@ -77,7 +78,7 @@ export interface LangChainHandlerAdvancedOptions {
 export interface IntrospectionCallbackHandlerOptions {
   /** Authentication token (env: INTROSPECTION_TOKEN). */
   token?: string;
-  /** Base URL for the API (env: INTROSPECTION_BASE_URL). */
+  /** Base URL for the API (env: INTROSPECTION_BASE_OTEL_URL). */
   baseUrl?: string;
   /** Service name for telemetry (env: INTROSPECTION_SERVICE_NAME). */
   serviceName?: string;
@@ -143,7 +144,7 @@ export class IntrospectionCallbackHandler extends BaseCallbackHandler {
 
       const baseUrl =
         options.baseUrl ||
-        process.env.INTROSPECTION_BASE_URL ||
+        process.env.INTROSPECTION_BASE_OTEL_URL ||
         "https://otel.introspection.dev";
 
       const endpoint = baseUrl.endsWith("/v1/traces")
@@ -246,11 +247,17 @@ export class IntrospectionCallbackHandler extends BaseCallbackHandler {
       this._spanParents.set(runId, parentRunId);
     }
 
-    // Walk up parents to find first non-wrapper name for gen_ai.agent.name
-    const agentName = this._findAgentName(parentRunId);
+    // Baggage wins so per-call agent identity (e.g. via withAgent())
+    // overrides the parent-span-name walk used as a default.
+    const baggageAgentName = this._readBaggage("gen_ai.agent.name");
+    const agentName = baggageAgentName || this._findAgentName(parentRunId);
     if (agentName) {
       span.setAttribute("gen_ai.agent.name", agentName);
     }
+    const baggageAgentId = this._readBaggage("gen_ai.agent.id");
+    if (baggageAgentId) {
+      span.setAttribute("gen_ai.agent.id", baggageAgentId);
+    }
 
     return span;
   }
@@ -452,6 +459,31 @@ export class IntrospectionCallbackHandler extends BaseCallbackHandler {
       if (typeof outputTokens === "number") {
         otelSpan.setAttribute("gen_ai.usage.output_tokens", outputTokens);
       }
+      // Flat field (legacy format) or nested cache_creation object (Claude 4+).
+      const cacheCreationObj = tokenUsage["cache_creation"] as
+        | Record<string, unknown>
+        | undefined;
+      const cacheWriteTokens =
+        tokenUsage["cache_creation_input_tokens"] ||
+        tokenUsage["cacheCreationInputTokens"] ||
+        ((cacheCreationObj?.["ephemeral_5m_input_tokens"] as number) || 0) +
+          ((cacheCreationObj?.["ephemeral_1h_input_tokens"] as number) || 0) ||
+        undefined;
+      if (typeof cacheWriteTokens === "number") {
+        otelSpan.setAttribute(
+          "gen_ai.usage.cache_creation.input_tokens",
+          cacheWriteTokens,
+        );
+      }
+      const cacheReadTokens =
+        tokenUsage["cache_read_input_tokens"] ||
+        tokenUsage["cacheReadInputTokens"];
+      if (typeof cacheReadTokens === "number") {
+        otelSpan.setAttribute(
+          "gen_ai.usage.cache_read.input_tokens",
+          cacheReadTokens,
+        );
+      }
     }
 
     const model = usage?.["model"] || usage?.["model_name"];
@@ -659,9 +691,24 @@ export class IntrospectionCallbackHandler extends BaseCallbackHandler {
     if (threadId !== undefined && threadId !== null) {
       return String(threadId);
     }
+    const baggageConvId = this._readBaggage("gen_ai.conversation.id");
+    if (baggageConvId) return baggageConvId;
     return this._conversationId;
   }
 
+  /**
+   * Read a single value from the active OTel baggage. Returns undefined when
+   * no propagator is installed or the key is absent.
+   *
+   * Used so callers can scope LangChain calls with
+   * `IntrospectionClient.withAgent()` / `.withConversation()` /
+   * `.withGenAi()` without threading metadata through every invoke().
+   */
+  private _readBaggage(key: string): string | undefined {
+    const baggage = propagation.getBaggage(otelContext.active());
+    return baggage?.getEntry(key)?.value;
+  }
+
   private _convertMessages(messages: BaseMessage[]): {
     inputMessages: InputMessage[];
     systemInstructions: string[];