@inference/tracing 0.0.21 → 0.0.23

package/README.md

@@ -11,6 +11,9 @@ prompts, responses, token usage, and parent-child agent flows.
 This package is currently in beta. APIs may change before `1.0`, but the package
 name and import paths are intended to remain stable.
 
+Full documentation lives at
+[docs.inference.net/integrations/traces/overview](https://docs.inference.net/integrations/traces/overview).
+
 ## Install
 
 ```bash
@@ -192,8 +195,11 @@ await agentSpan(
     agentName: "Refund Review Agent",
     spanName: "refund-review.run",
     sessionId: "conversation-1842",
+    userId: "user-7723",
     role: "refunds",
     system: "internal",
+    metadata: { queue: "priority" },
+    tags: ["refunds", "beta"],
   },
   async (span) => {
     span.setInput("Review refund request #1842");
@@ -210,10 +216,12 @@ await tracing.shutdown();
 survives display-name changes so Catalyst can group executions correctly in the
 agent dashboard. `agentName` is optional and becomes `agent.name` when you want
 a human-readable display label. `sessionId` is optional and should identify one
-conversation, not the whole process. Any child spans created inside the callback
-automatically parent under the agent span and supported SDK wrappers copy the
-active `agent.id` and optional `agent.name` / `agent.role` onto their child
-spans.
+conversation, not the whole process. `userId` is optional and becomes `user.id`
+so Catalyst can filter and group traces by end user. `metadata` and `tags` are
+also optional: `metadata` attaches a JSON bag and `tags` attaches a string
+array to the span. Any child spans created inside the callback automatically
+parent under the agent span and supported SDK wrappers copy the active
+`agent.id` and optional `agent.name` / `agent.role` onto their child spans.
 
 ## Configuration
 
@@ -244,6 +252,7 @@ understand them without custom adapters:
 | Model metadata | `llm.model_name`, `llm.invocation_parameters` |
 | Token counts | `llm.token_count.prompt`, `llm.token_count.completion`, `llm.token_count.total` |
 | Provider/system | `gen_ai.system` |
+| Agent and session | `agent.id`, `agent.name`, `agent.role`, `session.id`, `user.id`, `metadata`, `tags` |
 
 Constants are exported for custom spans:
 

package/dist/agent-span.d.ts

@@ -56,6 +56,15 @@ export interface AgentSpanOptions {
      * so downstream viewers can group agent spans by conversation.
      */
     sessionId?: string;
+    /**
+     * End-user identifier the work runs on behalf of. Becomes this span's
+     * `user.id` so downstream viewers can filter and group traces by user.
+     */
+    userId?: string;
+    /** Free-form metadata bag — JSON-stringified onto the `metadata` attribute. */
+    metadata?: Record<string, unknown>;
+    /** Free-form string tags — set on the `tags` attribute as a string array. */
+    tags?: readonly string[];
 }
 /**
  * Options accepted by {@link manualSpan}.
@@ -91,6 +100,11 @@ export interface ManualSpanOptions {
      * so downstream viewers can group manual spans by conversation.
      */
     sessionId?: string;
+    /**
+     * End-user identifier the work runs on behalf of. Becomes this span's
+     * `user.id` so downstream viewers can filter and group traces by user.
+     */
+    userId?: string;
     /** Convenience: set `input.value` from the callback. Strings pass through; objects are JSON-stringified. */
     input?: unknown;
     /** Convenience: set `output.value` before the callback runs (rare — usually set inside the callback). */
@@ -155,6 +169,12 @@ export interface AgentSpanHandle {
      * Record the model name. Becomes `llm.model_name`.
      */
     setModel(model: string): void;
+    /** Record the overall agent outcome, e.g. success, failure, partial, or cancelled. */
+    setOutcome(outcome: string): void;
+    /** Record why the agent stopped, e.g. completed, error, timeout, or max_turns. */
+    setStopReason(reason: string): void;
+    /** Record whether the agent reached its expected finalization path. */
+    setFinalized(finalized: boolean): void;
     /**
      * Record tool identity on a TOOL-kind span.
      */
@@ -233,7 +253,7 @@ export declare function manualSpan<T>(tracer: Tracer, options: ManualSpanOptions
  * Wrap a chunk of agent work in an OpenInference-shaped AGENT span.
  *
  * Sets `openinference.span.kind=AGENT`, `agent.id`, optional
- * `agent.name` / `agent.role` / `session.id`, and `gen_ai.system`; the
+ * `agent.name` / `agent.role` / `session.id` / `user.id`, and `gen_ai.system`; the
  * callback can fill in `input`, `output`, model, and tokens via the handle.
  * The callback runs inside the span's active OTel context, so any child spans
  * created by an instrumented LLM SDK (or by `tracer.startSpan(...)` inside the

package/dist/agent-span.js

@@ -80,6 +80,9 @@ export async function manualSpan(tracer, options, fn) {
     const sessionId = options.sessionId?.trim();
     if (sessionId)
         startAttributes[Attr.SESSION_ID] = sessionId;
+    const userId = options.userId?.trim();
+    if (userId)
+        startAttributes[Attr.USER_ID] = userId;
     if (options.attributes)
         Object.assign(startAttributes, options.attributes);
     if (options.metadata && Object.keys(options.metadata).length > 0) {
@@ -106,11 +109,29 @@ export async function manualSpan(tracer, options, fn) {
     });
     try {
         const result = await context.with(ctx, () => fn(handle));
-        span.setStatus({ code: SpanStatusCode.OK });
+        if (spanKind === SpanKindValues.AGENT) {
+            const finalOutcome = handle.getOutcomeSet()
+                ? handle.getExplicitOutcome()
+                : "success";
+            if (!handle.getOutcomeSet())
+                span.setAttribute(Attr.AGENT_OUTCOME, finalOutcome);
+            if (!handle.getStopReasonSet()) {
+                span.setAttribute(Attr.AGENT_STOP_REASON, defaultStopReason(finalOutcome));
+            }
+            if (!handle.getFinalizedSet()) {
+                span.setAttribute(Attr.AGENT_FINALIZED, finalOutcome === "success");
+            }
+        }
+        setStatusForOutcome(span, spanKind, handle.getExplicitOutcome());
         return result;
     }
     catch (err) {
         span.recordException(err);
+        if (spanKind === SpanKindValues.AGENT) {
+            span.setAttribute(Attr.AGENT_OUTCOME, "failure");
+            span.setAttribute(Attr.AGENT_STOP_REASON, "error");
+            span.setAttribute(Attr.AGENT_FINALIZED, false);
+        }
         span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
         throw err;
     }
@@ -122,7 +143,7 @@ export async function manualSpan(tracer, options, fn) {
  * Wrap a chunk of agent work in an OpenInference-shaped AGENT span.
  *
  * Sets `openinference.span.kind=AGENT`, `agent.id`, optional
- * `agent.name` / `agent.role` / `session.id`, and `gen_ai.system`; the
+ * `agent.name` / `agent.role` / `session.id` / `user.id`, and `gen_ai.system`; the
  * callback can fill in `input`, `output`, model, and tokens via the handle.
  * The callback runs inside the span's active OTel context, so any child spans
  * created by an instrumented LLM SDK (or by `tracer.startSpan(...)` inside the
@@ -190,9 +211,16 @@ export async function agentSpan(tracer, options, fn) {
         agentName,
         agentRole: options.role,
         sessionId: options.sessionId,
+        userId: options.userId,
+        metadata: options.metadata,
+        tags: options.tags,
     }, fn);
 }
 function makeHandle(span) {
+    let outcomeSet = false;
+    let explicitOutcome = "success";
+    let stopReasonSet = false;
+    let finalizedSet = false;
     return {
         setInput(value) {
             if (value === undefined)
@@ -218,6 +246,19 @@ function makeHandle(span) {
         setModel(model) {
             span.setAttribute(Attr.MODEL_NAME, model);
         },
+        setOutcome(outcome) {
+            outcomeSet = true;
+            explicitOutcome = outcome;
+            span.setAttribute(Attr.AGENT_OUTCOME, outcome);
+        },
+        setStopReason(reason) {
+            stopReasonSet = true;
+            span.setAttribute(Attr.AGENT_STOP_REASON, reason);
+        },
+        setFinalized(finalized) {
+            finalizedSet = true;
+            span.setAttribute(Attr.AGENT_FINALIZED, finalized);
+        },
         setTool({ name, callId }) {
             span.setAttribute(Attr.TOOL_NAME, name);
             if (callId != null)
@@ -229,9 +270,35 @@ function makeHandle(span) {
         setAttributes(attributes) {
             setSpanAttributes(span, attributes);
         },
+        getOutcomeSet() {
+            return outcomeSet;
+        },
+        getExplicitOutcome() {
+            return explicitOutcome;
+        },
+        getStopReasonSet() {
+            return stopReasonSet;
+        },
+        getFinalizedSet() {
+            return finalizedSet;
+        },
         raw: span,
     };
 }
+function defaultStopReason(outcome) {
+    if (outcome === "success")
+        return "completed";
+    if (outcome === "failure")
+        return "error";
+    return outcome;
+}
+function setStatusForOutcome(span, spanKind, outcome) {
+    if (spanKind === SpanKindValues.AGENT && outcome === "failure") {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: "Agent outcome failure" });
+        return;
+    }
+    span.setStatus({ code: SpanStatusCode.OK });
+}
 function resolveAgentSpanName(options, agentId, agentName) {
     const explicitName = normalize(options.spanName);
     if (explicitName != null)

package/dist/instrumentation/claude-agent-sdk.js

@@ -81,6 +81,10 @@ function makeState() {
         cacheReadTokens: 0,
         llmCalls: 0,
         pendingToolSpans: new Map(),
+        resultSubtype: undefined,
+        resultStopReason: undefined,
+        resultIsError: false,
+        agentClosed: false,
     };
 }
 function wrapAsyncIterable(upstream, span, tracer, ctx) {
@@ -97,6 +101,7 @@ function wrapAsyncIterable(upstream, span, tracer, ctx) {
                         }
                         else {
                             finalize(span, state);
+                            state.agentClosed = true;
                         }
                         return result;
                     }
@@ -108,16 +113,20 @@ function wrapAsyncIterable(upstream, span, tracer, ctx) {
                         }
                         state.pendingToolSpans.clear();
                         span.recordException(err);
+                        span.setAttribute(Attr.AGENT_OUTCOME, "failure");
+                        span.setAttribute(Attr.AGENT_STOP_REASON, "error");
+                        span.setAttribute(Attr.AGENT_FINALIZED, false);
                         span.setStatus({
                             code: SpanStatusCode.ERROR,
                             message: String(err),
                         });
+                        state.agentClosed = true;
                         span.end();
                         throw err;
                     }
                 },
                 async return(value) {
-                    finalize(span, state);
+                    closeEarly(span, state);
                     if (it.return != null)
                         return it.return(value);
                     return { value, done: true };
@@ -184,6 +193,12 @@ function handleMessage(msg, state, tracer, ctx) {
             }
         }
     }
+    else if (msg.type === "result") {
+        state.resultSubtype = typeof msg.subtype === "string" ? msg.subtype : undefined;
+        state.resultStopReason =
+            typeof msg.stop_reason === "string" ? msg.stop_reason : undefined;
+        state.resultIsError = msg.is_error === true;
+    }
 }
 function addUsage(state, usage) {
     if (usage == null)
@@ -200,12 +215,51 @@ function addUsage(state, usage) {
     }
 }
 function finalize(span, state) {
-    // Close any tool spans that never got a matching tool_result.
     for (const s of state.pendingToolSpans.values()) {
-        s.setStatus({ code: SpanStatusCode.OK });
+        s.setAttribute(Attr.TOOL_RESULT_MISSING, true);
+        s.setStatus({ code: SpanStatusCode.ERROR, message: "Missing tool_result" });
+        s.end();
+    }
+    state.pendingToolSpans.clear();
+    setAgentSummary(span, state);
+    setAgentFinalState(span, state);
+    if (isErrorResult(state)) {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: resultStopReason(state) });
+    }
+    else {
+        span.setStatus({ code: SpanStatusCode.OK });
+    }
+    span.end();
+}
+function closeEarly(span, state) {
+    if (state.agentClosed)
+        return;
+    if (state.resultSubtype != null) {
+        finalize(span, state);
+        state.agentClosed = true;
+        return;
+    }
+    cancelAgent(span, state);
+    state.agentClosed = true;
+    span.end();
+}
+function cancelAgent(span, state) {
+    for (const s of state.pendingToolSpans.values()) {
+        s.setAttribute(Attr.TOOL_RESULT_MISSING, true);
+        s.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: "Stream closed before tool_result",
+        });
         s.end();
     }
     state.pendingToolSpans.clear();
+    setAgentSummary(span, state);
+    span.setAttribute(Attr.AGENT_OUTCOME, "cancelled");
+    span.setAttribute(Attr.AGENT_STOP_REASON, "cancelled");
+    span.setAttribute(Attr.AGENT_FINALIZED, false);
+    span.setStatus({ code: SpanStatusCode.OK });
+}
+function setAgentSummary(span, state) {
     span.setAttribute(Attr.OUTPUT_VALUE, state.lastAssistantText);
     if (state.inputTokens > 0) {
         span.setAttribute(Attr.TOKEN_COUNT_PROMPT, state.inputTokens);
@@ -224,8 +278,36 @@ function finalize(span, state) {
     }
     span.setAttribute(Attr.AGENT_TOOL_CALL_COUNT, state.toolCallCount);
     span.setAttribute(Attr.AGENT_LLM_CALL_COUNT, state.llmCalls);
-    span.setStatus({ code: SpanStatusCode.OK });
-    span.end();
+}
+function setAgentFinalState(span, state) {
+    const subtype = state.resultSubtype;
+    if (isErrorResult(state)) {
+        span.setAttribute(Attr.AGENT_OUTCOME, "failure");
+        span.setAttribute(Attr.AGENT_STOP_REASON, resultStopReason(state));
+        span.setAttribute(Attr.AGENT_FINALIZED, false);
+    }
+    else if (subtype === "success") {
+        span.setAttribute(Attr.AGENT_OUTCOME, "success");
+        span.setAttribute(Attr.AGENT_STOP_REASON, "completed");
+        span.setAttribute(Attr.AGENT_FINALIZED, true);
+    }
+    else if (subtype != null && subtype !== "") {
+        span.setAttribute(Attr.AGENT_OUTCOME, "partial");
+        span.setAttribute(Attr.AGENT_STOP_REASON, subtype);
+        span.setAttribute(Attr.AGENT_FINALIZED, false);
+    }
+    else {
+        span.setAttribute(Attr.AGENT_OUTCOME, "partial");
+        span.setAttribute(Attr.AGENT_STOP_REASON, "missing_result");
+        span.setAttribute(Attr.AGENT_FINALIZED, false);
+    }
+}
+function isErrorResult(state) {
+    const subtype = state.resultSubtype;
+    return (state.resultIsError || subtype === "error" || subtype?.startsWith("error_") === true);
+}
+function resultStopReason(state) {
+    return state.resultStopReason ?? state.resultSubtype ?? "error";
 }
 function stringify(value) {
     if (typeof value === "string")

package/dist/semconv.d.ts

@@ -128,12 +128,27 @@ export declare const Attr: {
     readonly AGENT_TOOL_CALL_COUNT: "agent.tool_call_count";
     /** Number of LLM calls in an agent run. */
     readonly AGENT_LLM_CALL_COUNT: "agent.llm_call_count";
+    /** Overall agent run outcome, e.g. success, failure, partial, or cancelled. */
+    readonly AGENT_OUTCOME: "agent.outcome";
+    /** Why an agent run stopped, e.g. completed, error, timeout, or max_turns. */
+    readonly AGENT_STOP_REASON: "agent.stop_reason";
+    /** Whether the agent run reached its expected finalization path. */
+    readonly AGENT_FINALIZED: "agent.finalized";
+    /** Whether a tool-use span ended without a correlated tool result. */
+    readonly TOOL_RESULT_MISSING: "tool.result.missing";
     /**
      * Stable identifier for one conversation, used to group related spans.
      *
      * Wire key: `session.id`
      */
     readonly SESSION_ID: "session.id";
+    /**
+     * End-user identifier the work runs on behalf of, used to filter and
+     * group traces by user.
+     *
+     * Wire key: `user.id`
+     */
+    readonly USER_ID: "user.id";
 };
 /**
  * Canonical string values for {@link Attr.SPAN_KIND}.

package/dist/semconv.js

@@ -128,12 +128,27 @@ export const Attr = {
     AGENT_TOOL_CALL_COUNT: "agent.tool_call_count",
     /** Number of LLM calls in an agent run. */
     AGENT_LLM_CALL_COUNT: "agent.llm_call_count",
+    /** Overall agent run outcome, e.g. success, failure, partial, or cancelled. */
+    AGENT_OUTCOME: "agent.outcome",
+    /** Why an agent run stopped, e.g. completed, error, timeout, or max_turns. */
+    AGENT_STOP_REASON: "agent.stop_reason",
+    /** Whether the agent run reached its expected finalization path. */
+    AGENT_FINALIZED: "agent.finalized",
+    /** Whether a tool-use span ended without a correlated tool result. */
+    TOOL_RESULT_MISSING: "tool.result.missing",
     /**
      * Stable identifier for one conversation, used to group related spans.
      *
      * Wire key: `session.id`
      */
     SESSION_ID: "session.id",
+    /**
+     * End-user identifier the work runs on behalf of, used to filter and
+     * group traces by user.
+     *
+     * Wire key: `user.id`
+     */
+    USER_ID: "user.id",
 };
 /**
  * Canonical string values for {@link Attr.SPAN_KIND}.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inference/tracing",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "type": "module",
   "description": "First-party OpenInference-shaped tracing for TypeScript LLM and agent applications on Catalyst by Inference.net.",
   "homepage": "https://inference.net",