@fallom/trace 0.2.13 → 0.2.15

package/dist/index.d.mts

@@ -11,6 +11,10 @@ interface SessionContext {
     configKey: string;
     sessionId: string;
     customerId?: string;
+    /** Custom key-value metadata for filtering/grouping */
+    metadata?: Record<string, string | number | boolean>;
+    /** Simple string tags for quick filtering */
+    tags?: string[];
 }
 /**
  * Trace context for linking spans together.
@@ -42,6 +46,8 @@ interface TraceData {
     error_message?: string;
     time_to_first_token_ms?: number;
     is_streaming?: boolean;
+    metadata?: Record<string, string | number | boolean>;
+    tags?: string[];
     attributes?: Record<string, unknown>;
     prompt_key?: string;
     prompt_version?: number;
@@ -58,6 +64,18 @@ interface SessionOptions {
     sessionId: string;
     /** Optional customer/user identifier for analytics */
     customerId?: string;
+    /**
+     * Custom key-value metadata for filtering/grouping traces.
+     * Use this for structured data like deployment type, environment, etc.
+     * @example { deployment: "dedicated", requestType: "transcript", provider: "novita" }
+     */
+    metadata?: Record<string, string | number | boolean>;
+    /**
+     * Simple string tags for quick filtering.
+     * Use this for simple labels/categories.
+     * @example ["production", "dedicated", "transcript-analysis"]
+     */
+    tags?: string[];
 }
 /**
  * Options for wrapAISDK.

package/dist/index.d.ts

@@ -11,6 +11,10 @@ interface SessionContext {
     configKey: string;
     sessionId: string;
     customerId?: string;
+    /** Custom key-value metadata for filtering/grouping */
+    metadata?: Record<string, string | number | boolean>;
+    /** Simple string tags for quick filtering */
+    tags?: string[];
 }
 /**
  * Trace context for linking spans together.
@@ -42,6 +46,8 @@ interface TraceData {
     error_message?: string;
     time_to_first_token_ms?: number;
     is_streaming?: boolean;
+    metadata?: Record<string, string | number | boolean>;
+    tags?: string[];
     attributes?: Record<string, unknown>;
     prompt_key?: string;
     prompt_version?: number;
@@ -58,6 +64,18 @@ interface SessionOptions {
     sessionId: string;
     /** Optional customer/user identifier for analytics */
     customerId?: string;
+    /**
+     * Custom key-value metadata for filtering/grouping traces.
+     * Use this for structured data like deployment type, environment, etc.
+     * @example { deployment: "dedicated", requestType: "transcript", provider: "novita" }
+     */
+    metadata?: Record<string, string | number | boolean>;
+    /**
+     * Simple string tags for quick filtering.
+     * Use this for simple labels/categories.
+     * @example ["production", "dedicated", "transcript-analysis"]
+     */
+    tags?: string[];
 }
 /**
  * Options for wrapAISDK.

package/dist/index.js

@@ -2118,6 +2118,8 @@ function wrapOpenAI(client, sessionCtx) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -2143,6 +2145,8 @@ function wrapOpenAI(client, sessionCtx) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -2238,6 +2242,8 @@ function wrapAnthropic(client, sessionCtx) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -2263,6 +2269,8 @@ function wrapAnthropic(client, sessionCtx) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -2353,6 +2361,8 @@ function wrapGoogleAI(model, sessionCtx) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -2378,6 +2388,8 @@ function wrapGoogleAI(model, sessionCtx) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -2462,10 +2474,9 @@ function createGenerateTextWrapper(aiModule, sessionCtx, debug = false) {
       const result = await aiModule.generateText(wrappedParams);
       const endTime = Date.now();
       if (debug || isDebugMode()) {
-        console.log(
-          "\n\u{1F50D} [Fallom Debug] generateText raw result:",
-          JSON.stringify(result, null, 2)
-        );
+        console.log("\n\u{1F50D} [Fallom Debug] generateText result:");
+        console.log("   toolCalls:", result?.toolCalls?.length || 0);
+        console.log("   steps:", result?.steps?.length || 0);
       }
       const modelId = result?.response?.modelId || params?.model?.modelId || String(params?.model || "unknown");
       const attributes = {
@@ -2484,15 +2495,15 @@ function createGenerateTextWrapper(aiModule, sessionCtx, debug = false) {
         const mapToolCall = (tc) => ({
           toolCallId: tc?.toolCallId,
           toolName: tc?.toolName,
-          args: tc?.args,
-          // The actual arguments passed to the tool!
+          args: tc?.args ?? tc?.input,
+          // v4: args, v5: input
           type: tc?.type
         });
         const mapToolResult = (tr) => ({
           toolCallId: tr?.toolCallId,
           toolName: tr?.toolName,
-          result: tr?.result,
-          // The actual result from the tool!
+          result: tr?.result ?? tr?.output,
+          // v4: result, v5: output
           type: tr?.type
         });
         attributes["fallom.raw.response"] = JSON.stringify({
@@ -2628,6 +2639,8 @@ function createGenerateTextWrapper(aiModule, sessionCtx, debug = false) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -2654,6 +2667,8 @@ function createGenerateTextWrapper(aiModule, sessionCtx, debug = false) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -2801,15 +2816,15 @@ function createStreamTextWrapper(aiModule, sessionCtx, debug = false) {
             const mapToolCall = (tc) => ({
               toolCallId: tc?.toolCallId,
               toolName: tc?.toolName,
-              args: tc?.args,
-              // The actual arguments passed to the tool!
+              args: tc?.args ?? tc?.input,
+              // v4: args, v5: input
               type: tc?.type
             });
             const mapToolResult = (tr) => ({
               toolCallId: tr?.toolCallId,
               toolName: tr?.toolName,
-              result: tr?.result,
-              // The actual result from the tool!
+              result: tr?.result ?? tr?.output,
+              // v4: result, v5: output
               type: tr?.type
             });
             attributes["fallom.raw.request"] = JSON.stringify({
@@ -2929,6 +2944,8 @@ function createStreamTextWrapper(aiModule, sessionCtx, debug = false) {
             config_key: ctx.configKey,
             session_id: ctx.sessionId,
             customer_id: ctx.customerId,
+            metadata: ctx.metadata,
+            tags: ctx.tags,
             trace_id: traceId,
             span_id: spanId,
             parent_span_id: parentSpanId,
@@ -2957,6 +2974,8 @@ function createStreamTextWrapper(aiModule, sessionCtx, debug = false) {
           config_key: ctx.configKey,
           session_id: ctx.sessionId,
           customer_id: ctx.customerId,
+          metadata: ctx.metadata,
+          tags: ctx.tags,
           trace_id: traceId,
           span_id: spanId,
           parent_span_id: parentSpanId,
@@ -3058,6 +3077,8 @@ function createGenerateObjectWrapper(aiModule, sessionCtx, debug = false) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -3084,6 +3105,8 @@ function createGenerateObjectWrapper(aiModule, sessionCtx, debug = false) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -3173,6 +3196,8 @@ function createStreamObjectWrapper(aiModule, sessionCtx, debug = false) {
           config_key: ctx.configKey,
           session_id: ctx.sessionId,
           customer_id: ctx.customerId,
+          metadata: ctx.metadata,
+          tags: ctx.tags,
           trace_id: traceId,
           span_id: spanId,
           parent_span_id: parentSpanId,
@@ -3198,6 +3223,8 @@ function createStreamObjectWrapper(aiModule, sessionCtx, debug = false) {
           config_key: ctx.configKey,
           session_id: ctx.sessionId,
           customer_id: ctx.customerId,
+          metadata: ctx.metadata,
+          tags: ctx.tags,
           trace_id: traceId,
           span_id: spanId,
           parent_span_id: parentSpanId,
@@ -3264,6 +3291,8 @@ function wrapMastraAgent(agent, sessionCtx) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -3283,6 +3312,8 @@ function wrapMastraAgent(agent, sessionCtx) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -3312,7 +3343,9 @@ var FallomSession = class {
     this.ctx = {
       configKey: options.configKey,
       sessionId: options.sessionId,
-      customerId: options.customerId
+      customerId: options.customerId,
+      metadata: options.metadata,
+      tags: options.tags
     };
   }
   /** Get the session context. */
@@ -3363,6 +3396,8 @@ var FallomSession = class {
             config_key: ctx.configKey,
             session_id: ctx.sessionId,
             customer_id: ctx.customerId,
+            metadata: ctx.metadata,
+            tags: ctx.tags,
             trace_id: traceId,
             span_id: spanId,
             parent_span_id: traceCtx?.parentSpanId,
@@ -3387,6 +3422,8 @@ var FallomSession = class {
             config_key: ctx.configKey,
             session_id: ctx.sessionId,
             customer_id: ctx.customerId,
+            metadata: ctx.metadata,
+            tags: ctx.tags,
             trace_id: traceId,
             span_id: spanId,
             parent_span_id: traceCtx?.parentSpanId,
@@ -3420,6 +3457,8 @@ var FallomSession = class {
             config_key: ctx.configKey,
             session_id: ctx.sessionId,
             customer_id: ctx.customerId,
+            metadata: ctx.metadata,
+            tags: ctx.tags,
             trace_id: traceId,
             span_id: spanId,
             parent_span_id: traceCtx?.parentSpanId,
@@ -3444,6 +3483,8 @@ var FallomSession = class {
             config_key: ctx.configKey,
             session_id: ctx.sessionId,
             customer_id: ctx.customerId,
+            metadata: ctx.metadata,
+            tags: ctx.tags,
             trace_id: traceId,
             span_id: spanId,
             parent_span_id: traceCtx?.parentSpanId,

package/dist/index.mjs

@@ -1123,6 +1123,8 @@ function wrapOpenAI(client, sessionCtx) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -1148,6 +1150,8 @@ function wrapOpenAI(client, sessionCtx) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -1243,6 +1247,8 @@ function wrapAnthropic(client, sessionCtx) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -1268,6 +1274,8 @@ function wrapAnthropic(client, sessionCtx) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -1358,6 +1366,8 @@ function wrapGoogleAI(model, sessionCtx) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -1383,6 +1393,8 @@ function wrapGoogleAI(model, sessionCtx) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -1467,10 +1479,9 @@ function createGenerateTextWrapper(aiModule, sessionCtx, debug = false) {
       const result = await aiModule.generateText(wrappedParams);
       const endTime = Date.now();
       if (debug || isDebugMode()) {
-        console.log(
-          "\n\u{1F50D} [Fallom Debug] generateText raw result:",
-          JSON.stringify(result, null, 2)
-        );
+        console.log("\n\u{1F50D} [Fallom Debug] generateText result:");
+        console.log("   toolCalls:", result?.toolCalls?.length || 0);
+        console.log("   steps:", result?.steps?.length || 0);
       }
       const modelId = result?.response?.modelId || params?.model?.modelId || String(params?.model || "unknown");
       const attributes = {
@@ -1489,15 +1500,15 @@ function createGenerateTextWrapper(aiModule, sessionCtx, debug = false) {
         const mapToolCall = (tc) => ({
           toolCallId: tc?.toolCallId,
           toolName: tc?.toolName,
-          args: tc?.args,
-          // The actual arguments passed to the tool!
+          args: tc?.args ?? tc?.input,
+          // v4: args, v5: input
           type: tc?.type
         });
         const mapToolResult = (tr) => ({
           toolCallId: tr?.toolCallId,
           toolName: tr?.toolName,
-          result: tr?.result,
-          // The actual result from the tool!
+          result: tr?.result ?? tr?.output,
+          // v4: result, v5: output
           type: tr?.type
         });
         attributes["fallom.raw.response"] = JSON.stringify({
@@ -1633,6 +1644,8 @@ function createGenerateTextWrapper(aiModule, sessionCtx, debug = false) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -1659,6 +1672,8 @@ function createGenerateTextWrapper(aiModule, sessionCtx, debug = false) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -1806,15 +1821,15 @@ function createStreamTextWrapper(aiModule, sessionCtx, debug = false) {
             const mapToolCall = (tc) => ({
               toolCallId: tc?.toolCallId,
               toolName: tc?.toolName,
-              args: tc?.args,
-              // The actual arguments passed to the tool!
+              args: tc?.args ?? tc?.input,
+              // v4: args, v5: input
               type: tc?.type
             });
             const mapToolResult = (tr) => ({
               toolCallId: tr?.toolCallId,
               toolName: tr?.toolName,
-              result: tr?.result,
-              // The actual result from the tool!
+              result: tr?.result ?? tr?.output,
+              // v4: result, v5: output
               type: tr?.type
             });
             attributes["fallom.raw.request"] = JSON.stringify({
@@ -1934,6 +1949,8 @@ function createStreamTextWrapper(aiModule, sessionCtx, debug = false) {
             config_key: ctx.configKey,
             session_id: ctx.sessionId,
             customer_id: ctx.customerId,
+            metadata: ctx.metadata,
+            tags: ctx.tags,
             trace_id: traceId,
             span_id: spanId,
             parent_span_id: parentSpanId,
@@ -1962,6 +1979,8 @@ function createStreamTextWrapper(aiModule, sessionCtx, debug = false) {
           config_key: ctx.configKey,
           session_id: ctx.sessionId,
           customer_id: ctx.customerId,
+          metadata: ctx.metadata,
+          tags: ctx.tags,
           trace_id: traceId,
           span_id: spanId,
           parent_span_id: parentSpanId,
@@ -2063,6 +2082,8 @@ function createGenerateObjectWrapper(aiModule, sessionCtx, debug = false) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -2089,6 +2110,8 @@ function createGenerateObjectWrapper(aiModule, sessionCtx, debug = false) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -2178,6 +2201,8 @@ function createStreamObjectWrapper(aiModule, sessionCtx, debug = false) {
           config_key: ctx.configKey,
           session_id: ctx.sessionId,
           customer_id: ctx.customerId,
+          metadata: ctx.metadata,
+          tags: ctx.tags,
           trace_id: traceId,
           span_id: spanId,
           parent_span_id: parentSpanId,
@@ -2203,6 +2228,8 @@ function createStreamObjectWrapper(aiModule, sessionCtx, debug = false) {
           config_key: ctx.configKey,
           session_id: ctx.sessionId,
           customer_id: ctx.customerId,
+          metadata: ctx.metadata,
+          tags: ctx.tags,
           trace_id: traceId,
           span_id: spanId,
           parent_span_id: parentSpanId,
@@ -2269,6 +2296,8 @@ function wrapMastraAgent(agent, sessionCtx) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -2288,6 +2317,8 @@ function wrapMastraAgent(agent, sessionCtx) {
         config_key: ctx.configKey,
         session_id: ctx.sessionId,
         customer_id: ctx.customerId,
+        metadata: ctx.metadata,
+        tags: ctx.tags,
         trace_id: traceId,
         span_id: spanId,
         parent_span_id: parentSpanId,
@@ -2317,7 +2348,9 @@ var FallomSession = class {
     this.ctx = {
       configKey: options.configKey,
       sessionId: options.sessionId,
-      customerId: options.customerId
+      customerId: options.customerId,
+      metadata: options.metadata,
+      tags: options.tags
     };
   }
   /** Get the session context. */
@@ -2368,6 +2401,8 @@ var FallomSession = class {
             config_key: ctx.configKey,
             session_id: ctx.sessionId,
             customer_id: ctx.customerId,
+            metadata: ctx.metadata,
+            tags: ctx.tags,
             trace_id: traceId,
             span_id: spanId,
             parent_span_id: traceCtx?.parentSpanId,
@@ -2392,6 +2427,8 @@ var FallomSession = class {
             config_key: ctx.configKey,
             session_id: ctx.sessionId,
             customer_id: ctx.customerId,
+            metadata: ctx.metadata,
+            tags: ctx.tags,
             trace_id: traceId,
             span_id: spanId,
             parent_span_id: traceCtx?.parentSpanId,
@@ -2425,6 +2462,8 @@ var FallomSession = class {
             config_key: ctx.configKey,
             session_id: ctx.sessionId,
             customer_id: ctx.customerId,
+            metadata: ctx.metadata,
+            tags: ctx.tags,
             trace_id: traceId,
             span_id: spanId,
             parent_span_id: traceCtx?.parentSpanId,
@@ -2449,6 +2488,8 @@ var FallomSession = class {
             config_key: ctx.configKey,
             session_id: ctx.sessionId,
             customer_id: ctx.customerId,
+            metadata: ctx.metadata,
+            tags: ctx.tags,
             trace_id: traceId,
             span_id: spanId,
             parent_span_id: traceCtx?.parentSpanId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fallom/trace",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "Model A/B testing and tracing for LLM applications. Zero latency, production-ready.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",