@mtharrison/loupe 1.2.0 → 1.4.0

package/dist/store.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TraceStore = void 0;
+const node_crypto_1 = require("node:crypto");
 const node_events_1 = require("node:events");
 const utils_1 = require("./utils");
+const STREAM_EVENT_NAME_PREFIX = 'stream.';
 class TraceStore extends node_events_1.EventEmitter {
     maxTraces;
     order;
@@ -13,72 +15,100 @@ class TraceStore extends node_events_1.EventEmitter {
         this.order = [];
         this.traces = new Map();
     }
-    recordInvokeStart(context, request) {
-        return this.recordStart('invoke', context, request);
+    startSpan(context, options = {}) {
+        return this.recordStart(options.mode || 'invoke', context, options.request || {}, options);
     }
-    recordInvokeFinish(traceId, response) {
-        const trace = this.traces.get(traceId);
+    addSpanEvent(spanId, event) {
+        // Loupe returns its own stable span handle from startSpan(). That handle is used to
+        // look up mutable in-memory records here, while trace.spanContext.spanId stores the
+        // OpenTelemetry span ID exposed on the resulting span data.
+        const trace = this.traces.get(spanId);
+        if (!trace) {
+            return;
+        }
+        const spanEvent = normalizeSpanEvent(event);
+        trace.events.push(spanEvent);
+        this.applyStreamPayload(trace, event.payload, spanEvent);
+        this.publish('span:update', spanId, { trace: this.cloneTrace(trace) });
+    }
+    endSpan(spanId, response) {
+        const trace = this.traces.get(spanId);
         if (!trace) {
             return;
         }
-        trace.response = (0, utils_1.safeClone)(response);
-        trace.usage = (0, utils_1.safeClone)(response?.usage);
+        const clone = (0, utils_1.safeClone)(response);
+        if (trace.mode === 'stream') {
+            const finishEvent = normalizeSpanEvent((0, utils_1.toSpanEventInputFromChunk)(clone));
+            trace.events.push(finishEvent);
+            this.applyStreamPayload(trace, clone, finishEvent);
+            trace.response = clone;
+            trace.usage = (0, utils_1.safeClone)(clone?.usage);
+        }
+        else {
+            trace.response = clone;
+            trace.usage = (0, utils_1.safeClone)(clone?.usage);
+        }
+        applyResponseAttributes(trace, clone);
         trace.status = 'ok';
+        trace.spanStatus = { code: 'OK' };
         trace.endedAt = new Date().toISOString();
-        this.publish('trace:update', traceId, { trace: this.cloneTrace(trace) });
+        this.publish('span:end', spanId, { trace: this.cloneTrace(trace) });
     }
-    recordStreamStart(context, request) {
-        return this.recordStart('stream', context, request);
+    recordException(spanId, error) {
+        const trace = this.traces.get(spanId);
+        if (!trace) {
+            return;
+        }
+        const payload = (0, utils_1.toErrorPayload)(error);
+        trace.error = payload;
+        trace.events.push({
+            attributes: payload || {},
+            name: 'exception',
+            timestamp: new Date().toISOString(),
+        });
+        trace.status = 'error';
+        trace.spanStatus = {
+            code: 'ERROR',
+            message: payload?.message,
+        };
+        if (payload?.name || payload?.type || payload?.code || payload?.status) {
+            trace.attributes['error.type'] = String(payload.name || payload.type || payload.code || payload.status);
+        }
+        trace.endedAt = new Date().toISOString();
+        this.publish('span:end', spanId, { trace: this.cloneTrace(trace) });
     }
-    recordStreamChunk(traceId, chunk) {
-        const trace = this.traces.get(traceId);
-        if (!trace || !trace.stream) {
+    applyStreamPayload(trace, payload, spanEvent) {
+        if (!trace.stream) {
             return;
         }
-        const clone = (0, utils_1.safeClone)(chunk);
+        const clone = toStreamPayload(payload, spanEvent);
         if (clone && typeof clone === 'object') {
             clone.offsetMs = Math.max(0, Date.now() - Date.parse(trace.startedAt));
         }
         trace.stream.events.push(clone);
-        if (chunk?.type === 'chunk') {
+        if (clone?.type === 'chunk') {
             trace.stream.chunkCount += 1;
             if (trace.stream.firstChunkMs === null) {
                 trace.stream.firstChunkMs = Date.now() - Date.parse(trace.startedAt);
             }
-            if (typeof chunk.content === 'string') {
-                trace.stream.reconstructed.message.content = `${trace.stream.reconstructed.message.content || ''}${chunk.content}`;
+            if (typeof clone.content === 'string') {
+                trace.stream.reconstructed.message.content = `${trace.stream.reconstructed.message.content || ''}${clone.content}`;
             }
         }
-        if (chunk?.type === 'begin') {
-            trace.stream.reconstructed.message.role = chunk.role;
+        if (clone?.type === 'begin') {
+            trace.stream.reconstructed.message.role = clone.role;
         }
-        if (chunk?.type === 'finish') {
+        if (clone?.type === 'finish') {
             trace.response = clone;
-            trace.usage = (0, utils_1.safeClone)(chunk.usage);
+            trace.usage = (0, utils_1.safeClone)(clone.usage);
             trace.stream.reconstructed.message = {
-                ...((0, utils_1.safeClone)(chunk.message) || {}),
+                ...((0, utils_1.safeClone)(clone.message) || {}),
                 content: trace.stream.reconstructed.message.content ||
-                    (typeof chunk.message?.content === 'string' ? chunk.message.content : chunk.message?.content ?? null),
+                    (typeof clone.message?.content === 'string' ? clone.message.content : clone.message?.content ?? null),
             };
-            trace.stream.reconstructed.tool_calls = (0, utils_1.safeClone)(chunk.tool_calls || []);
-            trace.stream.reconstructed.usage = (0, utils_1.safeClone)(chunk.usage || null);
-            trace.status = 'ok';
-            trace.endedAt = new Date().toISOString();
+            trace.stream.reconstructed.tool_calls = (0, utils_1.safeClone)(clone.tool_calls || []);
+            trace.stream.reconstructed.usage = (0, utils_1.safeClone)(clone.usage || null);
         }
-        this.publish('trace:update', traceId, { trace: this.cloneTrace(trace) });
-    }
-    recordStreamFinish(traceId, chunk) {
-        this.recordStreamChunk(traceId, chunk);
-    }
-    recordError(traceId, error) {
-        const trace = this.traces.get(traceId);
-        if (!trace) {
-            return;
-        }
-        trace.error = (0, utils_1.toErrorPayload)(error);
-        trace.status = 'error';
-        trace.endedAt = new Date().toISOString();
-        this.publish('trace:update', traceId, { trace: this.cloneTrace(trace) });
     }
     list(filters = {}) {
         const items = this.filteredTraces(filters).map(utils_1.toSummary);
@@ -99,7 +129,7 @@ class TraceStore extends node_events_1.EventEmitter {
     clear() {
         this.order = [];
         this.traces.clear();
-        this.publish('trace:clear', null, {});
+        this.publish('span:clear', null, {});
     }
     hierarchy(filters = {}) {
         const traces = this.filteredTraces(filters);
@@ -111,51 +141,49 @@ class TraceStore extends node_events_1.EventEmitter {
             };
         }
         const roots = new Map();
+        const traceBySpanId = new Map();
+        const traceNodeByTraceId = new Map();
+        const traceSessionByTraceId = new Map();
+        const parentNodeById = new Map();
         for (const trace of traces) {
-            const sessionId = trace.hierarchy.sessionId || 'unknown-session';
+            const sessionId = getTraceSessionId(trace);
             const sessionNode = getOrCreateNode(roots, `session:${sessionId}`, 'session', `Session ${sessionId}`, {
                 sessionId,
                 chatId: trace.hierarchy.chatId,
-            });
-            const lineage = [sessionNode];
-            const rootActorId = trace.hierarchy.rootActorId || 'unknown-actor';
-            const actorNode = getOrCreateNode(sessionNode.children, `actor:${sessionId}:${rootActorId}`, 'actor', rootActorId, {
-                actorId: rootActorId,
-                rootActorId,
-                sessionId,
+                rootActorId: trace.hierarchy.rootActorId,
                 topLevelAgentId: trace.hierarchy.topLevelAgentId,
             });
-            lineage.push(actorNode);
-            let currentNode = actorNode;
-            if (trace.hierarchy.kind === 'guardrail') {
-                const label = `${trace.hierarchy.guardrailPhase || 'guardrail'} guardrail`;
-                currentNode = getOrCreateNode(currentNode.children, `guardrail:${sessionId}:${rootActorId}:${trace.context.guardrailType || label}`, 'guardrail', label, {
-                    guardrailPhase: trace.hierarchy.guardrailPhase || null,
-                    guardrailType: trace.context.guardrailType || null,
-                    systemType: trace.context.systemType || null,
-                    watchdogPhase: trace.hierarchy.watchdogPhase || null,
-                });
-                lineage.push(currentNode);
-            }
-            else if (trace.hierarchy.childActorId) {
-                currentNode = getOrCreateNode(currentNode.children, `child-actor:${sessionId}:${rootActorId}:${trace.hierarchy.childActorId}`, 'child-actor', trace.hierarchy.childActorId, {
-                    actorId: trace.hierarchy.childActorId,
-                    childActorId: trace.hierarchy.childActorId,
-                    delegatedAgentId: trace.hierarchy.delegatedAgentId,
-                });
-                lineage.push(currentNode);
+            const traceNode = createTraceNode(trace);
+            traceBySpanId.set(trace.spanContext.spanId, trace);
+            traceNodeByTraceId.set(trace.id, traceNode);
+            traceSessionByTraceId.set(trace.id, sessionId);
+        }
+        for (const trace of traces) {
+            const sessionId = traceSessionByTraceId.get(trace.id) || 'unknown-session';
+            const sessionNode = roots.get(`session:${sessionId}`);
+            const traceNode = traceNodeByTraceId.get(trace.id);
+            if (!sessionNode || !traceNode) {
+                continue;
             }
-            if (trace.hierarchy.stage) {
-                currentNode = getOrCreateNode(currentNode.children, `stage:${sessionId}:${rootActorId}:${trace.hierarchy.childActorId || 'root'}:${trace.hierarchy.stage}`, 'stage', trace.hierarchy.stage, {
-                    stage: trace.hierarchy.stage,
-                    workflowState: trace.hierarchy.workflowState,
-                });
-                lineage.push(currentNode);
+            const parentTrace = trace.parentSpanId ? traceBySpanId.get(trace.parentSpanId) : null;
+            const parentTraceNode = parentTrace &&
+                traceSessionByTraceId.get(parentTrace.id) === sessionId &&
+                parentTrace.id !== trace.id
+                ? traceNodeByTraceId.get(parentTrace.id) || null
+                : null;
+            parentNodeById.set(traceNode.id, parentTraceNode || sessionNode);
+        }
+        for (const trace of traces) {
+            const traceNode = traceNodeByTraceId.get(trace.id);
+            const parentNode = traceNode ? parentNodeById.get(traceNode.id) || null : null;
+            if (!traceNode || !parentNode) {
+                continue;
             }
-            const traceNode = createTraceNode(trace);
-            currentNode.children.set(traceNode.id, traceNode);
-            for (const node of new Set(lineage)) {
-                applyTraceRollup(node, trace);
+            parentNode.children.set(traceNode.id, traceNode);
+            let currentNode = parentNode;
+            while (currentNode) {
+                applyTraceRollup(currentNode, trace);
+                currentNode = parentNodeById.get(currentNode.id) || null;
             }
         }
         return {
@@ -164,19 +192,24 @@ class TraceStore extends node_events_1.EventEmitter {
             rootNodes: [...roots.values()].map(serialiseNode),
         };
     }
-    recordStart(mode, context, request) {
-        const traceContext = (0, utils_1.normalizeTraceContext)(context, mode);
+    recordStart(mode, context, request, options = {}) {
+        const traceContext = applyConversationIdToContext((0, utils_1.normalizeTraceContext)(context, mode), options.attributes);
         const traceId = randomId();
+        const parentSpan = this.findTraceBySpanReference(options.parentSpanId);
         const startedAt = new Date().toISOString();
         const trace = {
+            attributes: buildSpanAttributes(traceContext, mode, request, options.attributes),
             context: traceContext,
             endedAt: null,
             error: null,
+            events: [],
             hierarchy: traceContext.hierarchy,
             id: traceId,
             kind: traceContext.kind,
             mode,
             model: traceContext.model,
+            name: options.name || getDefaultSpanName(traceContext, mode),
+            parentSpanId: parentSpan?.spanContext.spanId || options.parentSpanId || null,
             provider: traceContext.provider,
             request: {
                 input: (0, utils_1.safeClone)(request?.input),
@@ -187,6 +220,15 @@ class TraceStore extends node_events_1.EventEmitter {
             },
             response: null,
             startedAt,
+            spanContext: {
+                // The returned Loupe span handle (trace.id) is used for local mutation and SSE updates.
+                // spanContext contains the OpenTelemetry trace/span identifiers that are attached to
+                // the exported span payload and inherited by child spans.
+                spanId: randomHexId(16),
+                traceId: parentSpan?.spanContext.traceId || randomHexId(32),
+            },
+            spanKind: options.kind || 'CLIENT',
+            spanStatus: { code: 'UNSET' },
             status: 'pending',
             stream: mode === 'stream'
                 ? {
@@ -206,9 +248,24 @@ class TraceStore extends node_events_1.EventEmitter {
         this.order.push(traceId);
         this.traces.set(traceId, trace);
         this.evictIfNeeded();
-        this.publish('trace:add', traceId, { trace: this.cloneTrace(trace) });
+        this.publish('span:start', traceId, { trace: this.cloneTrace(trace) });
         return traceId;
     }
+    findTraceBySpanReference(spanReference) {
+        if (!spanReference) {
+            return null;
+        }
+        const byTraceId = this.traces.get(spanReference);
+        if (byTraceId) {
+            return byTraceId;
+        }
+        for (const trace of this.traces.values()) {
+            if (trace.spanContext.spanId === spanReference) {
+                return trace;
+            }
+        }
+        return null;
+    }
     evictIfNeeded() {
         while (this.order.length > this.maxTraces) {
             const oldest = this.order.shift();
@@ -216,7 +273,7 @@ class TraceStore extends node_events_1.EventEmitter {
             if (oldest) {
                 this.traces.delete(oldest);
             }
-            this.publish('trace:evict', oldest || null, removed ? { trace: this.cloneTrace(removed) } : {});
+            this.publish('span:evict', oldest || null, removed ? { trace: this.cloneTrace(removed) } : {});
         }
     }
     cloneTrace(trace) {
@@ -273,8 +330,9 @@ class TraceStore extends node_events_1.EventEmitter {
     }
     publish(type, traceId, payload) {
         const event = {
+            span: payload.trace,
+            spanId: traceId,
             type,
-            traceId,
             timestamp: new Date().toISOString(),
             ...payload,
         };
@@ -375,6 +433,151 @@ function buildGroupHierarchy(traces, groupBy) {
     }
     return [...groups.values()].map(serialiseNode);
 }
+function getTraceSessionId(trace) {
+    const conversationId = toNonEmptyString(trace.attributes?.['gen_ai.conversation.id']);
+    return conversationId || trace.hierarchy.sessionId || 'unknown-session';
+}
+function applyConversationIdToContext(context, extraAttributes) {
+    const conversationId = toNonEmptyString(extraAttributes?.['gen_ai.conversation.id']);
+    if (!conversationId || conversationId === context.sessionId) {
+        return context;
+    }
+    return {
+        ...context,
+        sessionId: conversationId,
+        chatId: conversationId,
+        rootSessionId: context.rootSessionId || conversationId,
+        rootChatId: context.rootChatId || conversationId,
+        tags: {
+            ...context.tags,
+            sessionId: conversationId,
+            chatId: conversationId,
+            rootSessionId: context.rootSessionId || conversationId,
+            rootChatId: context.rootChatId || conversationId,
+        },
+        hierarchy: {
+            ...context.hierarchy,
+            sessionId: conversationId,
+            chatId: conversationId,
+        },
+    };
+}
 function randomId() {
     return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
+function randomHexId(length) {
+    if (length % 2 !== 0) {
+        throw new RangeError(`OpenTelemetry hex IDs must have an even length. Received: ${length}`);
+    }
+    return (0, node_crypto_1.randomBytes)(Math.ceil(length / 2)).toString('hex').slice(0, length);
+}
+function normalizeSpanEvent(event) {
+    const attributes = (0, utils_1.safeClone)(event.attributes || {});
+    if (event.name === 'stream.finish') {
+        attributes['gen_ai.message.status'] = attributes['gen_ai.message.status'] || 'completed';
+    }
+    else if (event.name.startsWith(STREAM_EVENT_NAME_PREFIX)) {
+        attributes['gen_ai.message.status'] = attributes['gen_ai.message.status'] || 'in_progress';
+    }
+    if (attributes.finish_reasons && attributes['gen_ai.response.finish_reasons'] === undefined) {
+        attributes['gen_ai.response.finish_reasons'] = (0, utils_1.safeClone)(attributes.finish_reasons);
+    }
+    if (attributes.message && attributes['gen_ai.output.messages'] === undefined) {
+        attributes['gen_ai.output.messages'] = [(0, utils_1.safeClone)(attributes.message)];
+    }
+    return {
+        attributes,
+        name: event.name,
+        timestamp: new Date().toISOString(),
+    };
+}
+function toStreamPayload(payload, spanEvent) {
+    if (payload && typeof payload === 'object') {
+        return (0, utils_1.safeClone)(payload);
+    }
+    // Generic addSpanEvent() callers may only provide an OpenTelemetry-style event name
+    // plus attributes. Reconstruct the minimal legacy stream payload shape from that data
+    // so the existing dashboard stream timeline can continue to render incrementally.
+    const suffix = spanEvent.name.startsWith(STREAM_EVENT_NAME_PREFIX)
+        ? spanEvent.name.slice(STREAM_EVENT_NAME_PREFIX.length)
+        : spanEvent.name;
+    const eventType = suffix || 'event';
+    return {
+        ...(0, utils_1.safeClone)(spanEvent.attributes || {}),
+        type: eventType,
+    };
+}
+function getDefaultSpanName(context, mode) {
+    const prefix = context.provider || 'llm';
+    return `${prefix}.${mode}`;
+}
+function toNonEmptyString(value) {
+    return typeof value === 'string' && value.trim() ? value : null;
+}
+function buildSpanAttributes(context, mode, request, extraAttributes) {
+    const base = {
+        'gen_ai.conversation.id': context.sessionId || undefined,
+        'gen_ai.input.messages': Array.isArray(request?.input?.messages) ? (0, utils_1.safeClone)(request.input.messages) : undefined,
+        'gen_ai.operation.name': inferGenAIOperationName(request, mode),
+        'gen_ai.provider.name': context.provider || undefined,
+        'gen_ai.request.choice.count': typeof request?.input?.n === 'number' ? request.input.n : undefined,
+        'gen_ai.request.model': (typeof request?.input?.model === 'string' && request.input.model) || context.model || undefined,
+        'gen_ai.system': context.provider || undefined,
+        'loupe.actor.id': context.actorId || undefined,
+        'loupe.actor.type': context.actorType || undefined,
+        'loupe.guardrail.phase': context.guardrailPhase || undefined,
+        'loupe.guardrail.type': context.guardrailType || undefined,
+        'loupe.root_actor.id': context.rootActorId || undefined,
+        'loupe.root_session.id': context.rootSessionId || undefined,
+        'loupe.session.id': context.sessionId || undefined,
+        'loupe.stage': context.stage || undefined,
+        'loupe.tenant.id': context.tenantId || undefined,
+        'loupe.user.id': context.userId || undefined,
+    };
+    for (const [key, value] of Object.entries(context.tags || {})) {
+        base[`loupe.tag.${key}`] = value;
+    }
+    return Object.fromEntries(Object.entries({
+        ...base,
+        ...(extraAttributes || {}),
+    }).filter(([, value]) => value !== undefined && value !== null));
+}
+function applyResponseAttributes(trace, response) {
+    const finishReasons = Array.isArray(response?.finish_reasons)
+        ? response.finish_reasons
+        : response?.finish_reason
+            ? [response.finish_reason]
+            : [];
+    const usage = response?.usage;
+    if (typeof response?.model === 'string' && response.model) {
+        trace.attributes['gen_ai.response.model'] = response.model;
+    }
+    if (usage?.tokens?.prompt !== undefined) {
+        trace.attributes['gen_ai.usage.input_tokens'] = usage.tokens.prompt;
+    }
+    if (usage?.tokens?.completion !== undefined) {
+        trace.attributes['gen_ai.usage.output_tokens'] = usage.tokens.completion;
+    }
+    if (finishReasons.length > 0) {
+        trace.attributes['gen_ai.response.finish_reasons'] = (0, utils_1.safeClone)(finishReasons);
+    }
+    if (response?.message) {
+        trace.attributes['gen_ai.output.messages'] = [(0, utils_1.safeClone)(response.message)];
+        trace.attributes['gen_ai.output.type'] = inferGenAIOutputType(response.message.content);
+    }
+}
+function inferGenAIOperationName(request, mode) {
+    if (Array.isArray(request?.input?.messages) && request.input.messages.length > 0) {
+        return 'chat';
+    }
+    return mode;
+}
+function inferGenAIOutputType(content) {
+    if (typeof content === 'string' || Array.isArray(content)) {
+        return 'text';
+    }
+    if (content && typeof content === 'object') {
+        return 'json';
+    }
+    return 'unknown';
+}

package/dist/types.d.ts

@@ -1,5 +1,7 @@
 export type TraceMode = 'invoke' | 'stream';
 export type TraceStatus = 'pending' | 'ok' | 'error';
+export type SpanKind = 'INTERNAL' | 'SERVER' | 'CLIENT' | 'PRODUCER' | 'CONSUMER';
+export type SpanStatusCode = 'UNSET' | 'OK' | 'ERROR';
 export type TraceConfig = {
     host?: string;
     maxTraces?: number;
@@ -7,6 +9,20 @@ export type TraceConfig = {
     uiHotReload?: boolean;
 };
 export type TraceTags = Record<string, string>;
+export type SpanAttributes = Record<string, any>;
+export type SpanContext = {
+    spanId: string;
+    traceId: string;
+};
+export type SpanEvent = {
+    attributes: SpanAttributes;
+    name: string;
+    timestamp: string;
+};
+export type SpanStatus = {
+    code: SpanStatusCode;
+    message?: string;
+};
 export type TraceContext = {
     actorId?: string | null;
     actorType?: string | null;
@@ -79,6 +95,19 @@ export type TraceRequest = {
     input?: Record<string, any>;
     options?: Record<string, any>;
 };
+export type SpanStartOptions = {
+    attributes?: SpanAttributes;
+    kind?: SpanKind;
+    mode?: TraceMode;
+    name?: string;
+    parentSpanId?: string | null;
+    request?: TraceRequest;
+};
+export type SpanEventInput = {
+    attributes?: SpanAttributes;
+    name: string;
+    payload?: unknown;
+};
 export type TraceStructuredInputInsight = {
     format: 'xml';
     role: string;
@@ -101,14 +130,18 @@ export type TraceSummaryFlags = {
     hasStructuredInput: boolean;
 };
 export type TraceRecord = {
+    attributes: SpanAttributes;
     context: NormalizedTraceContext;
     endedAt: string | null;
     error: Record<string, any> | null;
+    events: SpanEvent[];
     hierarchy: TraceHierarchy;
     id: string;
     kind: string;
     mode: TraceMode;
     model: string | null;
+    name: string;
+    parentSpanId: string | null;
     provider: string | null;
     request: {
         input?: Record<string, any>;
@@ -116,6 +149,9 @@ export type TraceRecord = {
     };
     response: Record<string, any> | null;
     startedAt: string;
+    spanContext: SpanContext;
+    spanKind: SpanKind;
+    spanStatus: SpanStatus;
     status: TraceStatus;
     stream: null | {
         chunkCount: number;
@@ -153,14 +189,14 @@ export type TraceSummary = {
     tags: TraceTags;
 };
 export type TraceEvent = {
+    span?: TraceRecord;
+    spanId: string | null;
     timestamp: string;
-    trace?: TraceRecord;
-    traceId: string | null;
     type: string;
 };
 export type UIReloadEvent = {
     timestamp: string;
-    traceId: null;
+    spanId: null;
     type: 'ui:reload';
 };
 export type TraceListResponse = {
@@ -233,14 +269,13 @@ export type UIWatchController = {
     stop(): Promise<void>;
 };
 export type LocalLLMTracer = {
+    addSpanEvent(spanId: string, event: SpanEventInput): void;
     configure(config?: TraceConfig): void;
+    endSpan(spanId: string, response?: unknown): void;
     isEnabled(): boolean;
-    recordError(traceId: string, error: unknown): void;
-    recordInvokeFinish(traceId: string, response: unknown): void;
-    recordInvokeStart(context: TraceContext, request: TraceRequest): string;
-    recordStreamChunk(traceId: string, chunk: unknown): void;
-    recordStreamFinish(traceId: string, chunk: unknown): void;
-    recordStreamStart(context: TraceContext, request: TraceRequest): string;
+    recordException(spanId: string, error: unknown): void;
+    runWithActiveSpan<T>(spanId: string, callback: () => T): T;
+    startSpan(context: TraceContext, options?: SpanStartOptions): string;
     startServer(): Promise<{
         host: string;
         port: number;

package/dist/utils.d.ts

@@ -1,5 +1,6 @@
-import { type NormalizedTraceContext, type TraceContext, type TraceInsights, type TraceMode, type TraceRecord, type TraceSummary } from './types';
+import { type NormalizedTraceContext, type SpanEventInput, type TraceContext, type TraceInsights, type TraceMode, type TraceRecord, type TraceSummary } from './types';
 export declare function safeClone<T>(value: T): T;
+export declare function toSpanEventInputFromChunk(chunk: unknown): SpanEventInput;
 export declare function toErrorPayload(error: any): Record<string, any> | null;
 export declare function sanitizeHeaders(headers: Record<string, any> | undefined): Record<string, any>;
 export declare function envFlag(name: string): boolean;

package/dist/utils.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.safeClone = safeClone;
+exports.toSpanEventInputFromChunk = toSpanEventInputFromChunk;
 exports.toErrorPayload = toErrorPayload;
 exports.sanitizeHeaders = sanitizeHeaders;
 exports.envFlag = envFlag;
@@ -30,6 +31,19 @@ function safeClone(value) {
         return value;
     }
 }
+function toSpanEventInputFromChunk(chunk) {
+    const payload = safeClone(chunk);
+    const eventType = typeof payload?.type === 'string' && payload.type ? payload.type : 'event';
+    const attributes = payload !== null && typeof payload === 'object' ? { ...payload } : {};
+    if ('type' in attributes) {
+        delete attributes.type;
+    }
+    return {
+        attributes,
+        name: `stream.${eventType}`,
+        payload: payload ?? undefined,
+    };
+}
 function toErrorPayload(error) {
     if (!error) {
         return null;