@introspection-sdk/introspection-node 0.20.0 → 0.21.0

package/src/otel/integrations/index.ts

@@ -1,152 +0,0 @@
-/**
- * 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,
-  isModuleNotFound,
-  type Integration,
-  type IntegrationHandles,
-  type IntegrationSetupContext,
-} from "./base.js";
-
-export { DidNotEnable, isModuleNotFound };
-export type { Integration, IntegrationHandles, IntegrationSetupContext };
-
-/**
- * Built-in integrations, loaded lazily. Each integration probes its optional
- * framework package at runtime, so importing the OTel barrel never requires
- * every optional framework SDK to be installed.
- */
-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> = [];
-
-async function availableIntegrations(
-  integrations: Integration[],
-): Promise<Integration[]> {
-  const available: Integration[] = [];
-
-  for (const integration of integrations) {
-    if (integration.isAvailable && !(await integration.isAvailable())) {
-      continue;
-    }
-    available.push(integration);
-  }
-
-  return available;
-}
-
-/**
- * Return the built-in integrations whose framework is importable.
- *
- * Missing optional peer packages are expected and skipped quietly. Any OTHER
- * failure 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 availableIntegrations(found);
-}
-
-/**
- * Run each integration's `setupOnce` once, honouring `deactivates`.
- *
- * @returns the set of identifiers installed so far this process.
- */
-export async function setupIntegrations(
-  integrations: Integration[],
-  ctx: IntegrationSetupContext,
-): Promise<Set<string>> {
-  // First-wins de-dupe by identifier.
-  const byId = new Map<string, Integration>();
-  for (const integration of await availableIntegrations(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 = await 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

@@ -1,60 +0,0 @@
-/**
- * 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.
- */
-
-import {
-  importOptionalPeer,
-  isOptionalPeerInstalled,
-  OPTIONAL_PEERS,
-  type Integration,
-} from "./base.js";
-import type { IntrospectionCallbackHandler } from "../langchain-handler.js";
-
-const importLocal = (specifier: string) =>
-  import(specifier) as Promise<{
-    IntrospectionCallbackHandler: new (
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      options: any,
-    ) => IntrospectionCallbackHandler;
-  }>;
-
-const integration: Integration = {
-  identifier: "langchain",
-  isAvailable: () => isOptionalPeerInstalled(OPTIONAL_PEERS.langchainCallbacks),
-  // 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"],
-  async setupOnce({ token, serviceName, baseUrl, advanced, handles }) {
-    await importOptionalPeer(OPTIONAL_PEERS.langchainCallbacks);
-    const { IntrospectionCallbackHandler } = await importLocal(
-      "../langchain-handler.js",
-    );
-    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

@@ -1,48 +0,0 @@
-/**
- * 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 {
-  importOptionalPeer,
-  isOptionalPeerInstalled,
-  OPTIONAL_PEERS,
-  type Integration,
-} from "./base.js";
-
-const importLocal = (specifier: string) =>
-  import(specifier) as Promise<{
-    IntrospectionMastraExporter: new (
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      options: any,
-    ) => unknown;
-  }>;
-
-const integration: Integration = {
-  identifier: "mastra",
-  isAvailable: () =>
-    isOptionalPeerInstalled(OPTIONAL_PEERS.mastraObservability),
-  async setupOnce({ token, baseUrl, advanced, handles }) {
-    await importOptionalPeer(OPTIONAL_PEERS.mastraObservability);
-    const { IntrospectionMastraExporter } = await importLocal(
-      "../mastra-exporter.js",
-    );
-    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

@@ -1,47 +0,0 @@
-/**
- * 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 { IntrospectionTracingProcessor } from "../tracing-processor.js";
-import {
-  importOptionalPeer,
-  isOptionalPeerInstalled,
-  OPTIONAL_PEERS,
-  type Integration,
-} from "./base.js";
-
-interface OpenAIAgentsModule {
-  addTraceProcessor?: (processor: IntrospectionTracingProcessor) => void;
-}
-
-const integration: Integration = {
-  identifier: "openai_agents",
-  isAvailable: () => isOptionalPeerInstalled(OPTIONAL_PEERS.openaiAgents),
-  async setupOnce({ token, serviceName, baseUrl, advanced }) {
-    const { addTraceProcessor } = await importOptionalPeer<OpenAIAgentsModule>(
-      OPTIONAL_PEERS.openaiAgents,
-    );
-    if (!addTraceProcessor) {
-      throw new Error(
-        "Invalid @openai/agents module: addTraceProcessor missing",
-      );
-    }
-    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

@@ -1,28 +0,0 @@
-/**
- * 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)`.
- */
-
-import { IntrospectionPiInstrumentor } from "../pi.js";
-import {
-  importOptionalPeer,
-  isOptionalPeerInstalled,
-  OPTIONAL_PEERS,
-  type Integration,
-} from "./base.js";
-
-const integration: Integration = {
-  identifier: "pi",
-  isAvailable: () => isOptionalPeerInstalled(OPTIONAL_PEERS.piAgentCore),
-  async setupOnce({ handles }) {
-    await importOptionalPeer(OPTIONAL_PEERS.piAgentCore);
-    // 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

@@ -1,26 +0,0 @@
-/**
- * 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.
- */
-
-import {
-  isOptionalPeerInstalled,
-  OPTIONAL_PEERS,
-  type Integration,
-} from "./base.js";
-
-const integration: Integration = {
-  identifier: "vercel",
-  isAvailable: () => isOptionalPeerInstalled(OPTIONAL_PEERS.vercelAi),
-  setupOnce() {
-    // No-op: the shared IntrospectionSpanProcessor converts AI SDK spans.
-  },
-};
-
-export default integration;