@inference/tracing 0.0.21 → 0.0.22

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). */
@@ -233,7 +247,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) {
@@ -122,7 +125,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,6 +193,9 @@ 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) {

package/dist/semconv.d.ts

@@ -134,6 +134,13 @@ export declare const Attr: {
      * 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

@@ -134,6 +134,13 @@ export const Attr = {
      * 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.22",
   "type": "module",
   "description": "First-party OpenInference-shaped tracing for TypeScript LLM and agent applications on Catalyst by Inference.net.",
   "homepage": "https://inference.net",