@fallom/trace 0.1.10 → 0.1.12

package/dist/index.d.mts

@@ -1,3 +1,6 @@
+import { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { ExportResult } from '@opentelemetry/core';
+
 /**
  * Fallom tracing module.
  *
@@ -211,17 +214,50 @@ declare function wrapGoogleAI<T extends {
  * }); // Automatically traced!
  * ```
  */
+/** Options for wrapAISDK */
+interface WrapAISDKOptions {
+    /**
+     * Enable debug logging to see the raw Vercel AI SDK response structure.
+     * Useful for debugging missing usage/token data.
+     */
+    debug?: boolean;
+}
 declare function wrapAISDK<T extends {
     generateText: (...args: any[]) => Promise<any>;
     streamText: (...args: any[]) => any;
     generateObject?: (...args: any[]) => Promise<any>;
     streamObject?: (...args: any[]) => any;
-}>(ai: T): {
+}>(ai: T, options?: WrapAISDKOptions): {
     generateText: T["generateText"];
     streamText: T["streamText"];
     generateObject: T["generateObject"];
     streamObject: T["streamObject"];
 };
+/**
+ * Wrap a Mastra agent to automatically trace all generate() calls.
+ *
+ * @param agent - The Mastra Agent instance
+ * @returns The same agent with tracing enabled
+ *
+ * @example
+ * ```typescript
+ * import { trace } from "@fallom/trace";
+ * import { Agent } from "@mastra/core";
+ *
+ * await trace.init({ apiKey: "your-key" });
+ *
+ * const agent = new Agent({ ... });
+ * const tracedAgent = trace.wrapMastraAgent(agent);
+ *
+ * trace.setSession("my-app", "session-123", "user-456");
+ * const result = await tracedAgent.generate([{ role: "user", content: "Hello" }]);
+ * // ^ Automatically traced!
+ * ```
+ */
+declare function wrapMastraAgent<T extends {
+    generate: (...args: any[]) => Promise<any>;
+    name?: string;
+}>(agent: T): T;
 
 declare const trace_clearSession: typeof clearSession;
 declare const trace_getSession: typeof getSession;
@@ -232,9 +268,10 @@ declare const trace_span: typeof span;
 declare const trace_wrapAISDK: typeof wrapAISDK;
 declare const trace_wrapAnthropic: typeof wrapAnthropic;
 declare const trace_wrapGoogleAI: typeof wrapGoogleAI;
+declare const trace_wrapMastraAgent: typeof wrapMastraAgent;
 declare const trace_wrapOpenAI: typeof wrapOpenAI;
 declare namespace trace {
-  export { trace_clearSession as clearSession, trace_getSession as getSession, init$3 as init, trace_runWithSession as runWithSession, trace_setSession as setSession, trace_shutdown as shutdown, trace_span as span, trace_wrapAISDK as wrapAISDK, trace_wrapAnthropic as wrapAnthropic, trace_wrapGoogleAI as wrapGoogleAI, trace_wrapOpenAI as wrapOpenAI };
+  export { trace_clearSession as clearSession, trace_getSession as getSession, init$3 as init, trace_runWithSession as runWithSession, trace_setSession as setSession, trace_shutdown as shutdown, trace_span as span, trace_wrapAISDK as wrapAISDK, trace_wrapAnthropic as wrapAnthropic, trace_wrapGoogleAI as wrapGoogleAI, trace_wrapMastraAgent as wrapMastraAgent, trace_wrapOpenAI as wrapOpenAI };
 }
 
 /**
@@ -444,6 +481,112 @@ interface InitOptions {
  */
 declare function init(options?: InitOptions): Promise<void>;
 
+/**
+ * Fallom Exporter for Mastra
+ *
+ * Custom OpenTelemetry exporter that sends traces from Mastra agents to Fallom.
+ * Reads session context from the shared trace module (set via trace.setSession()).
+ *
+ * Usage with Mastra:
+ * ```typescript
+ * import { trace, FallomExporter } from "@fallom/trace";
+ * import { Mastra } from "@mastra/core/mastra";
+ *
+ * // Initialize trace module
+ * await trace.init({ apiKey: process.env.FALLOM_API_KEY });
+ *
+ * // Create Mastra with Fallom exporter
+ * const mastra = new Mastra({
+ *   agents: { myAgent },
+ *   telemetry: {
+ *     serviceName: "my-agent",
+ *     enabled: true,
+ *     export: {
+ *       type: "custom",
+ *       exporter: new FallomExporter(),
+ *     },
+ *   },
+ * });
+ *
+ * // In your request handler:
+ * trace.setSession("my-app", "session-123", "user-456");
+ * const result = await mastra.getAgent("myAgent").generate("Hello!");
+ * ```
+ */
+
+interface FallomExporterOptions {
+    /** Fallom API key. Defaults to FALLOM_API_KEY env var. */
+    apiKey?: string;
+    /** Base URL for traces endpoint (defaults to https://traces.fallom.com) */
+    baseUrl?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Set prompt tracking info.
+ * Call this after prompts.get() to track which prompt was used.
+ */
+declare function setMastraPrompt(promptKey: string, version?: number): void;
+/**
+ * Set A/B test prompt tracking info.
+ * Call this after prompts.getAB() to track which variant was used.
+ */
+declare function setMastraPromptAB(abTestKey: string, variantIndex: number): void;
+/**
+ * Clear prompt tracking info.
+ */
+declare function clearMastraPrompt(): void;
+/**
+ * OpenTelemetry SpanExporter that sends traces to Fallom.
+ *
+ * Reads session context from trace.setSession() automatically.
+ * Compatible with Mastra's custom exporter interface.
+ */
+declare class FallomExporter implements SpanExporter {
+    private apiKey;
+    private baseUrl;
+    private debug;
+    private pendingExports;
+    constructor(options?: FallomExporterOptions);
+    private log;
+    /**
+     * Export spans to Fallom.
+     */
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    /**
+     * Shutdown the exporter, waiting for pending exports.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Force flush pending exports.
+     */
+    forceFlush(): Promise<void>;
+    /**
+     * Send spans to Fallom's OTLP endpoint.
+     */
+    private sendSpans;
+    /**
+     * Convert OpenTelemetry spans to OTLP JSON format.
+     */
+    private spansToOtlpJson;
+    /**
+     * Convert a single span to OTLP format.
+     */
+    private spanToOtlp;
+    /**
+     * Convert attributes to OTLP format.
+     */
+    private attributesToOtlp;
+    /**
+     * Convert a value to OTLP AnyValue format.
+     */
+    private valueToOtlp;
+    /**
+     * Convert HrTime to nanoseconds string.
+     */
+    private hrTimeToNanos;
+}
+
 /**
  * Fallom - Model A/B testing, prompt management, and tracing for LLM applications.
  *
@@ -488,4 +631,4 @@ declare const _default: {
     prompts: typeof prompts;
 };
 
-export { type InitOptions, type PromptResult, _default as default, init, models, prompts, trace };
+export { FallomExporter, type FallomExporterOptions, type InitOptions, type PromptResult, clearMastraPrompt, _default as default, init, models, prompts, setMastraPrompt, setMastraPromptAB, trace };

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+import { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { ExportResult } from '@opentelemetry/core';
+
 /**
  * Fallom tracing module.
  *
@@ -211,17 +214,50 @@ declare function wrapGoogleAI<T extends {
  * }); // Automatically traced!
  * ```
  */
+/** Options for wrapAISDK */
+interface WrapAISDKOptions {
+    /**
+     * Enable debug logging to see the raw Vercel AI SDK response structure.
+     * Useful for debugging missing usage/token data.
+     */
+    debug?: boolean;
+}
 declare function wrapAISDK<T extends {
     generateText: (...args: any[]) => Promise<any>;
     streamText: (...args: any[]) => any;
     generateObject?: (...args: any[]) => Promise<any>;
     streamObject?: (...args: any[]) => any;
-}>(ai: T): {
+}>(ai: T, options?: WrapAISDKOptions): {
     generateText: T["generateText"];
     streamText: T["streamText"];
     generateObject: T["generateObject"];
     streamObject: T["streamObject"];
 };
+/**
+ * Wrap a Mastra agent to automatically trace all generate() calls.
+ *
+ * @param agent - The Mastra Agent instance
+ * @returns The same agent with tracing enabled
+ *
+ * @example
+ * ```typescript
+ * import { trace } from "@fallom/trace";
+ * import { Agent } from "@mastra/core";
+ *
+ * await trace.init({ apiKey: "your-key" });
+ *
+ * const agent = new Agent({ ... });
+ * const tracedAgent = trace.wrapMastraAgent(agent);
+ *
+ * trace.setSession("my-app", "session-123", "user-456");
+ * const result = await tracedAgent.generate([{ role: "user", content: "Hello" }]);
+ * // ^ Automatically traced!
+ * ```
+ */
+declare function wrapMastraAgent<T extends {
+    generate: (...args: any[]) => Promise<any>;
+    name?: string;
+}>(agent: T): T;
 
 declare const trace_clearSession: typeof clearSession;
 declare const trace_getSession: typeof getSession;
@@ -232,9 +268,10 @@ declare const trace_span: typeof span;
 declare const trace_wrapAISDK: typeof wrapAISDK;
 declare const trace_wrapAnthropic: typeof wrapAnthropic;
 declare const trace_wrapGoogleAI: typeof wrapGoogleAI;
+declare const trace_wrapMastraAgent: typeof wrapMastraAgent;
 declare const trace_wrapOpenAI: typeof wrapOpenAI;
 declare namespace trace {
-  export { trace_clearSession as clearSession, trace_getSession as getSession, init$3 as init, trace_runWithSession as runWithSession, trace_setSession as setSession, trace_shutdown as shutdown, trace_span as span, trace_wrapAISDK as wrapAISDK, trace_wrapAnthropic as wrapAnthropic, trace_wrapGoogleAI as wrapGoogleAI, trace_wrapOpenAI as wrapOpenAI };
+  export { trace_clearSession as clearSession, trace_getSession as getSession, init$3 as init, trace_runWithSession as runWithSession, trace_setSession as setSession, trace_shutdown as shutdown, trace_span as span, trace_wrapAISDK as wrapAISDK, trace_wrapAnthropic as wrapAnthropic, trace_wrapGoogleAI as wrapGoogleAI, trace_wrapMastraAgent as wrapMastraAgent, trace_wrapOpenAI as wrapOpenAI };
 }
 
 /**
@@ -444,6 +481,112 @@ interface InitOptions {
  */
 declare function init(options?: InitOptions): Promise<void>;
 
+/**
+ * Fallom Exporter for Mastra
+ *
+ * Custom OpenTelemetry exporter that sends traces from Mastra agents to Fallom.
+ * Reads session context from the shared trace module (set via trace.setSession()).
+ *
+ * Usage with Mastra:
+ * ```typescript
+ * import { trace, FallomExporter } from "@fallom/trace";
+ * import { Mastra } from "@mastra/core/mastra";
+ *
+ * // Initialize trace module
+ * await trace.init({ apiKey: process.env.FALLOM_API_KEY });
+ *
+ * // Create Mastra with Fallom exporter
+ * const mastra = new Mastra({
+ *   agents: { myAgent },
+ *   telemetry: {
+ *     serviceName: "my-agent",
+ *     enabled: true,
+ *     export: {
+ *       type: "custom",
+ *       exporter: new FallomExporter(),
+ *     },
+ *   },
+ * });
+ *
+ * // In your request handler:
+ * trace.setSession("my-app", "session-123", "user-456");
+ * const result = await mastra.getAgent("myAgent").generate("Hello!");
+ * ```
+ */
+
+interface FallomExporterOptions {
+    /** Fallom API key. Defaults to FALLOM_API_KEY env var. */
+    apiKey?: string;
+    /** Base URL for traces endpoint (defaults to https://traces.fallom.com) */
+    baseUrl?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Set prompt tracking info.
+ * Call this after prompts.get() to track which prompt was used.
+ */
+declare function setMastraPrompt(promptKey: string, version?: number): void;
+/**
+ * Set A/B test prompt tracking info.
+ * Call this after prompts.getAB() to track which variant was used.
+ */
+declare function setMastraPromptAB(abTestKey: string, variantIndex: number): void;
+/**
+ * Clear prompt tracking info.
+ */
+declare function clearMastraPrompt(): void;
+/**
+ * OpenTelemetry SpanExporter that sends traces to Fallom.
+ *
+ * Reads session context from trace.setSession() automatically.
+ * Compatible with Mastra's custom exporter interface.
+ */
+declare class FallomExporter implements SpanExporter {
+    private apiKey;
+    private baseUrl;
+    private debug;
+    private pendingExports;
+    constructor(options?: FallomExporterOptions);
+    private log;
+    /**
+     * Export spans to Fallom.
+     */
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    /**
+     * Shutdown the exporter, waiting for pending exports.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Force flush pending exports.
+     */
+    forceFlush(): Promise<void>;
+    /**
+     * Send spans to Fallom's OTLP endpoint.
+     */
+    private sendSpans;
+    /**
+     * Convert OpenTelemetry spans to OTLP JSON format.
+     */
+    private spansToOtlpJson;
+    /**
+     * Convert a single span to OTLP format.
+     */
+    private spanToOtlp;
+    /**
+     * Convert attributes to OTLP format.
+     */
+    private attributesToOtlp;
+    /**
+     * Convert a value to OTLP AnyValue format.
+     */
+    private valueToOtlp;
+    /**
+     * Convert HrTime to nanoseconds string.
+     */
+    private hrTimeToNanos;
+}
+
 /**
  * Fallom - Model A/B testing, prompt management, and tracing for LLM applications.
  *
@@ -488,4 +631,4 @@ declare const _default: {
     prompts: typeof prompts;
 };
 
-export { type InitOptions, type PromptResult, _default as default, init, models, prompts, trace };
+export { FallomExporter, type FallomExporterOptions, type InitOptions, type PromptResult, clearMastraPrompt, _default as default, init, models, prompts, setMastraPrompt, setMastraPromptAB, trace };