@mastra/langfuse 0.0.0-unified-sidebar-20251010130811 → 0.0.0-unified-workspace-snapshot-20260128233410

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';
+
+const mastra = new Mastra({
+  ...,
+  observability: {
+    configs: {
+      langfuse: {
+        serviceName: 'my-service',
+        exporters: [new LangfuseExporter()],
+      },
+    },
+  },
+});
+```
+
+### Explicit Configuration
+
+You can also pass credentials directly:
+
 ```typescript
 import { LangfuseExporter } from '@mastra/langfuse';
 
-// Use with Mastra
 const mastra = new Mastra({
   ...,
   observability: {
     configs: {
       langfuse: {
-        serviceName: 'service',
+        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,12 +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

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,183 +1,132 @@
 '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
+
+// src/metrics.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 != null && metrics.output != null) {
+    metrics.total = metrics.input + metrics.output;
+    if (metrics.cache_write_input_tokens != null) {
+      metrics.total += metrics.cache_write_input_tokens;
+    }
+  }
+  return metrics;
+}
+
+// src/tracing.ts
+var LangfuseExporter = class extends observability.TrackingExporter {
   name = "langfuse";
-  client;
-  realtime;
-  traceMap = /* @__PURE__ */ new Map();
-  logger;
-  constructor(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
-      });
-      this.client = null;
+  #client;
+  #realtime;
+  constructor(config = {}) {
+    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;
+    super({
+      ...config,
+      publicKey,
+      secretKey,
+      baseUrl
+    });
+    this.#realtime = config.realtime ?? false;
+    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.`
+      );
       return;
     }
-    this.client = new langfuse.Langfuse({
-      publicKey: config.publicKey,
-      secretKey: config.secretKey,
-      baseUrl: config.baseUrl,
+    this.#client = new langfuse.Langfuse({
+      publicKey,
+      secretKey,
+      baseUrl,
       ...config.options
     });
   }
-  async exportEvent(event) {
-    if (!this.client) {
-      return;
-    }
-    if (event.exportedSpan.isEvent) {
-      await this.handleEventSpan(event.exportedSpan);
-      return;
-    }
-    switch (event.type) {
-      case "span_started":
-        await this.handleSpanStarted(event.exportedSpan);
-        break;
-      case "span_updated":
-        await this.handleSpanUpdateOrEnd(event.exportedSpan, false);
-        break;
-      case "span_ended":
-        await this.handleSpanUpdateOrEnd(event.exportedSpan, true);
-        break;
-    }
-    if (this.realtime) {
-      await this.client.flushAsync();
+  async _postExportTracingEvent() {
+    if (this.#realtime) {
+      await this.#client?.flushAsync();
     }
   }
-  async handleSpanStarted(span) {
-    if (span.isRootSpan) {
-      this.initTrace(span);
-    }
-    const method = "handleSpanStarted";
-    const traceData = this.getTraceData({ span, method });
-    if (!traceData) {
-      return;
-    }
-    const langfuseParent = this.getLangfuseParent({ traceData, span, method });
+  async _buildRoot(args) {
+    const { span } = args;
+    return this.#client?.trace(this.buildTracePayload(span));
+  }
+  async _buildEvent(args) {
+    const { span, traceData } = args;
+    const langfuseParent = traceData.getParentOrRoot({ span });
     if (!langfuseParent) {
       return;
     }
-    const payload = this.buildSpanPayload(span, true);
-    const langfuseSpan = span.type === aiTracing.AISpanType.LLM_GENERATION ? langfuseParent.generation(payload) : langfuseParent.span(payload);
-    traceData.spans.set(span.id, langfuseSpan);
-    traceData.activeSpans.add(span.id);
+    const payload = this.buildSpanPayload(span, true, traceData);
+    return langfuseParent.event(payload);
   }
-  async handleSpanUpdateOrEnd(span, isEnd) {
-    const method = isEnd ? "handleSpanEnd" : "handleSpanUpdate";
-    const traceData = this.getTraceData({ span, method });
-    if (!traceData) {
-      return;
-    }
-    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.parentSpanId,
-        method
-      });
+  async _buildSpan(args) {
+    const { span, traceData } = args;
+    const langfuseParent = traceData.getParentOrRoot({ span });
+    if (!langfuseParent) {
       return;
     }
-    langfuseSpan.update(this.buildSpanPayload(span, false));
-    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);
-      }
-    }
+    const payload = this.buildSpanPayload(span, true, traceData);
+    const langfuseSpan = span.type === observability$1.SpanType.MODEL_GENERATION ? langfuseParent.generation(payload) : langfuseParent.span(payload);
+    this.logger.debug(`${this.name}: built span`, {
+      traceId: span.traceId,
+      spanId: payload.id,
+      method: "_buildSpan"
+    });
+    return langfuseSpan;
   }
-  async handleEventSpan(span) {
-    if (span.isRootSpan) {
-      this.logger.debug("Langfuse exporter: Creating trace", {
+  async _updateSpan(args) {
+    const { span, traceData } = args;
+    const langfuseSpan = traceData.getSpan({ spanId: span.id });
+    if (langfuseSpan) {
+      this.logger.debug(`${this.name}: found span for update`, {
         traceId: span.traceId,
-        spanId: span.id,
-        spanName: span.name,
-        method: "handleEventSpan"
+        spanId: langfuseSpan.id,
+        method: "_updateSpan"
       });
-      this.initTrace(span);
-    }
-    const method = "handleEventSpan";
-    const traceData = this.getTraceData({ span, method });
-    if (!traceData) {
-      return;
-    }
-    const langfuseParent = this.getLangfuseParent({ traceData, span, method });
-    if (!langfuseParent) {
-      return;
+      const updatePayload = this.buildSpanPayload(span, false, traceData);
+      langfuseSpan.update(updatePayload);
     }
-    const payload = this.buildSpanPayload(span, true);
-    const langfuseEvent = langfuseParent.event(payload);
-    traceData.events.set(span.id, langfuseEvent);
-    if (!span.endTime) {
-      traceData.activeSpans.add(span.id);
-    }
-  }
-  initTrace(span) {
-    const trace = this.client.trace(this.buildTracePayload(span));
-    this.traceMap.set(span.traceId, {
-      trace,
-      spans: /* @__PURE__ */ new Map(),
-      events: /* @__PURE__ */ new Map(),
-      activeSpans: /* @__PURE__ */ new Set(),
-      rootSpanId: span.id
-    });
   }
-  getTraceData(options) {
-    const { span, method } = options;
-    if (this.traceMap.has(span.traceId)) {
-      return this.traceMap.get(span.traceId);
+  async _finishSpan(args) {
+    const { span, traceData } = args;
+    const langfuseSpan = traceData.getSpan({ spanId: span.id });
+    langfuseSpan?.update(this.buildSpanPayload(span, false, traceData));
+    if (span.isRootSpan) {
+      const langfuseRoot = traceData.getRoot();
+      langfuseRoot?.update({ output: span.output });
     }
-    this.logger.warn("Langfuse exporter: No trace data found for span", {
-      traceId: span.traceId,
-      spanId: span.id,
-      spanName: span.name,
-      spanType: span.type,
-      isRootSpan: span.isRootSpan,
-      parentSpanId: span.parentSpanId,
-      method
-    });
   }
-  getLangfuseParent(options) {
-    const { traceData, span, method } = options;
-    const parentId = span.parentSpanId;
-    if (!parentId) {
-      return traceData.trace;
-    }
-    if (traceData.spans.has(parentId)) {
-      return traceData.spans.get(parentId);
-    }
-    if (traceData.events.has(parentId)) {
-      return traceData.events.get(parentId);
-    }
-    this.logger.warn("Langfuse exporter: No parent data found for span", {
-      traceId: span.traceId,
-      spanId: span.id,
-      spanName: span.name,
-      spanType: span.type,
-      isRootSpan: span.isRootSpan,
-      parentSpanId: span.parentSpanId,
-      method
+  async _abortSpan(args) {
+    const { span, reason } = args;
+    span.end({
+      level: "ERROR",
+      statusMessage: reason.message
     });
   }
   buildTracePayload(span) {
@@ -189,6 +138,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,
@@ -196,37 +146,80 @@ var LangfuseExporter = class {
     };
     return payload;
   }
-  buildSpanPayload(span, isCreate) {
+  /**
+   * Look up the Langfuse prompt from the closest 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.
+   * This enables prompt linking when:
+   * - A workflow calls multiple agents, each with different prompts
+   * - Nested agents have different prompts
+   * - The prompt is set on AGENT_RUN but MODEL_GENERATION inherits it
+   */
+  findLangfusePrompt(traceData, span) {
+    let currentSpanId = span.id;
+    while (currentSpanId) {
+      const providerMetadata = traceData.getMetadata({ spanId: currentSpanId });
+      if (providerMetadata?.prompt) {
+        this.logger.debug(`${this.name}: found prompt in provider metadata`, {
+          traceId: span.traceId,
+          spanId: span.id,
+          prompt: providerMetadata?.prompt
+        });
+        return providerMetadata.prompt;
+      }
+      currentSpanId = traceData.getParentId({ spanId: currentSpanId });
+    }
+    return void 0;
+  }
+  buildSpanPayload(span, isCreate, traceData) {
     const payload = {};
     if (isCreate) {
       payload.id = span.id;
       payload.name = span.name;
       payload.startTime = span.startTime;
-      if (span.input !== void 0) payload.input = span.input;
     }
+    if (span.input !== void 0) payload.input = span.input;
     if (span.output !== void 0) payload.output = span.output;
     if (span.endTime !== void 0) payload.endTime = span.endTime;
     const attributes = span.attributes ?? {};
+    const metadata = {
+      ...span.metadata
+    };
     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 promptData = this.findLangfusePrompt(traceData, span);
+      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";
@@ -242,9 +235,9 @@ var LangfuseExporter = class {
     scorerName,
     metadata
   }) {
-    if (!this.client) return;
+    if (!this.#client) return;
     try {
-      await this.client.score({
+      await this.#client.score({
         id: `${traceId}-${scorerName}`,
         traceId,
         observationId: spanId,
@@ -263,14 +256,40 @@ var LangfuseExporter = class {
       });
     }
   }
-  async shutdown() {
-    if (this.client) {
-      await this.client.shutdownAsync();
+  /**
+   * Force flush any buffered data to Langfuse without shutting down.
+   */
+  async _flush() {
+    if (this.#client) {
+      await this.#client.flushAsync();
+    }
+  }
+  async _postShutdown() {
+    if (this.#client) {
+      await this.#client.shutdownAsync();
     }
-    this.traceMap.clear();
   }
 };
 
+// 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.withLangfusePrompt = withLangfusePrompt;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map