@uselemma/tracing 3.0.3 → 4.0.0

package/dist/trace-wrapper.d.ts

@@ -1,107 +0,0 @@
-import { Span } from "@opentelemetry/api";
-export type TraceContext = {
-    /** The active OpenTelemetry span for this agent run. */
-    span: Span;
-    /** Unique identifier for this agent run. */
-    runId: string;
-    /**
-     * Override the run output and close the span immediately.
-     *
-     * In non-streaming agents, `complete()` is **optional** — the wrapper
-     * automatically captures the return value as `ai.agent.output` and closes
-     * the span when the function returns. Call it explicitly only when you need
-     * to record a different output than the return value, or close the span
-     * before the function exits.
-     *
-     * In streaming agents (`{ streaming: true }`), `complete()` is **required**
-     * — call it inside the stream's `onFinish` callback once the full output is
-     * assembled.
-     *
-     * Idempotent: the first call wins, subsequent calls are no-ops.
-     */
-    complete: (result?: unknown) => void;
-    /**
-     * @deprecated Use {@link complete} instead.
-     */
-    onComplete: (result: unknown) => void;
-    /**
-     * Record an error on the span and mark the run as failed.
-     * Does not close the span — the wrapper handles closing on return or error.
-     */
-    fail: (error: unknown) => void;
-    /**
-     * @deprecated Use {@link fail} instead.
-     */
-    recordError: (error: unknown) => void;
-};
-export type WrapAgentOptions = {
-    /** Mark this run as an experiment in Lemma. */
-    isExperiment?: boolean;
-    /**
-     * Set to `true` for agents that return a streaming response before the
-     * full output is known.
-     *
-     * When `true`, the wrapper does **not** auto-close the span on function
-     * return. You must call `ctx.complete(output)` inside the stream's
-     * `onFinish` callback once the full output is assembled.
-     *
-     * @default false
-     */
-    streaming?: boolean;
-};
-export type WrapRunOptions = {
-    /** Optional thread identifier for this invocation. */
-    threadId?: string;
-    /** Mark this specific invocation as an experiment. */
-    isExperiment?: boolean;
-};
-/**
- * Wraps an agent function with OpenTelemetry tracing, automatically creating
- * a span for the agent run and providing a `TraceContext` to the wrapped function.
- *
- * **Non-streaming (default):** simply return a value from the wrapped function.
- * The wrapper captures it as `ai.agent.output` and closes the span automatically.
- * No call to `ctx.complete()` is needed.
- *
- * **Streaming:** pass `{ streaming: true }` as the third argument. The wrapper
- * will not auto-close the span on return; call `ctx.complete(output)` inside
- * the stream's `onFinish` callback once the full output is assembled.
- *
- * @example
- * // Non-streaming — just return a value
- * const myAgent = agent('my-agent', async (input: string) => {
- *   const { text } = await generateText({
- *     model: openai('gpt-4o'), prompt: input,
- *     experimental_telemetry: { isEnabled: true },
- *   });
- *   return text; // wrapper auto-captures and closes the span
- * });
- *
- * @example
- * // Streaming — opt into manual lifecycle
- * const streamingAgent = agent('streaming-agent', async (input: string, ctx) => {
- *   const result = await streamText({
- *     model: openai('gpt-4o'), prompt: input,
- *     experimental_telemetry: { isEnabled: true },
- *     onFinish({ text }) { ctx.complete(text); },
- *   });
- *   return result.toDataStreamResponse();
- * }, { streaming: true });
- *
- * @param agentName - Human-readable agent name recorded as `ai.agent.name`.
- * @param fn - The agent function to wrap. Receives the call-time input as its
- *   first argument and an optional {@link TraceContext} as its second.
- * @param options - Configuration for the agent trace.
- * @returns An async function that accepts an `input`, executes `fn` inside a
- *   traced context, and returns `{ result, runId, span }`.
- */
-export declare function agent<Input = unknown>(agentName: string, fn: (input: Input, traceContext: TraceContext) => any, options?: WrapAgentOptions): (this: any, input: Input, runOptions?: WrapRunOptions) => Promise<{
-    result: any;
-    runId: string;
-    span: Span;
-}>;
-/**
- * @deprecated Use {@link agent} instead. `wrapAgent` will be removed in a future major version.
- */
-export declare const wrapAgent: typeof agent;
-//# sourceMappingURL=trace-wrapper.d.ts.map

package/dist/trace-wrapper.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"trace-wrapper.d.ts","sourceRoot":"","sources":["../src/trace-wrapper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgC,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAKxE,MAAM,MAAM,YAAY,GAAG;IACzB,wDAAwD;IACxD,IAAI,EAAE,IAAI,CAAC;IACX,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;;;;;;OAcG;IACH,QAAQ,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACrC;;OAEG;IACH,UAAU,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACtC;;;OAGG;IACH,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/B;;OAEG;IACH,WAAW,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+CAA+C;IAC/C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAkBF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,KAAK,CAAC,KAAK,GAAG,OAAO,EACnC,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,YAAY,KAAK,GAAG,EACrD,OAAO,CAAC,EAAE,gBAAgB,UAKlB,GAAG,SACF,KAAK,eACC,cAAc;;;;GAmF9B;AAED;;GAEG;AACH,eAAO,MAAM,SAAS,cAAQ,CAAC"}

package/dist/trace-wrapper.js

@@ -1,133 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.wrapAgent = void 0;
-exports.agent = agent;
-const api_1 = require("@opentelemetry/api");
-const uuid_1 = require("uuid");
-const debug_mode_1 = require("./debug-mode");
-const experiment_mode_1 = require("./experiment-mode");
-function resolveIsExperiment(globalEnabled, wrapperOptions, runOptions) {
-    if (globalEnabled)
-        return true;
-    if (typeof runOptions?.isExperiment === "boolean")
-        return runOptions.isExperiment;
-    return wrapperOptions?.isExperiment === true;
-}
-function normalizeThreadId(threadId) {
-    if (typeof threadId !== "string")
-        return undefined;
-    const trimmed = threadId.trim();
-    return trimmed.length > 0 ? trimmed : undefined;
-}
-/**
- * Wraps an agent function with OpenTelemetry tracing, automatically creating
- * a span for the agent run and providing a `TraceContext` to the wrapped function.
- *
- * **Non-streaming (default):** simply return a value from the wrapped function.
- * The wrapper captures it as `ai.agent.output` and closes the span automatically.
- * No call to `ctx.complete()` is needed.
- *
- * **Streaming:** pass `{ streaming: true }` as the third argument. The wrapper
- * will not auto-close the span on return; call `ctx.complete(output)` inside
- * the stream's `onFinish` callback once the full output is assembled.
- *
- * @example
- * // Non-streaming — just return a value
- * const myAgent = agent('my-agent', async (input: string) => {
- *   const { text } = await generateText({
- *     model: openai('gpt-4o'), prompt: input,
- *     experimental_telemetry: { isEnabled: true },
- *   });
- *   return text; // wrapper auto-captures and closes the span
- * });
- *
- * @example
- * // Streaming — opt into manual lifecycle
- * const streamingAgent = agent('streaming-agent', async (input: string, ctx) => {
- *   const result = await streamText({
- *     model: openai('gpt-4o'), prompt: input,
- *     experimental_telemetry: { isEnabled: true },
- *     onFinish({ text }) { ctx.complete(text); },
- *   });
- *   return result.toDataStreamResponse();
- * }, { streaming: true });
- *
- * @param agentName - Human-readable agent name recorded as `ai.agent.name`.
- * @param fn - The agent function to wrap. Receives the call-time input as its
- *   first argument and an optional {@link TraceContext} as its second.
- * @param options - Configuration for the agent trace.
- * @returns An async function that accepts an `input`, executes `fn` inside a
- *   traced context, and returns `{ result, runId, span }`.
- */
-function agent(agentName, fn, options) {
-    const streaming = options?.streaming ?? false;
-    const wrappedFunction = async function (input, runOptions) {
-        const tracer = api_1.trace.getTracer("lemma");
-        const runId = (0, uuid_1.v4)();
-        const isExperiment = resolveIsExperiment((0, experiment_mode_1.isExperimentModeEnabled)(), options, runOptions);
-        const threadId = normalizeThreadId(runOptions?.threadId);
-        const attributes = {
-            "ai.agent.name": agentName,
-            "lemma.run_id": runId,
-            "lemma.is_experiment": isExperiment,
-        };
-        if (threadId) {
-            attributes["lemma.thread_id"] = threadId;
-        }
-        const span = tracer.startSpan("ai.agent.run", { attributes }, api_1.ROOT_CONTEXT);
-        span.setAttribute("ai.agent.input", JSON.stringify(input) ?? "null");
-        (0, debug_mode_1.lemmaDebug)("trace-wrapper", "span started", { agentName, runId });
-        const ctx = api_1.trace.setSpan(api_1.ROOT_CONTEXT, span);
-        let outputSet = false;
-        try {
-            return await api_1.context.with(ctx, async () => {
-                const complete = (result) => {
-                    if (outputSet)
-                        return;
-                    span.setAttribute("ai.agent.output", JSON.stringify(result) ?? "null");
-                    outputSet = true;
-                    span.end();
-                    (0, debug_mode_1.lemmaDebug)("trace-wrapper", "complete called", { runId });
-                };
-                const fail = (error) => {
-                    span.recordException(error instanceof Error ? error : new Error(String(error)));
-                    span.setStatus({ code: 2 }); // SpanStatusCode.ERROR
-                };
-                const traceCtx = {
-                    span,
-                    runId,
-                    complete,
-                    onComplete: complete,
-                    fail,
-                    recordError: fail,
-                };
-                const result = await fn.call(this, input, traceCtx);
-                if (!streaming && !outputSet) {
-                    complete(result);
-                }
-                else if (streaming && !outputSet) {
-                    (0, debug_mode_1.lemmaDebug)("trace-wrapper", "streaming agent returned without complete()", { agentName, runId });
-                    console.warn(`[lemma] Streaming agent "${agentName}" returned without calling ctx.complete(). ` +
-                        `Call ctx.complete(output) inside the stream's onFinish callback to close the run span.`);
-                }
-                return { result, runId, span };
-            });
-        }
-        catch (err) {
-            span.recordException(err);
-            span.setStatus({ code: 2 }); // SpanStatusCode.ERROR
-            if (!outputSet) {
-                outputSet = true;
-                span.end();
-            }
-            (0, debug_mode_1.lemmaDebug)("trace-wrapper", "span ended on error", { runId, error: String(err) });
-            throw err;
-        }
-    };
-    return wrappedFunction;
-}
-/**
- * @deprecated Use {@link agent} instead. `wrapAgent` will be removed in a future major version.
- */
-exports.wrapAgent = agent;
-//# sourceMappingURL=trace-wrapper.js.map

package/dist/trace-wrapper.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"trace-wrapper.js","sourceRoot":"","sources":["../src/trace-wrapper.ts"],"names":[],"mappings":"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"}