@introspection-sdk/introspection-node 0.4.3 → 0.4.4
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.
- package/.turbo/turbo-build.log +1 -1
- package/dist/otel/anthropic.d.ts +14 -12
- package/dist/otel/anthropic.d.ts.map +1 -1
- package/dist/otel/anthropic.js +89 -47
- package/dist/otel/anthropic.js.map +1 -1
- package/dist/otel/gemini.d.ts +15 -7
- package/dist/otel/gemini.d.ts.map +1 -1
- package/dist/otel/gemini.js +88 -37
- package/dist/otel/gemini.js.map +1 -1
- package/dist/otel/index.d.ts +5 -0
- package/dist/otel/index.d.ts.map +1 -1
- package/dist/otel/index.js +8 -0
- package/dist/otel/index.js.map +1 -1
- package/dist/otel/init.d.ts +126 -0
- package/dist/otel/init.d.ts.map +1 -0
- package/dist/otel/init.js +259 -0
- package/dist/otel/init.js.map +1 -0
- package/dist/otel/integrations/anthropic.d.ts +10 -0
- package/dist/otel/integrations/anthropic.d.ts.map +1 -0
- package/dist/otel/integrations/anthropic.js +22 -0
- package/dist/otel/integrations/anthropic.js.map +1 -0
- package/dist/otel/integrations/base.d.ts +83 -0
- package/dist/otel/integrations/base.d.ts.map +1 -0
- package/dist/otel/integrations/base.js +23 -0
- package/dist/otel/integrations/base.js.map +1 -0
- package/dist/otel/integrations/claude-agent.d.ts +13 -0
- package/dist/otel/integrations/claude-agent.d.ts.map +1 -0
- package/dist/otel/integrations/claude-agent.js +27 -0
- package/dist/otel/integrations/claude-agent.js.map +1 -0
- package/dist/otel/integrations/gemini.d.ts +11 -0
- package/dist/otel/integrations/gemini.d.ts.map +1 -0
- package/dist/otel/integrations/gemini.js +21 -0
- package/dist/otel/integrations/gemini.js.map +1 -0
- package/dist/otel/integrations/index.d.ts +39 -0
- package/dist/otel/integrations/index.d.ts.map +1 -0
- package/dist/otel/integrations/index.js +131 -0
- package/dist/otel/integrations/index.js.map +1 -0
- package/dist/otel/integrations/langchain.d.ts +16 -0
- package/dist/otel/integrations/langchain.d.ts.map +1 -0
- package/dist/otel/integrations/langchain.js +41 -0
- package/dist/otel/integrations/langchain.js.map +1 -0
- package/dist/otel/integrations/mastra.d.ts +14 -0
- package/dist/otel/integrations/mastra.d.ts.map +1 -0
- package/dist/otel/integrations/mastra.js +27 -0
- package/dist/otel/integrations/mastra.js.map +1 -0
- package/dist/otel/integrations/openai-agents.d.ts +11 -0
- package/dist/otel/integrations/openai-agents.d.ts.map +1 -0
- package/dist/otel/integrations/openai-agents.js +25 -0
- package/dist/otel/integrations/openai-agents.js.map +1 -0
- package/dist/otel/integrations/pi.d.ts +12 -0
- package/dist/otel/integrations/pi.d.ts.map +1 -0
- package/dist/otel/integrations/pi.js +20 -0
- package/dist/otel/integrations/pi.js.map +1 -0
- package/dist/otel/integrations/vercel.d.ts +15 -0
- package/dist/otel/integrations/vercel.d.ts.map +1 -0
- package/dist/otel/integrations/vercel.js +20 -0
- package/dist/otel/integrations/vercel.js.map +1 -0
- package/dist/otel/register.d.ts +8 -0
- package/dist/otel/register.d.ts.map +1 -0
- package/dist/otel/register.js +48 -0
- package/dist/otel/register.js.map +1 -0
- package/dist/otel/setup.d.ts +29 -0
- package/dist/otel/setup.d.ts.map +1 -1
- package/dist/otel/setup.js +22 -3
- package/dist/otel/setup.js.map +1 -1
- package/dist/utils.d.ts +10 -0
- package/dist/utils.d.ts.map +1 -1
- package/dist/utils.js +12 -4
- package/dist/utils.js.map +1 -1
- package/package.json +17 -5
- package/src/otel/anthropic.ts +128 -63
- package/src/otel/gemini.ts +139 -45
- package/src/otel/index.ts +41 -0
- package/src/otel/init.ts +411 -0
- package/src/otel/integrations/anthropic.ts +26 -0
- package/src/otel/integrations/base.ts +95 -0
- package/src/otel/integrations/claude-agent.ts +32 -0
- package/src/otel/integrations/gemini.ts +25 -0
- package/src/otel/integrations/index.ts +151 -0
- package/src/otel/integrations/langchain.ts +45 -0
- package/src/otel/integrations/mastra.ts +30 -0
- package/src/otel/integrations/openai-agents.ts +31 -0
- package/src/otel/integrations/pi.ts +24 -0
- package/src/otel/integrations/vercel.ts +24 -0
- package/src/otel/register.ts +50 -0
- package/src/otel/setup.ts +44 -3
- package/src/utils.ts +12 -5
- package/.turbo/turbo-check-types.log +0 -4
- package/.turbo/turbo-lint.log +0 -5
- package/dist/ai-sdk-integration.d.ts +0 -123
- package/dist/ai-sdk-integration.d.ts.map +0 -1
- package/dist/ai-sdk-integration.js +0 -475
- package/dist/anthropic.d.ts +0 -54
- package/dist/anthropic.d.ts.map +0 -1
- package/dist/anthropic.js +0 -375
- package/dist/claude-hooks.d.ts +0 -328
- package/dist/claude-hooks.d.ts.map +0 -1
- package/dist/claude-hooks.js +0 -571
- package/dist/claude-wrapper.d.ts +0 -93
- package/dist/claude-wrapper.d.ts.map +0 -1
- package/dist/claude-wrapper.js +0 -154
- package/dist/converters/ai-sdk.d.ts +0 -65
- package/dist/converters/ai-sdk.d.ts.map +0 -1
- package/dist/converters/ai-sdk.js +0 -261
- package/dist/converters/openclaw.d.ts +0 -16
- package/dist/converters/openclaw.d.ts.map +0 -1
- package/dist/converters/openclaw.js +0 -49
- package/dist/langchain-handler.d.ts +0 -103
- package/dist/langchain-handler.d.ts.map +0 -1
- package/dist/langchain-handler.js +0 -518
- package/dist/mastra-exporter.d.ts +0 -85
- package/dist/mastra-exporter.d.ts.map +0 -1
- package/dist/mastra-exporter.js +0 -471
- package/dist/span-processor.d.ts +0 -62
- package/dist/span-processor.d.ts.map +0 -1
- package/dist/span-processor.js +0 -313
- package/dist/tracing-processor.d.ts +0 -136
- package/dist/tracing-processor.d.ts.map +0 -1
- package/dist/tracing-processor.js +0 -368
- package/dist/types/genai.d.ts +0 -165
- package/dist/types/genai.d.ts.map +0 -1
- 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
|
-
|
|
165
|
-
registerPropagator(behavior);
|
|
199
|
+
registerOTelGlobals(behavior);
|
|
166
200
|
|
|
167
201
|
const provider = new NodeTracerProvider({
|
|
168
|
-
|
|
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
|
-
|
|
5
|
-
|
|
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 =
|
|
16
|
+
const proxyUrl = resolveForwardProxyUrl();
|
|
10
17
|
if (!proxyUrl) return options;
|
|
11
18
|
|
|
12
19
|
return {
|
package/.turbo/turbo-lint.log
DELETED
|
@@ -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"}
|