@uselemma/tracing 2.12.1 → 2.15.0

package/README.md

@@ -34,20 +34,24 @@ enableExperimentMode();
 - `ai.agent.name`
 - `lemma.run_id`
 - `lemma.is_experiment`
+- `lemma.thread_id` (when `threadId` is passed at invocation time)
 
 ```typescript
 import { wrapAgent } from "@uselemma/tracing";
 
 const wrappedFn = wrapAgent(
   "my-agent",
-  async ({ onComplete }) => {
+  async ({ onComplete }, { userMessage }: { userMessage: string }) => {
     const result = await doWork(userMessage);
     onComplete(result);
     return result;
   },
 );
 
-const { result, runId } = await wrappedFn({ userMessage });
+const { result, runId } = await wrappedFn(
+  { userMessage },
+  { threadId: "thread_123", isExperiment: false },
+);
 ```
 
 ## Export Behavior

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { registerOTel, createLemmaSpanProcessor, type LemmaOTelOptions, type RegisterOTelOptions, type CreateLemmaSpanProcessorOptions, } from "./register";
 export { enableExperimentMode, disableExperimentMode, isExperimentModeEnabled, } from "./experiment-mode";
 export { enableDebugMode, disableDebugMode, isDebugModeEnabled, } from "./debug-mode";
-export { wrapAgent, type TraceContext, type WrapAgentOptions } from "./trace-wrapper";
+export { wrapAgent, type TraceContext, type WrapAgentOptions, type WrapRunOptions, } from "./trace-wrapper";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,wBAAwB,EACxB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,+BAA+B,GACrC,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,SAAS,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,wBAAwB,EACxB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,+BAA+B,GACrC,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,SAAS,EACT,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,uCAMoB;AALlB,wGAAA,YAAY,OAAA;AACZ,oHAAA,wBAAwB,OAAA;AAK1B,qDAI2B;AAHzB,uHAAA,oBAAoB,OAAA;AACpB,wHAAA,qBAAqB,OAAA;AACrB,0HAAA,uBAAuB,OAAA;AAEzB,2CAIsB;AAHpB,6GAAA,eAAe,OAAA;AACf,8GAAA,gBAAgB,OAAA;AAChB,gHAAA,kBAAkB,OAAA;AAEpB,iDAAsF;AAA7E,0GAAA,SAAS,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,uCAMoB;AALlB,wGAAA,YAAY,OAAA;AACZ,oHAAA,wBAAwB,OAAA;AAK1B,qDAI2B;AAHzB,uHAAA,oBAAoB,OAAA;AACpB,wHAAA,qBAAqB,OAAA;AACrB,0HAAA,uBAAuB,OAAA;AAEzB,2CAIsB;AAHpB,6GAAA,eAAe,OAAA;AACf,8GAAA,gBAAgB,OAAA;AAChB,gHAAA,kBAAkB,OAAA;AAEpB,iDAKyB;AAJvB,0GAAA,SAAS,OAAA"}

package/dist/trace-wrapper.d.ts

@@ -17,6 +17,12 @@ export type WrapAgentOptions = {
     /** Mark this run as an experiment in Lemma. */
     isExperiment?: 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.
@@ -44,7 +50,7 @@ export type WrapAgentOptions = {
  * @param options.isExperiment - Mark this run as an experiment in Lemma.
  * @returns An async function that accepts an `input`, executes `fn` inside a traced context, and returns `{ result, runId, span }`.
  */
-export declare function wrapAgent<Input = unknown>(agentName: string, fn: (traceContext: TraceContext, input: Input) => any, options?: WrapAgentOptions): (this: any, input: Input) => Promise<{
+export declare function wrapAgent<Input = unknown>(agentName: string, fn: (traceContext: TraceContext, input: Input) => any, options?: WrapAgentOptions): (this: any, input: Input, runOptions?: WrapRunOptions) => Promise<{
     result: any;
     runId: string;
     span: Span;

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

@@ -1 +1 @@
-{"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;;;;OAIG;IACH,UAAU,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACtC,8DAA8D;IAC9D,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;CACxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,SAAS,CAAC,KAAK,GAAG,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,YAAY,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,KAAK,GAAG,EAAE,OAAO,CAAC,EAAE,gBAAgB,UAC/F,GAAG,SAAS,KAAK;;;;GAqDhE"}
+{"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;;;;OAIG;IACH,UAAU,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACtC,8DAA8D;IAC9D,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;CACxB,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;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,SAAS,CAAC,KAAK,GAAG,OAAO,EACvC,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,CAAC,YAAY,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,KAAK,GAAG,EACrD,OAAO,CAAC,EAAE,gBAAgB,UAGlB,GAAG,SACF,KAAK,eACC,cAAc;;;;GAoE9B"}

package/dist/trace-wrapper.js

@@ -5,6 +5,19 @@ 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.
@@ -33,15 +46,21 @@ const experiment_mode_1 = require("./experiment-mode");
  * @returns An async function that accepts an `input`, executes `fn` inside a traced context, and returns `{ result, runId, span }`.
  */
 function wrapAgent(agentName, fn, options) {
-    const wrappedFunction = async function (input) {
+    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: {
-                "ai.agent.name": agentName,
-                "lemma.run_id": runId,
-                "lemma.is_experiment": (0, experiment_mode_1.isExperimentModeEnabled)() || options?.isExperiment === true,
-            },
+            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 });

package/dist/trace-wrapper.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uselemma/tracing",
-  "version": "2.12.1",
+  "version": "2.15.0",
   "description": "OpenTelemetry-based tracing module for Lemma",
   "license": "MIT",
   "author": "Lemma",