@fallom/trace 0.1.6 → 0.1.11

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.
  *
@@ -183,6 +186,70 @@ declare function wrapAnthropic<T extends {
 declare function wrapGoogleAI<T extends {
     generateContent: (...args: any[]) => Promise<any>;
 }>(model: T): T;
+/**
+ * Wrap the Vercel AI SDK to automatically trace all LLM calls.
+ * Works with generateText, streamText, generateObject, streamObject.
+ *
+ * @param ai - The ai module (import * as ai from "ai")
+ * @returns Object with wrapped generateText, streamText, generateObject, streamObject
+ *
+ * @example
+ * ```typescript
+ * import * as ai from "ai";
+ * import { createOpenAI } from "@ai-sdk/openai";
+ * import { trace } from "@fallom/trace";
+ *
+ * await trace.init({ apiKey: process.env.FALLOM_API_KEY });
+ * const { generateText, streamText } = trace.wrapAISDK(ai);
+ *
+ * const openrouter = createOpenAI({
+ *   apiKey: process.env.OPENROUTER_API_KEY,
+ *   baseURL: "https://openrouter.ai/api/v1",
+ * });
+ *
+ * trace.setSession("my-config", sessionId);
+ * const { text } = await generateText({
+ *   model: openrouter("openai/gpt-4o-mini"),
+ *   prompt: "Hello!",
+ * }); // Automatically traced!
+ * ```
+ */
+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): {
+    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;
@@ -190,11 +257,13 @@ declare const trace_runWithSession: typeof runWithSession;
 declare const trace_setSession: typeof setSession;
 declare const trace_shutdown: typeof shutdown;
 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_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 };
 }
 
 /**
@@ -368,16 +437,20 @@ declare namespace prompts {
  */
 interface InitOptions {
     apiKey?: string;
-    baseUrl?: string;
+    tracesUrl?: string;
+    configsUrl?: string;
+    promptsUrl?: string;
     captureContent?: boolean;
     debug?: boolean;
 }
 /**
- * Initialize both trace and models at once.
+ * Initialize trace, models, and prompts at once.
  *
  * @param options - Configuration options
  * @param options.apiKey - Your Fallom API key. Defaults to FALLOM_API_KEY env var.
- * @param options.baseUrl - API base URL. Defaults to FALLOM_BASE_URL or https://spans.fallom.com
+ * @param options.tracesUrl - Traces API URL. Defaults to FALLOM_TRACES_URL or https://traces.fallom.com
+ * @param options.configsUrl - Configs API URL. Defaults to FALLOM_CONFIGS_URL or https://configs.fallom.com
+ * @param options.promptsUrl - Prompts API URL. Defaults to FALLOM_PROMPTS_URL or https://prompts.fallom.com
  * @param options.captureContent - Whether to capture prompt/completion content (default: true)
  *
  * @example
@@ -388,7 +461,11 @@ interface InitOptions {
  * fallom.init({ apiKey: "your-api-key" });
  *
  * // Local development
- * fallom.init({ baseUrl: "http://localhost:8001" });
+ * fallom.init({
+ *   tracesUrl: "http://localhost:3002",
+ *   configsUrl: "http://localhost:3003",
+ *   promptsUrl: "http://localhost:3004"
+ * });
  *
  * // Privacy mode
  * fallom.init({ captureContent: false });
@@ -396,6 +473,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.
  *
@@ -440,4 +623,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.
  *
@@ -183,6 +186,70 @@ declare function wrapAnthropic<T extends {
 declare function wrapGoogleAI<T extends {
     generateContent: (...args: any[]) => Promise<any>;
 }>(model: T): T;
+/**
+ * Wrap the Vercel AI SDK to automatically trace all LLM calls.
+ * Works with generateText, streamText, generateObject, streamObject.
+ *
+ * @param ai - The ai module (import * as ai from "ai")
+ * @returns Object with wrapped generateText, streamText, generateObject, streamObject
+ *
+ * @example
+ * ```typescript
+ * import * as ai from "ai";
+ * import { createOpenAI } from "@ai-sdk/openai";
+ * import { trace } from "@fallom/trace";
+ *
+ * await trace.init({ apiKey: process.env.FALLOM_API_KEY });
+ * const { generateText, streamText } = trace.wrapAISDK(ai);
+ *
+ * const openrouter = createOpenAI({
+ *   apiKey: process.env.OPENROUTER_API_KEY,
+ *   baseURL: "https://openrouter.ai/api/v1",
+ * });
+ *
+ * trace.setSession("my-config", sessionId);
+ * const { text } = await generateText({
+ *   model: openrouter("openai/gpt-4o-mini"),
+ *   prompt: "Hello!",
+ * }); // Automatically traced!
+ * ```
+ */
+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): {
+    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;
@@ -190,11 +257,13 @@ declare const trace_runWithSession: typeof runWithSession;
 declare const trace_setSession: typeof setSession;
 declare const trace_shutdown: typeof shutdown;
 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_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 };
 }
 
 /**
@@ -368,16 +437,20 @@ declare namespace prompts {
  */
 interface InitOptions {
     apiKey?: string;
-    baseUrl?: string;
+    tracesUrl?: string;
+    configsUrl?: string;
+    promptsUrl?: string;
     captureContent?: boolean;
     debug?: boolean;
 }
 /**
- * Initialize both trace and models at once.
+ * Initialize trace, models, and prompts at once.
  *
  * @param options - Configuration options
  * @param options.apiKey - Your Fallom API key. Defaults to FALLOM_API_KEY env var.
- * @param options.baseUrl - API base URL. Defaults to FALLOM_BASE_URL or https://spans.fallom.com
+ * @param options.tracesUrl - Traces API URL. Defaults to FALLOM_TRACES_URL or https://traces.fallom.com
+ * @param options.configsUrl - Configs API URL. Defaults to FALLOM_CONFIGS_URL or https://configs.fallom.com
+ * @param options.promptsUrl - Prompts API URL. Defaults to FALLOM_PROMPTS_URL or https://prompts.fallom.com
  * @param options.captureContent - Whether to capture prompt/completion content (default: true)
  *
  * @example
@@ -388,7 +461,11 @@ interface InitOptions {
  * fallom.init({ apiKey: "your-api-key" });
  *
  * // Local development
- * fallom.init({ baseUrl: "http://localhost:8001" });
+ * fallom.init({
+ *   tracesUrl: "http://localhost:3002",
+ *   configsUrl: "http://localhost:3003",
+ *   promptsUrl: "http://localhost:3004"
+ * });
  *
  * // Privacy mode
  * fallom.init({ captureContent: false });
@@ -396,6 +473,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.
  *
@@ -440,4 +623,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 };