@introspection-sdk/introspection-node 0.4.0

package/dist/span-processor.js

@@ -0,0 +1,310 @@
+import { propagation, context as otelContext, } from "@opentelemetry/api";
+import { BatchSpanProcessor, } from "@opentelemetry/sdk-trace-base";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
+import { ExportResultCode } from "@opentelemetry/core";
+import { randomUUID } from "crypto";
+import { logger } from "./utils.js";
+import { isOpenInferenceSpan, replaceOpenInferenceWithGenAI, isVercelAISpan, convertVercelAIToGenAI, } from "./converters/index.js";
+/**
+ * A {@link ReadableSpan} wrapper that substitutes the original attributes with
+ * a converted set while delegating every other property to the original span.
+ *
+ * Used internally by {@link IntrospectionSpanProcessor} to convert
+ * OpenInference attributes to Gen AI semantic conventions on-the-fly.
+ */
+class ConvertedReadableSpan {
+    _original;
+    _convertedAttributes;
+    _resource;
+    constructor(original, convertedAttributes, resource) {
+        this._original = original;
+        this._convertedAttributes = convertedAttributes;
+        this._resource = resource;
+    }
+    get name() {
+        return this._original.name;
+    }
+    get kind() {
+        return this._original.kind;
+    }
+    spanContext() {
+        return this._original.spanContext();
+    }
+    get startTime() {
+        return this._original.startTime;
+    }
+    get endTime() {
+        return this._original.endTime;
+    }
+    get status() {
+        return this._original.status;
+    }
+    get links() {
+        return this._original.links;
+    }
+    get events() {
+        return this._original.events;
+    }
+    get duration() {
+        return this._original.duration;
+    }
+    get ended() {
+        return this._original.ended;
+    }
+    get resource() {
+        return this._resource ?? this._original.resource;
+    }
+    get instrumentationScope() {
+        return this._original.instrumentationScope;
+    }
+    get droppedAttributesCount() {
+        return this._original.droppedAttributesCount;
+    }
+    get droppedEventsCount() {
+        return this._original.droppedEventsCount;
+    }
+    get droppedLinksCount() {
+        return this._original.droppedLinksCount;
+    }
+    get attributes() {
+        return this._convertedAttributes;
+    }
+}
+/**
+ * OTel {@link SpanProcessor} that forwards traces to the Introspection backend
+ * via OTLP, automatically converting any OpenInference spans to Gen AI
+ * semantic convention attributes.
+ *
+ * @example
+ * ```ts
+ * import { IntrospectionSpanProcessor } from "@introspection-sdk/introspection-node";
+ *
+ * const processor = new IntrospectionSpanProcessor({ token: "sk-intro-…" });
+ * tracerProvider.addSpanProcessor(processor);
+ * ```
+ */
+export class IntrospectionSpanProcessor {
+    _spanProcessor;
+    _serviceName;
+    _conversationIds = new Map();
+    constructor(options = {}) {
+        const token = options.token || process.env.INTROSPECTION_TOKEN;
+        if (!token) {
+            throw new Error("INTROSPECTION_TOKEN is required");
+        }
+        const serviceName = options.serviceName ||
+            process.env.INTROSPECTION_SERVICE_NAME ||
+            undefined; // Falls back to TracerProvider's resource
+        this._serviceName = serviceName;
+        const advanced = options.advanced || {};
+        const baseUrl = advanced.baseUrl ||
+            process.env.INTROSPECTION_BASE_URL ||
+            "https://otel.introspection.dev";
+        const headers = {
+            Authorization: `Bearer ${token}`,
+            ...(advanced.additionalHeaders || {}),
+        };
+        // Construct endpoint URL
+        let endpoint;
+        if (baseUrl.endsWith("/v1/traces")) {
+            endpoint = baseUrl;
+        }
+        else {
+            endpoint = `${baseUrl.replace(/\/$/, "")}/v1/traces`;
+        }
+        logger.info(`IntrospectionSpanProcessor initialized: endpoint=${endpoint}${serviceName ? `, serviceName=${serviceName}` : ""}`);
+        // Use custom spanExporter if provided (for testing), otherwise create OTLP exporter
+        const baseExporter = advanced.spanExporter ||
+            new OTLPTraceExporter({
+                url: endpoint,
+                headers,
+            });
+        // Wrap exporter to add v1/v2 compatibility and basic validation
+        const exporter = {
+            export: (spans, resultCallback) => {
+                // Filter and fix spans: ensure they have required properties and add v1 compatibility
+                const validSpans = spans
+                    .filter((span) => {
+                    // Basic validation: span must have name and resource
+                    if (!span?.name || !span.resource) {
+                        return false;
+                    }
+                    // Must have either instrumentationLibrary or instrumentationScope
+                    const compatSpan = span;
+                    return !!(compatSpan.instrumentationLibrary ||
+                        compatSpan.instrumentationScope);
+                })
+                    .map((span) => span)
+                    .map((span) => {
+                    // Compatibility: add instrumentationLibrary for spans that only have instrumentationScope (v2)
+                    const compatSpan = span;
+                    if (compatSpan.instrumentationScope &&
+                        !compatSpan.instrumentationLibrary) {
+                        compatSpan.instrumentationLibrary =
+                            compatSpan.instrumentationScope;
+                    }
+                    return span;
+                });
+                if (validSpans.length === 0) {
+                    resultCallback({ code: ExportResultCode.SUCCESS });
+                    return;
+                }
+                // Export with error handling
+                try {
+                    baseExporter.export(validSpans, (result) => {
+                        if (result.code === ExportResultCode.SUCCESS) {
+                            logger.debug(`Exported ${validSpans.length} span(s) to ${endpoint}`);
+                        }
+                        else {
+                            logger.error(`Failed to export ${validSpans.length} span(s): ${result.error?.message || "Unknown error"}`);
+                        }
+                        resultCallback(result);
+                    });
+                }
+                catch (error) {
+                    logger.error(`Export error: ${error instanceof Error ? error.message : String(error)}`);
+                    resultCallback({
+                        code: ExportResultCode.FAILED,
+                        error: error instanceof Error ? error : new Error(String(error)),
+                    });
+                }
+            },
+            shutdown: () => baseExporter.shutdown(),
+            forceFlush: () => {
+                if (baseExporter.forceFlush) {
+                    return baseExporter.forceFlush();
+                }
+                return Promise.resolve();
+            },
+        };
+        // Use BatchSpanProcessor like logfire does
+        this._spanProcessor = new BatchSpanProcessor(exporter);
+    }
+    /**
+     * Called when a new span is started; delegates to the inner batch processor.
+     *
+     * @param span - The span that was just started.
+     * @param parentContext - The parent {@link Context}.
+     */
+    onStart(span, parentContext) {
+        this._spanProcessor.onStart(span, parentContext);
+    }
+    /**
+     * Called when a span ends. If the span originates from an OpenInference
+     * instrumentor, its attributes are converted to `gen_ai.*` semconv keys
+     * before being forwarded.
+     *
+     * @param span - The completed {@link ReadableSpan}.
+     */
+    onEnd(span) {
+        const compatSpan = span;
+        const scopeName = compatSpan.instrumentationScope?.name ||
+            compatSpan.instrumentationLibrary?.name;
+        const isOI = isOpenInferenceSpan(scopeName) ||
+            typeof span.attributes["openinference.span.kind"] === "string";
+        const isVercel = isVercelAISpan(span.attributes);
+        // Skip Vercel AI SDK wrapper spans (ai.streamText, ai.generateText).
+        // They duplicate the child doStream/doGenerate output without proper
+        // input message windows, causing empty user messages in conversation view.
+        // This applies regardless of whether OI attributes are also present.
+        const aiOperationId = span.attributes["ai.operationId"];
+        if (typeof aiOperationId === "string" &&
+            !String(aiOperationId).includes(".do")) {
+            return;
+        }
+        // Skip spans that have no LLM-relevant data — they are infrastructure spans
+        // (e.g. Next.js route resolution, HTTP spans) that should not be exported.
+        const hasGenAi = isOI ||
+            isVercel ||
+            span.attributes["gen_ai.system"] != null ||
+            span.attributes["gen_ai.operation.name"] != null ||
+            span.attributes["gen_ai.request.model"] != null ||
+            span.attributes["gen_ai.input.messages"] != null ||
+            span.attributes["gen_ai.output.messages"] != null;
+        if (!hasGenAi)
+            return;
+        let attrs;
+        if (isOI) {
+            attrs = {
+                ...replaceOpenInferenceWithGenAI(span.attributes),
+            };
+            // When both OI and Vercel attrs present, merge Vercel-specific
+            // enrichments (conversation ID from metadata, etc.)
+            if (isVercel) {
+                const vercelAttrs = convertVercelAIToGenAI(span.attributes);
+                for (const [key, value] of Object.entries(vercelAttrs)) {
+                    // Prefer Vercel output messages when they contain reasoning
+                    if (key === "gen_ai.output.messages" &&
+                        typeof value === "string" &&
+                        value.includes('"thinking"')) {
+                        attrs[key] = value;
+                    }
+                    else if (attrs[key] === undefined) {
+                        attrs[key] = value;
+                    }
+                }
+            }
+            logger.debug(`Converting OpenInference span: ${span.name}`);
+        }
+        else if (isVercel) {
+            attrs = {
+                ...span.attributes,
+                ...convertVercelAIToGenAI(span.attributes),
+            };
+            logger.debug(`Converting Vercel AI span: ${span.name}`);
+        }
+        else {
+            attrs = { ...span.attributes };
+        }
+        // Read baggage from active context
+        const baggage = propagation.getBaggage(otelContext.active());
+        // Conversation ID: baggage > existing attr > auto-generate per trace
+        const baggageConvId = baggage?.getEntry("gen_ai.conversation.id")?.value;
+        const existingConvId = attrs["gen_ai.conversation.id"];
+        if (baggageConvId) {
+            attrs["gen_ai.conversation.id"] = baggageConvId;
+        }
+        else if (!existingConvId) {
+            const traceId = span.spanContext().traceId;
+            if (!this._conversationIds.has(traceId)) {
+                this._conversationIds.set(traceId, `intro_conv_${randomUUID().replace(/-/g, "")}`);
+            }
+            attrs["gen_ai.conversation.id"] = this._conversationIds.get(traceId);
+        }
+        // Default gen_ai.operation.name to "chat" for spans with messages but no operation name
+        if (!attrs["gen_ai.operation.name"] &&
+            (attrs["gen_ai.input.messages"] || attrs["gen_ai.output.messages"])) {
+            attrs["gen_ai.operation.name"] = "chat";
+        }
+        // Agent name from baggage
+        const baggageAgentName = baggage?.getEntry("gen_ai.agent.name")?.value;
+        if (baggageAgentName && !attrs["gen_ai.agent.name"]) {
+            attrs["gen_ai.agent.name"] = baggageAgentName;
+        }
+        // Override resource with service name if provided
+        let resource;
+        if (this._serviceName) {
+            resource = span.resource.merge(resourceFromAttributes({ [ATTR_SERVICE_NAME]: this._serviceName }));
+        }
+        const processedSpan = new ConvertedReadableSpan(span, attrs, resource);
+        this._spanProcessor.onEnd(processedSpan);
+    }
+    /**
+     * Shut down the inner batch processor and its exporter.
+     *
+     * @returns A promise that resolves once all pending spans are flushed.
+     */
+    async shutdown() {
+        await this._spanProcessor.shutdown();
+    }
+    /**
+     * Force-flush any buffered spans to the Introspection backend.
+     *
+     * @returns A promise that resolves once the flush completes.
+     */
+    async forceFlush() {
+        await this._spanProcessor.forceFlush();
+    }
+}

package/dist/tracing-processor.d.ts

@@ -0,0 +1,136 @@
+/**
+ * OpenAI Agents TracingProcessor for Introspection SDK.
+ *
+ * Forwards OpenAI agent traces to the backend via OTLP with OTel Gen AI semantic
+ * convention attributes.
+ */
+import { type SpanExporter, type IdGenerator } from "@opentelemetry/sdk-trace-base";
+import type { TracingProcessor, Trace, Span, SpanData } from "@openai/agents";
+/**
+ * Advanced options for testing and customization of
+ * {@link IntrospectionTracingProcessor}.
+ */
+export interface TracingProcessorAdvancedOptions {
+    /** Custom span exporter (for testing - use InMemorySpanExporter) */
+    spanExporter?: SpanExporter;
+    /** Custom ID generator (for testing - use IncrementalIdGenerator) */
+    idGenerator?: IdGenerator;
+    /** Use SimpleSpanProcessor instead of BatchSpanProcessor (for testing) */
+    useSimpleSpanProcessor?: boolean;
+    /**
+     * Maximum number of spans to export in a single batch.
+     * Set to 1 to export each span individually on end, ensuring sequential
+     * processing by the backend (useful for multi-turn conversations where
+     * each turn must be ingested before the next arrives).
+     * Defaults to the OTel SDK default (512).
+     */
+    maxExportBatchSize?: number;
+    /**
+     * Delay interval in milliseconds between batch exports.
+     * Lower values reduce latency but increase network requests.
+     * Defaults to 1000.
+     */
+    scheduledDelayMillis?: number;
+}
+/** Configuration for {@link IntrospectionTracingProcessor}. */
+export interface IntrospectionTracingProcessorOptions {
+    /** Authentication token (env: INTROSPECTION_TOKEN) */
+    token?: string;
+    /** Base URL for the API (env: INTROSPECTION_BASE_URL, default: "https://otel.introspection.dev") */
+    baseUrl?: string;
+    /** Service name for telemetry (env: INTROSPECTION_SERVICE_NAME) */
+    serviceName?: string;
+    /** Additional headers to include in requests */
+    additionalHeaders?: Record<string, string>;
+    /** Advanced options for testing and customization */
+    advanced?: TracingProcessorAdvancedOptions;
+}
+/**
+ * {@link TracingProcessor} that forwards OpenAI agent traces to the
+ * Introspection backend via OTLP.
+ *
+ * Extracts OTel Gen AI semantic convention attributes from span data:
+ * - Agent spans: `gen_ai.agent.name`, `gen_ai.tool.definitions`, `gen_ai.agent.handoffs`
+ * - Function spans: `gen_ai.tool.name`, `gen_ai.tool.input`, `gen_ai.tool.output`
+ * - Response spans: `gen_ai.input/output.messages`, `gen_ai.usage.*`, `gen_ai.request.model`
+ * - Generation spans: `gen_ai.request.model`, `gen_ai.usage.*`
+ * - Handoff spans: `gen_ai.handoff.from_agent`, `gen_ai.handoff.to_agent`
+ *
+ * @example
+ * ```ts
+ * import { IntrospectionTracingProcessor } from "@introspection-sdk/introspection-node";
+ *
+ * const processor = new IntrospectionTracingProcessor({ token: "sk-intro-…" });
+ * // pass processor to the OpenAI Agents SDK withTrace() or registerProcessor()
+ * ```
+ */
+export declare class IntrospectionTracingProcessor implements TracingProcessor {
+    private _tracerProvider;
+    private _tracer;
+    private _spans;
+    private _conversationIds;
+    constructor(options?: IntrospectionTracingProcessorOptions);
+    /**
+     * Called when the processor is started. Optional lifecycle hook.
+     */
+    start(): void;
+    /**
+     * Called when a trace starts. Creates a root OTel span.
+     *
+     * @param trace - The OpenAI Agents SDK trace object.
+     */
+    onTraceStart(trace: Trace): Promise<void>;
+    /**
+     * Called when a trace ends. Closes the root OTel span.
+     *
+     * @param trace - The OpenAI Agents SDK trace object.
+     */
+    onTraceEnd(trace: Trace): Promise<void>;
+    /**
+     * Called when a span starts. Creates a child OTel span with parent context.
+     *
+     * @param span - The OpenAI Agents SDK span.
+     */
+    onSpanStart(span: Span<SpanData>): Promise<void>;
+    /**
+     * Called when a span ends. Extracts `gen_ai.*` attributes from the span
+     * data and sets them on the corresponding OTel span before ending it.
+     *
+     * @param span - The OpenAI Agents SDK span.
+     */
+    onSpanEnd(span: Span<SpanData>): Promise<void>;
+    /**
+     * Extract attributes from agent spans.
+     */
+    private _processAgentSpan;
+    /**
+     * Extract attributes from function/tool spans.
+     */
+    private _processFunctionSpan;
+    /**
+     * Extract attributes from response spans.
+     * Matches Python implementation - extracts from both spanData and _response object.
+     */
+    private _processResponseSpan;
+    /**
+     * Extract attributes from generation spans.
+     */
+    private _processGenerationSpan;
+    /**
+     * Extract attributes from handoff spans.
+     */
+    private _processHandoffSpan;
+    /**
+     * Shut down the tracer provider, flushing all pending spans.
+     *
+     * @returns A promise that resolves once shutdown is complete.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Force-flush any buffered spans to the Introspection backend.
+     *
+     * @returns A promise that resolves once the flush completes.
+     */
+    forceFlush(): Promise<void>;
+}
+//# sourceMappingURL=tracing-processor.d.ts.map

package/dist/tracing-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing-processor.d.ts","sourceRoot":"","sources":["../src/tracing-processor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,WAAW,EACjB,MAAM,+BAA+B,CAAC;AAoBvC,OAAO,KAAK,EACV,gBAAgB,EAChB,KAAK,EACL,IAAI,EACJ,QAAQ,EAMT,MAAM,gBAAgB,CAAC;AAExB;;;GAGG;AACH,MAAM,WAAW,+BAA+B;IAC9C,oEAAoE;IACpE,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,qEAAqE;IACrE,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,0EAA0E;IAC1E,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,+DAA+D;AAC/D,MAAM,WAAW,oCAAoC;IACnD,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oGAAoG;IACpG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,qDAAqD;IACrD,QAAQ,CAAC,EAAE,+BAA+B,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,6BAA8B,YAAW,gBAAgB;IACpE,OAAO,CAAC,eAAe,CAAsB;IAC7C,OAAO,CAAC,OAAO,CAA+C;IAC9D,OAAO,CAAC,MAAM,CAAoC;IAClD,OAAO,CAAC,gBAAgB,CAAkC;gBAE9C,OAAO,GAAE,oCAAyC;IAyF9D;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;;;OAIG;IACG,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAW/C;;;;OAIG;IACG,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAa7C;;;;OAIG;IACG,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BtD;;;;;OAKG;IACG,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA6CpD;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA0BzB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAgB5B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IA0F5B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAwC9B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAY3B;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAGlC"}