@mastra/langfuse 0.0.0-stream-vnext-usage-20250908171242 → 0.0.0-testing-cloud-studios-20260114234039

package/README.md

@@ -10,22 +10,54 @@ npm install @mastra/langfuse
 
 ## Usage
 
+### Zero-Config Setup
+
+The exporter automatically reads credentials from environment variables:
+
+```bash
+# Required
+LANGFUSE_PUBLIC_KEY=pk-lf-...
+LANGFUSE_SECRET_KEY=sk-lf-...
+
+# Optional - defaults to Langfuse cloud
+LANGFUSE_BASE_URL=https://cloud.langfuse.com
+```
+
 ```typescript
 import { LangfuseExporter } from '@mastra/langfuse';
 
-// Use with Mastra
 const mastra = new Mastra({
   ...,
   observability: {
-    instances: {
+    configs: {
       langfuse: {
-        serviceName: 'service',
+        serviceName: 'my-service',
+        exporters: [new LangfuseExporter()],
+      },
+    },
+  },
+});
+```
+
+### Explicit Configuration
+
+You can also pass credentials directly:
+
+```typescript
+import { LangfuseExporter } from '@mastra/langfuse';
+
+const mastra = new Mastra({
+  ...,
+  observability: {
+    configs: {
+      langfuse: {
+        serviceName: 'my-service',
         exporters: [
           new LangfuseExporter({
-            publicKey: process.env.LANGFUSE_PUBLIC_KEY,
-            secretKey: process.env.LANGFUSE_SECRET_KEY,
-            baseUrl: process.env.LANGFUSE_BASE_URL, // Optional - defaults to Langfuse cloud
-            realtime: true,
+            publicKey: 'pk-lf-...',
+            secretKey: 'sk-lf-...',
+            baseUrl: 'https://cloud.langfuse.com', // Optional
+            realtime: true, // Optional - flush after each event
           }),
         ],
       },
@@ -34,16 +66,22 @@ const mastra = new Mastra({
 });
 ```
 
+### Configuration Options
+
+| Option      | Type      | Description                                                                  |
+| ----------- | --------- | ---------------------------------------------------------------------------- |
+| `publicKey` | `string`  | Langfuse public key. Defaults to `LANGFUSE_PUBLIC_KEY` env var               |
+| `secretKey` | `string`  | Langfuse secret key. Defaults to `LANGFUSE_SECRET_KEY` env var               |
+| `baseUrl`   | `string`  | Langfuse host URL. Defaults to `LANGFUSE_BASE_URL` env var or Langfuse cloud |
+| `realtime`  | `boolean` | Flush after each event for immediate visibility. Defaults to `false`         |
+| `options`   | `object`  | Additional options to pass to the Langfuse client                            |
+
 ## Features
 
-### AI Tracing
+### Tracing
 
 - **Automatic span mapping**: Root spans become Langfuse traces
-- **LLM generation support**: `LLM_GENERATION` spans become Langfuse generations with token usage
+- **Model generation support**: `MODEL_GENERATION` spans become Langfuse generations with token usage
 - **Type-specific metadata**: Extracts relevant metadata for each span type (agents, tools, workflows)
 - **Error tracking**: Automatic error status and message tracking
 - **Hierarchical traces**: Maintains parent-child relationships
-
-## License
-
-Apache 2.0

package/dist/helpers.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Langfuse Tracing Options Helpers
+ *
+ * These helpers integrate with the `buildTracingOptions` pattern from
+ * `@mastra/observability` to add Langfuse-specific tracing features.
+ *
+ * @example
+ * ```typescript
+ * import { buildTracingOptions } from '@mastra/observability';
+ * import { withLangfusePrompt } from '@mastra/langfuse';
+ *
+ * const prompt = await langfuse.getPrompt('my-prompt');
+ *
+ * const agent = new Agent({
+ *   defaultGenerateOptions: {
+ *     tracingOptions: buildTracingOptions(withLangfusePrompt(prompt)),
+ *   },
+ * });
+ * ```
+ */
+import type { TracingOptionsUpdater } from '@mastra/observability';
+/**
+ * Langfuse prompt input - accepts either a Langfuse SDK prompt object
+ * or manual fields.
+ */
+export interface LangfusePromptInput {
+    /** Prompt name */
+    name?: string;
+    /** Prompt version */
+    version?: number;
+    /** Prompt UUID */
+    id?: string;
+}
+/**
+ * Adds Langfuse prompt metadata to the tracing options
+ * to enable Langfuse Prompt Tracing.
+ *
+ * The metadata is added under `metadata.langfuse.prompt` and includes:
+ * - `name` - Prompt name
+ * - `version` - Prompt version
+ * - `id` - Prompt UUID
+ *
+ * All fields are deeply merged with any existing metadata.
+ *
+ * @param prompt - A Langfuse prompt object (from `langfuse.getPrompt()`) or manual fields
+ * @returns A TracingOptionsUpdater function for use with `buildTracingOptions`
+ *
+ * @example
+ * ```typescript
+ * import { buildTracingOptions } from '@mastra/observability';
+ * import { withLangfusePrompt } from '@mastra/langfuse';
+ * import { Langfuse } from 'langfuse';
+ *
+ * const langfuse = new Langfuse();
+ * const prompt = await langfuse.getPrompt('customer-support');
+ *
+ * // Use with buildTracingOptions
+ * const tracingOptions = buildTracingOptions(
+ *   withLangfusePrompt(prompt),
+ * );
+ *
+ * // Or directly in agent config
+ * const agent = new Agent({
+ *   name: 'support-agent',
+ *   instructions: prompt.prompt,
+ *   model: openai('gpt-4o'),
+ *   defaultGenerateOptions: {
+ *     tracingOptions: buildTracingOptions(withLangfusePrompt(prompt)),
+ *   },
+ * });
+ *
+ * // Manual fields also work
+ * const tracingOptions = buildTracingOptions(
+ *   withLangfusePrompt({ name: 'my-prompt', version: 1 }),
+ * );
+ * ```
+ */
+export declare function withLangfusePrompt(prompt: LangfusePromptInput): TracingOptionsUpdater;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAEnE;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,kBAAkB;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qBAAqB;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kBAAkB;IAClB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,mBAAmB,GAAG,qBAAqB,CAerF"}

package/dist/index.cjs

@@ -1,51 +1,79 @@
 'use strict';
 
-var aiTracing = require('@mastra/core/ai-tracing');
-var logger = require('@mastra/core/logger');
+var observability$1 = require('@mastra/core/observability');
+var utils = require('@mastra/core/utils');
+var observability = require('@mastra/observability');
 var langfuse = require('langfuse');
 
-// src/ai-tracing.ts
-var LangfuseExporter = class {
+// src/tracing.ts
+function formatUsageMetrics(usage) {
+  if (!usage) return {};
+  const metrics = {};
+  if (usage.inputTokens !== void 0) {
+    metrics.input = usage.inputTokens;
+    if (usage.inputDetails?.cacheWrite !== void 0) {
+      metrics.cache_write_input_tokens = usage.inputDetails.cacheWrite;
+      metrics.input -= metrics.cache_write_input_tokens;
+    }
+  }
+  if (usage.inputDetails?.cacheRead !== void 0) {
+    metrics.cache_read_input_tokens = usage.inputDetails.cacheRead;
+  }
+  if (usage.outputTokens !== void 0) {
+    metrics.output = usage.outputTokens;
+  }
+  if (usage.outputDetails?.reasoning !== void 0) {
+    metrics.reasoning = usage.outputDetails.reasoning;
+  }
+  if (metrics.input && metrics.output) {
+    metrics.total = metrics.input + metrics.output;
+    if (metrics.cache_write_input_tokens) {
+      metrics.total += metrics.cache_write_input_tokens;
+    }
+  }
+  return metrics;
+}
+var LangfuseExporter = class extends observability.BaseExporter {
   name = "langfuse";
   client;
   realtime;
   traceMap = /* @__PURE__ */ new Map();
-  logger;
-  constructor(config) {
+  constructor(config = {}) {
+    super(config);
     this.realtime = config.realtime ?? false;
-    this.logger = new logger.ConsoleLogger({ level: config.logLevel ?? "warn" });
-    if (!config.publicKey || !config.secretKey) {
-      this.logger.error("LangfuseExporter: Missing required credentials, exporter will be disabled", {
-        hasPublicKey: !!config.publicKey,
-        hasSecretKey: !!config.secretKey
-      });
+    const publicKey = config.publicKey ?? process.env.LANGFUSE_PUBLIC_KEY;
+    const secretKey = config.secretKey ?? process.env.LANGFUSE_SECRET_KEY;
+    const baseUrl = config.baseUrl ?? process.env.LANGFUSE_BASE_URL;
+    if (!publicKey || !secretKey) {
+      const publicKeySource = config.publicKey ? "from config" : process.env.LANGFUSE_PUBLIC_KEY ? "from env" : "missing";
+      const secretKeySource = config.secretKey ? "from config" : process.env.LANGFUSE_SECRET_KEY ? "from env" : "missing";
+      this.setDisabled(
+        `Missing required credentials (publicKey: ${publicKeySource}, secretKey: ${secretKeySource}). Set LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY environment variables or pass them in config.`
+      );
       this.client = null;
       return;
     }
     this.client = new langfuse.Langfuse({
-      publicKey: config.publicKey,
-      secretKey: config.secretKey,
-      baseUrl: config.baseUrl,
+      publicKey,
+      secretKey,
+      baseUrl,
       ...config.options
     });
   }
-  async exportEvent(event) {
-    if (!this.client) {
-      return;
-    }
-    if (event.span.isEvent) {
-      await this.handleEventSpan(event.span);
+  async _exportTracingEvent(event) {
+    if (event.exportedSpan.isEvent) {
+      await this.handleEventSpan(event.exportedSpan);
       return;
     }
     switch (event.type) {
       case "span_started":
-        await this.handleSpanStarted(event.span);
+        await this.handleSpanStarted(event.exportedSpan);
         break;
       case "span_updated":
-        await this.handleSpanUpdateOrEnd(event.span, false);
+        await this.handleSpanUpdateOrEnd(event.exportedSpan, false);
         break;
       case "span_ended":
-        await this.handleSpanUpdateOrEnd(event.span, true);
+        await this.handleSpanUpdateOrEnd(event.exportedSpan, true);
         break;
     }
     if (this.realtime) {
@@ -61,13 +89,21 @@ var LangfuseExporter = class {
     if (!traceData) {
       return;
     }
+    if (!span.isRootSpan) {
+      const langfuseData = span.metadata?.langfuse;
+      traceData.spanMetadata.set(span.id, {
+        parentSpanId: span.parentSpanId,
+        langfusePrompt: langfuseData?.prompt
+      });
+    }
     const langfuseParent = this.getLangfuseParent({ traceData, span, method });
     if (!langfuseParent) {
       return;
     }
-    const payload = this.buildSpanPayload(span, true);
-    const langfuseSpan = span.type === aiTracing.AISpanType.LLM_GENERATION ? langfuseParent.generation(payload) : langfuseParent.span(payload);
+    const payload = this.buildSpanPayload(span, true, traceData);
+    const langfuseSpan = span.type === observability$1.SpanType.MODEL_GENERATION ? langfuseParent.generation(payload) : langfuseParent.span(payload);
     traceData.spans.set(span.id, langfuseSpan);
+    traceData.activeSpans.add(span.id);
   }
   async handleSpanUpdateOrEnd(span, isEnd) {
     const method = isEnd ? "handleSpanEnd" : "handleSpanUpdate";
@@ -77,21 +113,33 @@ var LangfuseExporter = class {
     }
     const langfuseSpan = traceData.spans.get(span.id);
     if (!langfuseSpan) {
+      if (isEnd && span.isEvent) {
+        traceData.activeSpans.delete(span.id);
+        if (traceData.activeSpans.size === 0) {
+          this.traceMap.delete(span.traceId);
+        }
+        return;
+      }
       this.logger.warn("Langfuse exporter: No Langfuse span found for span update/end", {
         traceId: span.traceId,
         spanId: span.id,
         spanName: span.name,
         spanType: span.type,
         isRootSpan: span.isRootSpan,
-        parentSpanId: span.parent?.id,
+        parentSpanId: span.parentSpanId,
         method
       });
       return;
     }
-    langfuseSpan.update(this.buildSpanPayload(span, false));
-    if (isEnd && span.isRootSpan) {
-      traceData.trace.update({ output: span.output });
-      this.traceMap.delete(span.traceId);
+    langfuseSpan.update(this.buildSpanPayload(span, false, traceData));
+    if (isEnd) {
+      traceData.activeSpans.delete(span.id);
+      if (span.isRootSpan) {
+        traceData.trace.update({ output: span.output });
+      }
+      if (traceData.activeSpans.size === 0) {
+        this.traceMap.delete(span.traceId);
+      }
     }
   }
   async handleEventSpan(span) {
@@ -113,13 +161,37 @@ var LangfuseExporter = class {
     if (!langfuseParent) {
       return;
     }
-    const payload = this.buildSpanPayload(span, true);
+    const payload = this.buildSpanPayload(span, true, traceData);
     const langfuseEvent = langfuseParent.event(payload);
     traceData.events.set(span.id, langfuseEvent);
+    if (!span.endTime) {
+      traceData.activeSpans.add(span.id);
+    }
   }
   initTrace(span) {
+    if (this.traceMap.has(span.traceId)) {
+      this.logger.debug("Langfuse exporter: Reusing existing trace from local map", {
+        traceId: span.traceId,
+        spanId: span.id,
+        spanName: span.name
+      });
+      return;
+    }
     const trace = this.client.trace(this.buildTracePayload(span));
-    this.traceMap.set(span.traceId, { trace, spans: /* @__PURE__ */ new Map(), events: /* @__PURE__ */ new Map() });
+    const langfuseData = span.metadata?.langfuse;
+    const spanMetadata = /* @__PURE__ */ new Map();
+    spanMetadata.set(span.id, {
+      parentSpanId: void 0,
+      langfusePrompt: langfuseData?.prompt
+    });
+    this.traceMap.set(span.traceId, {
+      trace,
+      spans: /* @__PURE__ */ new Map(),
+      spanMetadata,
+      events: /* @__PURE__ */ new Map(),
+      activeSpans: /* @__PURE__ */ new Set(),
+      rootSpanId: span.id
+    });
   }
   getTraceData(options) {
     const { span, method } = options;
@@ -132,13 +204,13 @@ var LangfuseExporter = class {
       spanName: span.name,
       spanType: span.type,
       isRootSpan: span.isRootSpan,
-      parentSpanId: span.parent?.id,
+      parentSpanId: span.parentSpanId,
       method
     });
   }
   getLangfuseParent(options) {
     const { traceData, span, method } = options;
-    const parentId = span.parent?.id;
+    const parentId = span.parentSpanId;
     if (!parentId) {
       return traceData.trace;
     }
@@ -154,7 +226,7 @@ var LangfuseExporter = class {
       spanName: span.name,
       spanType: span.type,
       isRootSpan: span.isRootSpan,
-      parentSpanId: span.parent?.id,
+      parentSpanId: span.parentSpanId,
       method
     });
   }
@@ -167,6 +239,7 @@ var LangfuseExporter = class {
     if (userId) payload.userId = userId;
     if (sessionId) payload.sessionId = sessionId;
     if (span.input) payload.input = span.input;
+    if (span.tags?.length) payload.tags = span.tags;
     payload.metadata = {
       spanType: span.type,
       ...span.attributes,
@@ -174,7 +247,23 @@ var LangfuseExporter = class {
     };
     return payload;
   }
-  buildSpanPayload(span, isCreate) {
+  /**
+   * Look up the Langfuse prompt from the closest parent span that has one.
+   * This enables prompt inheritance for MODEL_GENERATION spans when the prompt
+   * is set on a parent span (e.g., AGENT_RUN) rather than directly on the generation.
+   */
+  findParentLangfusePrompt(traceData, span) {
+    let currentSpanId = span.parentSpanId;
+    while (currentSpanId) {
+      const parentMetadata = traceData.spanMetadata.get(currentSpanId);
+      if (parentMetadata?.langfusePrompt) {
+        return parentMetadata.langfusePrompt;
+      }
+      currentSpanId = parentMetadata?.parentSpanId;
+    }
+    return void 0;
+  }
+  buildSpanPayload(span, isCreate, traceData) {
     const payload = {};
     if (isCreate) {
       payload.id = span.id;
@@ -185,26 +274,51 @@ var LangfuseExporter = class {
     if (span.output !== void 0) payload.output = span.output;
     if (span.endTime !== void 0) payload.endTime = span.endTime;
     const attributes = span.attributes ?? {};
+    const resolvedTraceData = traceData ?? this.traceMap.get(span.traceId);
+    let inheritedLangfusePrompt;
+    if (span.type === observability$1.SpanType.MODEL_GENERATION && !span.metadata?.langfuse && resolvedTraceData) {
+      inheritedLangfusePrompt = this.findParentLangfusePrompt(resolvedTraceData, span);
+    }
+    const metadata = {
+      ...span.metadata,
+      ...inheritedLangfusePrompt ? { langfuse: { prompt: inheritedLangfusePrompt } } : {}
+    };
     const attributesToOmit = [];
-    if (span.type === aiTracing.AISpanType.LLM_GENERATION) {
-      const llmAttr = attributes;
-      if (llmAttr.model !== void 0) {
-        payload.model = llmAttr.model;
+    const metadataToOmit = [];
+    if (span.type === observability$1.SpanType.MODEL_GENERATION) {
+      const modelAttr = attributes;
+      if (modelAttr.model !== void 0) {
+        payload.model = modelAttr.model;
         attributesToOmit.push("model");
       }
-      if (llmAttr.usage !== void 0) {
-        payload.usage = llmAttr.usage;
+      if (modelAttr.usage !== void 0) {
+        payload.usageDetails = formatUsageMetrics(modelAttr.usage);
         attributesToOmit.push("usage");
       }
-      if (llmAttr.parameters !== void 0) {
-        payload.modelParameters = llmAttr.parameters;
+      if (modelAttr.parameters !== void 0) {
+        payload.modelParameters = modelAttr.parameters;
         attributesToOmit.push("parameters");
       }
+      const langfuseData = metadata.langfuse;
+      const promptData = langfuseData?.prompt;
+      const hasNameAndVersion = promptData?.name !== void 0 && promptData?.version !== void 0;
+      const hasId = promptData?.id !== void 0;
+      if (hasNameAndVersion || hasId) {
+        payload.prompt = {};
+        if (promptData?.name !== void 0) payload.prompt.name = promptData.name;
+        if (promptData?.version !== void 0) payload.prompt.version = promptData.version;
+        if (promptData?.id !== void 0) payload.prompt.id = promptData.id;
+        metadataToOmit.push("langfuse");
+      }
+      if (modelAttr.completionStartTime !== void 0) {
+        payload.completionStartTime = modelAttr.completionStartTime;
+        attributesToOmit.push("completionStartTime");
+      }
     }
     payload.metadata = {
       spanType: span.type,
-      ...aiTracing.omitKeys(attributes, attributesToOmit),
-      ...span.metadata
+      ...utils.omitKeys(attributes, attributesToOmit),
+      ...utils.omitKeys(metadata, metadataToOmit)
     };
     if (span.errorInfo) {
       payload.level = "ERROR";
@@ -212,14 +326,64 @@ var LangfuseExporter = class {
     }
     return payload;
   }
+  async addScoreToTrace({
+    traceId,
+    spanId,
+    score,
+    reason,
+    scorerName,
+    metadata
+  }) {
+    if (!this.client) return;
+    try {
+      await this.client.score({
+        id: `${traceId}-${scorerName}`,
+        traceId,
+        observationId: spanId,
+        name: scorerName,
+        value: score,
+        ...metadata?.sessionId ? { sessionId: metadata.sessionId } : {},
+        metadata: { ...reason ? { reason } : {} },
+        dataType: "NUMERIC"
+      });
+    } catch (error) {
+      this.logger.error("Langfuse exporter: Error adding score to trace", {
+        error,
+        traceId,
+        spanId,
+        scorerName
+      });
+    }
+  }
   async shutdown() {
     if (this.client) {
       await this.client.shutdownAsync();
     }
     this.traceMap.clear();
+    await super.shutdown();
   }
 };
 
+// src/helpers.ts
+function withLangfusePrompt(prompt) {
+  return (opts) => ({
+    ...opts,
+    metadata: {
+      ...opts.metadata,
+      langfuse: {
+        ...opts.metadata?.langfuse,
+        prompt: {
+          ...prompt.name !== void 0 && { name: prompt.name },
+          ...prompt.version !== void 0 && { version: prompt.version },
+          ...prompt.id !== void 0 && { id: prompt.id }
+        }
+      }
+    }
+  });
+}
+
 exports.LangfuseExporter = LangfuseExporter;
+exports.formatUsageMetrics = formatUsageMetrics;
+exports.withLangfusePrompt = withLangfusePrompt;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map