@introspection-sdk/introspection-node 0.4.3 → 0.4.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (122) hide show
  1. package/.turbo/turbo-build.log +1 -1
  2. package/dist/otel/anthropic.d.ts +14 -12
  3. package/dist/otel/anthropic.d.ts.map +1 -1
  4. package/dist/otel/anthropic.js +89 -47
  5. package/dist/otel/anthropic.js.map +1 -1
  6. package/dist/otel/gemini.d.ts +15 -7
  7. package/dist/otel/gemini.d.ts.map +1 -1
  8. package/dist/otel/gemini.js +88 -37
  9. package/dist/otel/gemini.js.map +1 -1
  10. package/dist/otel/index.d.ts +5 -0
  11. package/dist/otel/index.d.ts.map +1 -1
  12. package/dist/otel/index.js +8 -0
  13. package/dist/otel/index.js.map +1 -1
  14. package/dist/otel/init.d.ts +126 -0
  15. package/dist/otel/init.d.ts.map +1 -0
  16. package/dist/otel/init.js +259 -0
  17. package/dist/otel/init.js.map +1 -0
  18. package/dist/otel/integrations/anthropic.d.ts +10 -0
  19. package/dist/otel/integrations/anthropic.d.ts.map +1 -0
  20. package/dist/otel/integrations/anthropic.js +22 -0
  21. package/dist/otel/integrations/anthropic.js.map +1 -0
  22. package/dist/otel/integrations/base.d.ts +83 -0
  23. package/dist/otel/integrations/base.d.ts.map +1 -0
  24. package/dist/otel/integrations/base.js +23 -0
  25. package/dist/otel/integrations/base.js.map +1 -0
  26. package/dist/otel/integrations/claude-agent.d.ts +13 -0
  27. package/dist/otel/integrations/claude-agent.d.ts.map +1 -0
  28. package/dist/otel/integrations/claude-agent.js +27 -0
  29. package/dist/otel/integrations/claude-agent.js.map +1 -0
  30. package/dist/otel/integrations/gemini.d.ts +11 -0
  31. package/dist/otel/integrations/gemini.d.ts.map +1 -0
  32. package/dist/otel/integrations/gemini.js +21 -0
  33. package/dist/otel/integrations/gemini.js.map +1 -0
  34. package/dist/otel/integrations/index.d.ts +39 -0
  35. package/dist/otel/integrations/index.d.ts.map +1 -0
  36. package/dist/otel/integrations/index.js +131 -0
  37. package/dist/otel/integrations/index.js.map +1 -0
  38. package/dist/otel/integrations/langchain.d.ts +16 -0
  39. package/dist/otel/integrations/langchain.d.ts.map +1 -0
  40. package/dist/otel/integrations/langchain.js +41 -0
  41. package/dist/otel/integrations/langchain.js.map +1 -0
  42. package/dist/otel/integrations/mastra.d.ts +14 -0
  43. package/dist/otel/integrations/mastra.d.ts.map +1 -0
  44. package/dist/otel/integrations/mastra.js +27 -0
  45. package/dist/otel/integrations/mastra.js.map +1 -0
  46. package/dist/otel/integrations/openai-agents.d.ts +11 -0
  47. package/dist/otel/integrations/openai-agents.d.ts.map +1 -0
  48. package/dist/otel/integrations/openai-agents.js +25 -0
  49. package/dist/otel/integrations/openai-agents.js.map +1 -0
  50. package/dist/otel/integrations/pi.d.ts +12 -0
  51. package/dist/otel/integrations/pi.d.ts.map +1 -0
  52. package/dist/otel/integrations/pi.js +20 -0
  53. package/dist/otel/integrations/pi.js.map +1 -0
  54. package/dist/otel/integrations/vercel.d.ts +15 -0
  55. package/dist/otel/integrations/vercel.d.ts.map +1 -0
  56. package/dist/otel/integrations/vercel.js +20 -0
  57. package/dist/otel/integrations/vercel.js.map +1 -0
  58. package/dist/otel/register.d.ts +8 -0
  59. package/dist/otel/register.d.ts.map +1 -0
  60. package/dist/otel/register.js +48 -0
  61. package/dist/otel/register.js.map +1 -0
  62. package/dist/otel/setup.d.ts +29 -0
  63. package/dist/otel/setup.d.ts.map +1 -1
  64. package/dist/otel/setup.js +22 -3
  65. package/dist/otel/setup.js.map +1 -1
  66. package/dist/utils.d.ts +10 -0
  67. package/dist/utils.d.ts.map +1 -1
  68. package/dist/utils.js +12 -4
  69. package/dist/utils.js.map +1 -1
  70. package/package.json +17 -5
  71. package/src/otel/anthropic.ts +128 -63
  72. package/src/otel/gemini.ts +139 -45
  73. package/src/otel/index.ts +41 -0
  74. package/src/otel/init.ts +411 -0
  75. package/src/otel/integrations/anthropic.ts +26 -0
  76. package/src/otel/integrations/base.ts +95 -0
  77. package/src/otel/integrations/claude-agent.ts +32 -0
  78. package/src/otel/integrations/gemini.ts +25 -0
  79. package/src/otel/integrations/index.ts +151 -0
  80. package/src/otel/integrations/langchain.ts +45 -0
  81. package/src/otel/integrations/mastra.ts +30 -0
  82. package/src/otel/integrations/openai-agents.ts +31 -0
  83. package/src/otel/integrations/pi.ts +24 -0
  84. package/src/otel/integrations/vercel.ts +24 -0
  85. package/src/otel/register.ts +50 -0
  86. package/src/otel/setup.ts +44 -3
  87. package/src/utils.ts +12 -5
  88. package/.turbo/turbo-check-types.log +0 -4
  89. package/.turbo/turbo-lint.log +0 -5
  90. package/dist/ai-sdk-integration.d.ts +0 -123
  91. package/dist/ai-sdk-integration.d.ts.map +0 -1
  92. package/dist/ai-sdk-integration.js +0 -475
  93. package/dist/anthropic.d.ts +0 -54
  94. package/dist/anthropic.d.ts.map +0 -1
  95. package/dist/anthropic.js +0 -375
  96. package/dist/claude-hooks.d.ts +0 -328
  97. package/dist/claude-hooks.d.ts.map +0 -1
  98. package/dist/claude-hooks.js +0 -571
  99. package/dist/claude-wrapper.d.ts +0 -93
  100. package/dist/claude-wrapper.d.ts.map +0 -1
  101. package/dist/claude-wrapper.js +0 -154
  102. package/dist/converters/ai-sdk.d.ts +0 -65
  103. package/dist/converters/ai-sdk.d.ts.map +0 -1
  104. package/dist/converters/ai-sdk.js +0 -261
  105. package/dist/converters/openclaw.d.ts +0 -16
  106. package/dist/converters/openclaw.d.ts.map +0 -1
  107. package/dist/converters/openclaw.js +0 -49
  108. package/dist/langchain-handler.d.ts +0 -103
  109. package/dist/langchain-handler.d.ts.map +0 -1
  110. package/dist/langchain-handler.js +0 -518
  111. package/dist/mastra-exporter.d.ts +0 -85
  112. package/dist/mastra-exporter.d.ts.map +0 -1
  113. package/dist/mastra-exporter.js +0 -471
  114. package/dist/span-processor.d.ts +0 -62
  115. package/dist/span-processor.d.ts.map +0 -1
  116. package/dist/span-processor.js +0 -313
  117. package/dist/tracing-processor.d.ts +0 -136
  118. package/dist/tracing-processor.d.ts.map +0 -1
  119. package/dist/tracing-processor.js +0 -368
  120. package/dist/types/genai.d.ts +0 -165
  121. package/dist/types/genai.d.ts.map +0 -1
  122. package/dist/types/genai.js +0 -82
@@ -0,0 +1,151 @@
1
+ /**
2
+ * Integration discovery + setup loader for `introspection.init()`.
3
+ *
4
+ * Mirrors the Python SDK's registry: built-in integrations are resolved
5
+ * lazily (a missing framework just skips its shim), `setupOnce` runs at most
6
+ * once per identifier per process, and an integration may `deactivate` others.
7
+ */
8
+
9
+ import { logger } from "../../utils.js";
10
+ import {
11
+ DidNotEnable,
12
+ type Integration,
13
+ type IntegrationHandles,
14
+ type IntegrationSetupContext,
15
+ } from "./base.js";
16
+
17
+ export { DidNotEnable };
18
+ export type { Integration, IntegrationHandles, IntegrationSetupContext };
19
+
20
+ /**
21
+ * Built-in integrations, loaded lazily. Each thunk dynamically imports an
22
+ * integration module; that module imports its framework at the top level, so
23
+ * if the framework is not installed the import rejects and the integration is
24
+ * skipped. Order matters only for `deactivates` resolution (handled below).
25
+ */
26
+ const BUILTIN_INTEGRATIONS: ReadonlyArray<
27
+ () => Promise<{ default: Integration }>
28
+ > = [
29
+ () => import("./anthropic.js"),
30
+ () => import("./gemini.js"),
31
+ () => import("./openai-agents.js"),
32
+ () => import("./vercel.js"),
33
+ () => import("./claude-agent.js"),
34
+ () => import("./langchain.js"),
35
+ () => import("./mastra.js"),
36
+ () => import("./pi.js"),
37
+ ];
38
+
39
+ const installed = new Set<string>();
40
+ // Teardown callbacks returned by integration setupOnce (e.g. uninstrument a
41
+ // prototype patch), run by teardownIntegrations() on shutdown.
42
+ const teardowns: Array<() => void> = [];
43
+
44
+ /**
45
+ * Distinguish "framework package not installed" (expected — skip quietly) from
46
+ * a real error inside an installed integration (a bug we shouldn't hide).
47
+ */
48
+ export function isModuleNotFound(e: unknown): boolean {
49
+ const code = (e as { code?: string } | null)?.code;
50
+ if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
51
+ return true;
52
+ }
53
+ const msg = e instanceof Error ? e.message : String(e);
54
+ return /Cannot find (module|package)|Failed to resolve/i.test(msg);
55
+ }
56
+
57
+ /**
58
+ * Return the built-in integrations whose framework is importable.
59
+ *
60
+ * Each module's top-level framework import determines availability: a missing
61
+ * package makes the dynamic import reject, which we log at debug and skip. Any
62
+ * OTHER failure (a real error inside an installed integration) is surfaced at
63
+ * warn level rather than silently swallowed — it's a bug, not an absent peer.
64
+ */
65
+ export async function discoverIntegrations(): Promise<Integration[]> {
66
+ const found: Integration[] = [];
67
+ for (const load of BUILTIN_INTEGRATIONS) {
68
+ try {
69
+ const mod = await load();
70
+ if (mod.default) found.push(mod.default);
71
+ } catch (e) {
72
+ if (isModuleNotFound(e)) {
73
+ logger.debug(
74
+ `Skipping integration (framework not installed): ${String(e)}`,
75
+ );
76
+ } else {
77
+ logger.warn(
78
+ `Integration failed to load with an unexpected error (skipping): ${String(e)}`,
79
+ );
80
+ }
81
+ }
82
+ }
83
+ return found;
84
+ }
85
+
86
+ /**
87
+ * Run each integration's `setupOnce` once, honouring `deactivates`.
88
+ *
89
+ * @returns the set of identifiers installed so far this process.
90
+ */
91
+ export function setupIntegrations(
92
+ integrations: Integration[],
93
+ ctx: IntegrationSetupContext,
94
+ ): Set<string> {
95
+ // First-wins de-dupe by identifier.
96
+ const byId = new Map<string, Integration>();
97
+ for (const integration of integrations) {
98
+ if (!byId.has(integration.identifier)) {
99
+ byId.set(integration.identifier, integration);
100
+ }
101
+ }
102
+
103
+ const disabled = new Set<string>();
104
+ for (const integration of byId.values()) {
105
+ for (const id of integration.deactivates ?? []) disabled.add(id);
106
+ }
107
+
108
+ for (const [identifier, integration] of byId) {
109
+ if (disabled.has(identifier)) {
110
+ logger.debug(
111
+ `Skipping ${identifier} (deactivated by another integration)`,
112
+ );
113
+ continue;
114
+ }
115
+ if (installed.has(identifier)) continue;
116
+ try {
117
+ const teardown = integration.setupOnce(ctx);
118
+ if (typeof teardown === "function") teardowns.push(teardown);
119
+ installed.add(identifier);
120
+ } catch (e) {
121
+ if (e instanceof DidNotEnable) {
122
+ logger.debug(`Could not enable ${identifier}: ${e.message}`);
123
+ continue;
124
+ }
125
+ throw e;
126
+ }
127
+ }
128
+
129
+ return new Set(installed);
130
+ }
131
+
132
+ /**
133
+ * Run every integration teardown and clear the run-once guard, so the next
134
+ * `setupIntegrations()` (e.g. after `introspection.shutdown()` + a fresh
135
+ * `init()`) re-installs against the rebuilt provider instead of being skipped.
136
+ */
137
+ export function teardownIntegrations(): void {
138
+ for (const teardown of teardowns.splice(0)) {
139
+ try {
140
+ teardown();
141
+ } catch (e) {
142
+ logger.debug(`Error tearing down integration: ${String(e)}`);
143
+ }
144
+ }
145
+ installed.clear();
146
+ }
147
+
148
+ /** Clear the run-once guard (running teardowns). Test-only utility. */
149
+ export function resetInstalledForTests(): void {
150
+ teardownIntegrations();
151
+ }
@@ -0,0 +1,45 @@
1
+ /**
2
+ * LangChain / LangGraph integration.
3
+ *
4
+ * The callback handler is attached per-invoke (`chain.invoke(input, { callbacks
5
+ * })`), so this integration builds the handler — pre-bound to the `init()`
6
+ * token — and publishes it via `introspection.getLangchainHandler()`.
7
+ *
8
+ * Deactivates the Anthropic integration: when LangChain drives the Anthropic
9
+ * model, the handler already traces the call, so the prototype-level Anthropic
10
+ * patch would double-trace it.
11
+ */
12
+
13
+ // Presence gate.
14
+ import "@langchain/core/callbacks/base";
15
+
16
+ import { IntrospectionCallbackHandler } from "../langchain-handler.js";
17
+ import type { Integration } from "./base.js";
18
+
19
+ const integration: Integration = {
20
+ identifier: "langchain",
21
+ // Intentional, and matches the Python SDK: when @langchain/core is present,
22
+ // auto-discovery skips the always-on raw-Anthropic prototype patch so a
23
+ // LangChain → ChatAnthropic call isn't traced twice (once by LangChain's
24
+ // callback handler, once by the raw `messages.create` patch).
25
+ //
26
+ // Trade-off (by design): if an app has BOTH @langchain/core installed AND
27
+ // makes raw `@anthropic-ai/sdk` calls outside LangChain, those raw calls
28
+ // won't be auto-traced. To trace them, instrument explicitly with
29
+ // `new AnthropicInstrumentor().instrumentClass(...)`, or call
30
+ // `init({ autoDiscover: false, integrations: [anthropicIntegration] })`.
31
+ deactivates: ["anthropic"],
32
+ setupOnce({ token, serviceName, baseUrl, advanced, handles }) {
33
+ handles.langchainHandler = new IntrospectionCallbackHandler({
34
+ token,
35
+ serviceName,
36
+ baseUrl,
37
+ additionalHeaders: advanced?.additionalHeaders,
38
+ advanced: advanced?.spanExporter
39
+ ? { spanExporter: advanced.spanExporter }
40
+ : undefined,
41
+ });
42
+ },
43
+ };
44
+
45
+ export default integration;
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Mastra integration.
3
+ *
4
+ * The Mastra exporter is wired into Mastra's `observability.configs` rather
5
+ * than globally, so this integration builds the exporter — pre-bound to the
6
+ * `init()` token — and publishes it via `introspection.getMastraExporter()`.
7
+ *
8
+ * Importing `../mastra-exporter.js` (which requires `@mastra/observability`)
9
+ * is the presence gate: a missing Mastra makes discovery skip this shim.
10
+ */
11
+
12
+ import { IntrospectionMastraExporter } from "../mastra-exporter.js";
13
+ import type { Integration } from "./base.js";
14
+
15
+ const integration: Integration = {
16
+ identifier: "mastra",
17
+ setupOnce({ token, baseUrl, advanced, handles }) {
18
+ handles.mastraExporter = new IntrospectionMastraExporter({
19
+ token,
20
+ baseUrl,
21
+ additionalHeaders: advanced?.additionalHeaders,
22
+ debug: advanced?.debug,
23
+ advanced: advanced?.spanExporter
24
+ ? { spanExporter: advanced.spanExporter }
25
+ : undefined,
26
+ });
27
+ },
28
+ };
29
+
30
+ export default integration;
@@ -0,0 +1,31 @@
1
+ /**
2
+ * OpenAI Agents SDK integration.
3
+ *
4
+ * Registers an {@link IntrospectionTracingProcessor} with the Agents SDK's
5
+ * global trace pipeline. `addTraceProcessor` appends, preserving any processors
6
+ * other integrations (e.g. a vendor exporter) already registered.
7
+ */
8
+
9
+ import { addTraceProcessor } from "@openai/agents";
10
+
11
+ import { IntrospectionTracingProcessor } from "../tracing-processor.js";
12
+ import type { Integration } from "./base.js";
13
+
14
+ const integration: Integration = {
15
+ identifier: "openai_agents",
16
+ setupOnce({ token, serviceName, baseUrl, advanced }) {
17
+ addTraceProcessor(
18
+ new IntrospectionTracingProcessor({
19
+ token,
20
+ serviceName,
21
+ baseUrl,
22
+ additionalHeaders: advanced?.additionalHeaders,
23
+ advanced: advanced?.spanExporter
24
+ ? { spanExporter: advanced.spanExporter }
25
+ : undefined,
26
+ }),
27
+ );
28
+ },
29
+ };
30
+
31
+ export default integration;
@@ -0,0 +1,24 @@
1
+ /**
2
+ * Pi Agent SDK integration.
3
+ *
4
+ * The Pi instrumentor wraps a specific `Agent` instance, so this integration
5
+ * builds the instrumentor — bound to the shared provider's global tracer — and
6
+ * publishes it via `introspection.instrumentPi(agent, meta)`.
7
+ */
8
+
9
+ // Presence gate.
10
+ import "@mariozechner/pi-agent-core";
11
+
12
+ import { IntrospectionPiInstrumentor } from "../pi.js";
13
+ import type { Integration } from "./base.js";
14
+
15
+ const integration: Integration = {
16
+ identifier: "pi",
17
+ setupOnce({ handles }) {
18
+ // The instrumentor emits onto the global tracer, which `init()` has just
19
+ // registered with the shared IntrospectionSpanProcessor.
20
+ handles.piInstrumentor = new IntrospectionPiInstrumentor();
21
+ },
22
+ };
23
+
24
+ export default integration;
@@ -0,0 +1,24 @@
1
+ /**
2
+ * Vercel AI SDK integration.
3
+ *
4
+ * The AI SDK emits `ai.*` / `gen_ai.*` attributes natively via OTel when
5
+ * `experimental_telemetry` is enabled. The shared provider already carries an
6
+ * {@link IntrospectionSpanProcessor}, which converts those `ai.*` attributes to
7
+ * canonical `gen_ai.*` semconv at span end — so there is nothing to patch here.
8
+ * This integration exists so auto-discovery reports the AI SDK as detected and
9
+ * (via its top-level import) is skipped when `ai` is not installed.
10
+ */
11
+
12
+ // Presence gate: a missing `ai` package makes this module's import reject.
13
+ import "ai";
14
+
15
+ import type { Integration } from "./base.js";
16
+
17
+ const integration: Integration = {
18
+ identifier: "vercel",
19
+ setupOnce() {
20
+ // No-op: the shared IntrospectionSpanProcessor converts AI SDK spans.
21
+ },
22
+ };
23
+
24
+ export default integration;
@@ -0,0 +1,50 @@
1
+ /**
2
+ * Zero-code preload entry point for Introspection tracing.
3
+ *
4
+ * Usage (ESM):
5
+ *
6
+ * ```bash
7
+ * node --import @introspection-sdk/introspection-node/otel/register app.js
8
+ * ```
9
+ *
10
+ * Runs `introspection.init()` from the environment **before** the app's module
11
+ * graph executes, so no `init()` call is needed in application source. Because
12
+ * the Anthropic / Gemini one-liner works by prototype-patching the SDK classes
13
+ * (see `AnthropicInstrumentor.instrumentClass`), every client constructed after
14
+ * this preload is traced with zero code changes.
15
+ *
16
+ * Configuration is read from the usual environment variables
17
+ * (`INTROSPECTION_TOKEN`, `INTROSPECTION_SERVICE_NAME`,
18
+ * `INTROSPECTION_BASE_OTEL_URL`). If no token is configured the preload logs a
19
+ * warning and does nothing, so it never crashes the host application.
20
+ *
21
+ * This is the counterpart to the private SDK's `register.ts`, adapted to the
22
+ * `src/otel` surface: it drives the existing `init()` rather than registering an
23
+ * import-in-the-middle loader hook (the prototype-patch path does not need one).
24
+ */
25
+ import { logger } from "../utils.js";
26
+ import { init } from "./init.js";
27
+
28
+ /**
29
+ * Run `init()` if a token is configured. Exported (and awaited at module load)
30
+ * so tests can invoke it deterministically; the module-level `await` below
31
+ * guarantees the preload finishes — including framework auto-discovery and the
32
+ * prototype patch — before Node evaluates the application entry point.
33
+ */
34
+ export async function registerFromEnv(): Promise<void> {
35
+ if (!process.env.INTROSPECTION_TOKEN) {
36
+ logger.warn(
37
+ "[introspection] register: INTROSPECTION_TOKEN not set; tracing not initialised.",
38
+ );
39
+ return;
40
+ }
41
+ try {
42
+ await init();
43
+ logger.debug("[introspection] register: tracing initialised from preload.");
44
+ } catch (err) {
45
+ // Never let a preload failure take down the host application.
46
+ logger.warn(`[introspection] register: init failed: ${String(err)}`);
47
+ }
48
+ }
49
+
50
+ await registerFromEnv();
package/src/otel/setup.ts CHANGED
@@ -61,6 +61,7 @@ import {
61
61
  W3CTraceContextPropagator,
62
62
  } from "@opentelemetry/core";
63
63
  import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
64
+ import type { SpanProcessor } from "@opentelemetry/sdk-trace-base";
64
65
 
65
66
  import { logger } from "../utils.js";
66
67
  import {
@@ -86,6 +87,26 @@ export interface SetupTracingOptions extends IntrospectionSpanProcessorOptions {
86
87
  * other libraries that relied on the previous registration.
87
88
  */
88
89
  onConflict?: ConflictBehavior;
90
+
91
+ /**
92
+ * Extra span processors attached to the same `NodeTracerProvider`, so a
93
+ * single set of spans fans out to other backends (Langfuse, Arize, …).
94
+ * This is the low-level dual-export hook:
95
+ *
96
+ * ```ts
97
+ * setupTracing({
98
+ * serviceName: "my-app",
99
+ * additionalSpanProcessors: [new BatchSpanProcessor(langfuseExporter)],
100
+ * });
101
+ * ```
102
+ *
103
+ * Note: the {@link IntrospectionSpanProcessor} forwards its *own* converted
104
+ * copy of each span to Introspection — it does not mutate the shared span —
105
+ * so these processors receive the raw span and run independently of it.
106
+ * Order is therefore irrelevant. `introspection.init({ spanProcessors })`
107
+ * is the equivalent for the one-liner surface.
108
+ */
109
+ additionalSpanProcessors?: SpanProcessor[];
89
110
  }
90
111
 
91
112
  function defaultConflictBehavior(): ConflictBehavior {
@@ -148,6 +169,20 @@ function registerPropagator(behavior: ConflictBehavior): void {
148
169
  logger.warn(msg);
149
170
  }
150
171
 
172
+ /**
173
+ * Install the OTel context manager + W3C (trace-context + baggage) propagator
174
+ * that Introspection's baggage scopes depend on.
175
+ *
176
+ * Shared by {@link setupTracing} and `introspection.init()`. `behavior`
177
+ * controls what happens when a manager / propagator is already registered
178
+ * (see {@link ConflictBehavior}).
179
+ */
180
+ export function registerOTelGlobals(behavior?: ConflictBehavior): void {
181
+ const resolved = behavior ?? defaultConflictBehavior();
182
+ registerContextManager(resolved);
183
+ registerPropagator(resolved);
184
+ }
185
+
151
186
  /**
152
187
  * Initialise Introspection tracing for a Node.js process.
153
188
  */
@@ -161,11 +196,17 @@ export function setupTracing(
161
196
  const behavior: ConflictBehavior =
162
197
  options?.onConflict ?? defaultConflictBehavior();
163
198
 
164
- registerContextManager(behavior);
165
- registerPropagator(behavior);
199
+ registerOTelGlobals(behavior);
166
200
 
167
201
  const provider = new NodeTracerProvider({
168
- spanProcessors: [new IntrospectionSpanProcessor(options)],
202
+ // Order is irrelevant: IntrospectionSpanProcessor exports its own converted
203
+ // copy and does not mutate the shared span, so co-located dual-export
204
+ // processors receive the raw span regardless of position. Listed first here
205
+ // (and in init()) purely for a consistent, readable ordering story.
206
+ spanProcessors: [
207
+ new IntrospectionSpanProcessor(options),
208
+ ...(options?.additionalSpanProcessors ?? []),
209
+ ],
169
210
  });
170
211
  provider.register();
171
212
 
package/src/utils.ts CHANGED
@@ -1,12 +1,19 @@
1
1
  import { DiagLogLevel, DiagLogger } from "@opentelemetry/api";
2
2
  import { HttpsProxyAgent } from "https-proxy-agent";
3
+ import { resolveForwardProxyUrl } from "@introspection-sdk/introspection-proxy";
3
4
 
4
- function getHttpsProxyUrl(): string | undefined {
5
- return process.env.HTTPS_PROXY || undefined;
6
- }
7
-
5
+ /**
6
+ * Attach a forward-proxy agent to OTLP exporter options when a proxy is
7
+ * configured in the environment.
8
+ *
9
+ * Note: the OTLP proto exporters use Node's `http`/`https` stack, so this uses
10
+ * `HttpsProxyAgent` (an `http.Agent`) rather than the undici dispatcher from
11
+ * `./proxy.js` — a dispatcher only applies to `fetch`. The proxy *URL* is
12
+ * resolved by the shared {@link resolveForwardProxyUrl} so fetch and OTLP
13
+ * traffic agree on which proxy to use.
14
+ */
8
15
  export function withOtlpHttpsProxy<T extends object>(options: T): T {
9
- const proxyUrl = getHttpsProxyUrl();
16
+ const proxyUrl = resolveForwardProxyUrl();
10
17
  if (!proxyUrl) return options;
11
18
 
12
19
  return {
@@ -1,4 +0,0 @@
1
-
2
- > @introspection-sdk/introspection-node@0.1.0 check-types /Users/julian/projects/introspection-org/introspection-js-sdk/packages/introspection-node
3
- > tsc --noEmit
4
-
@@ -1,5 +0,0 @@
1
-
2
- > @introspection-sdk/introspection-node@0.1.0 lint /Users/julian/projects/introspection-org/introspection-js-sdk/packages/introspection-node
3
- > eslint . --max-warnings 0
4
-
5
- Warning: React version was set to "detect" in eslint-plugin-react settings, but the "react" package is not installed. Assuming latest React version for linting.
@@ -1,123 +0,0 @@
1
- /**
2
- * AI SDK TelemetryIntegration for Introspection.
3
- *
4
- * Implements the Vercel AI SDK's TelemetryIntegration interface to capture
5
- * LLM interactions and export them as OpenTelemetry spans with gen_ai.*
6
- * semantic convention attributes to the Introspection backend.
7
- *
8
- * Similar to IntrospectionTracingProcessor for OpenAI Agents SDK and
9
- * IntrospectionClaudeHooks for Claude Agent SDK.
10
- *
11
- * @example
12
- * ```ts
13
- * import { IntrospectionAISDKIntegration } from "@introspection-sdk/introspection-node";
14
- * import { generateText } from "ai";
15
- * import { openai } from "@ai-sdk/openai";
16
- *
17
- * const introspection = new IntrospectionAISDKIntegration({
18
- * token: "sk-intro-...",
19
- * serviceName: "my-app",
20
- * });
21
- *
22
- * const { text } = await generateText({
23
- * model: openai("gpt-4o"),
24
- * prompt: "Hello!",
25
- * experimental_telemetry: {
26
- * isEnabled: true,
27
- * integrations: [introspection],
28
- * },
29
- * });
30
- *
31
- * await introspection.shutdown();
32
- * ```
33
- */
34
- import { type SpanExporter, type IdGenerator } from "@opentelemetry/sdk-trace-base";
35
- /** Advanced options for testing and customization. */
36
- export interface AISDKIntegrationAdvancedOptions {
37
- /** Custom span exporter (for testing — use InMemorySpanExporter). */
38
- spanExporter?: SpanExporter;
39
- /** Custom ID generator (for testing). */
40
- idGenerator?: IdGenerator;
41
- /** Use SimpleSpanProcessor instead of BatchSpanProcessor (for testing). */
42
- useSimpleSpanProcessor?: boolean;
43
- /** Maximum batch size for span export. */
44
- maxExportBatchSize?: number;
45
- /** Delay between batch exports in milliseconds. */
46
- scheduledDelayMillis?: number;
47
- }
48
- /** Configuration for {@link IntrospectionAISDKIntegration}. */
49
- export interface IntrospectionAISDKIntegrationOptions {
50
- /** Authentication token (env: INTROSPECTION_TOKEN). */
51
- token?: string;
52
- /** Base URL for the API (env: INTROSPECTION_BASE_URL, default: "https://otel.introspection.dev"). */
53
- baseUrl?: string;
54
- /** Service name for telemetry (env: INTROSPECTION_SERVICE_NAME). */
55
- serviceName?: string;
56
- /** Additional headers to include in requests. */
57
- additionalHeaders?: Record<string, string>;
58
- /** Advanced options for testing and customization. */
59
- advanced?: AISDKIntegrationAdvancedOptions;
60
- }
61
- /**
62
- * AI SDK {@link TelemetryIntegration} that captures LLM interactions and
63
- * exports them as OpenTelemetry spans with `gen_ai.*` semantic convention
64
- * attributes to the Introspection backend.
65
- *
66
- * Creates its own {@link BasicTracerProvider} — no external OTel setup required.
67
- * Each generation (generateText/streamText call) produces:
68
- * - A root span grouping the entire operation
69
- * - Step spans (one per LLM call) with full gen_ai attributes
70
- * - Tool call spans nested under their parent step
71
- */
72
- export declare class IntrospectionAISDKIntegration {
73
- private _tracerProvider;
74
- private _tracer;
75
- private _generation;
76
- constructor(options?: IntrospectionAISDKIntegrationOptions);
77
- /**
78
- * Called when a generation operation begins (before any LLM calls).
79
- * Creates a root span to group all steps in this generation.
80
- */
81
- onStart: (event: unknown) => void;
82
- /**
83
- * Called when a step (individual LLM call) begins.
84
- * Creates a child span under the root span and captures input messages.
85
- */
86
- onStepStart: (event: unknown) => void;
87
- /**
88
- * Called when a tool execution begins.
89
- * Creates a child span under the current step span.
90
- */
91
- onToolCallStart: (event: unknown) => void;
92
- /**
93
- * Called when a tool execution completes.
94
- * Sets output/error attributes and ends the tool span.
95
- */
96
- onToolCallFinish: (event: unknown) => void;
97
- /**
98
- * Called when a step (LLM call) completes.
99
- * Sets gen_ai attributes (input/output messages, usage, model) and ends
100
- * the step span.
101
- */
102
- onStepFinish: (event: unknown) => void;
103
- /**
104
- * Called when the entire generation completes (all steps finished).
105
- * Sets total usage on the root span and ends it.
106
- */
107
- onFinish: (event: unknown) => void;
108
- /**
109
- * Shut down the tracer provider, flushing all pending spans.
110
- *
111
- * @returns A promise that resolves once shutdown is complete.
112
- */
113
- shutdown(): Promise<void>;
114
- /**
115
- * Force-flush any buffered spans to the Introspection backend.
116
- *
117
- * @returns A promise that resolves once the flush completes.
118
- */
119
- forceFlush(): Promise<void>;
120
- /** Cleanly end any active generation, closing all open spans. */
121
- private _endGeneration;
122
- }
123
- //# sourceMappingURL=ai-sdk-integration.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"ai-sdk-integration.d.ts","sourceRoot":"","sources":["../src/ai-sdk-integration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAOH,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,WAAW,EACjB,MAAM,+BAA+B,CAAC;AAoBvC,sDAAsD;AACtD,MAAM,WAAW,+BAA+B;IAC9C,qEAAqE;IACrE,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,yCAAyC;IACzC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,2EAA2E;IAC3E,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,0CAA0C;IAC1C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,mDAAmD;IACnD,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,+DAA+D;AAC/D,MAAM,WAAW,oCAAoC;IACnD,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qGAAqG;IACrG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,sDAAsD;IACtD,QAAQ,CAAC,EAAE,+BAA+B,CAAC;CAC5C;AAoBD;;;;;;;;;;GAUG;AACH,qBAAa,6BAA6B;IACxC,OAAO,CAAC,eAAe,CAAsB;IAC7C,OAAO,CAAC,OAAO,CAA+C;IAC9D,OAAO,CAAC,WAAW,CAAgC;gBAEvC,OAAO,GAAE,oCAAyC;IA8F9D;;;OAGG;IACH,OAAO,GAAI,OAAO,OAAO,KAAG,IAAI,CA2D9B;IAEF;;;OAGG;IACH,WAAW,GAAI,OAAO,OAAO,KAAG,IAAI,CAgFlC;IAEF;;;OAGG;IACH,eAAe,GAAI,OAAO,OAAO,KAAG,IAAI,CA0CtC;IAEF;;;OAGG;IACH,gBAAgB,GAAI,OAAO,OAAO,KAAG,IAAI,CAgDvC;IAEF;;;;OAIG;IACH,YAAY,GAAI,OAAO,OAAO,KAAG,IAAI,CAuHnC;IAEF;;;OAGG;IACH,QAAQ,GAAI,OAAO,OAAO,KAAG,IAAI,CA+C/B;IAMF;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAK/B;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQjC,iEAAiE;IACjE,OAAO,CAAC,cAAc;CASvB"}