@mastra/langfuse 0.0.0-trace-timeline-update-20251121092347 → 0.0.0-type-testing-20260120105120

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

@@ -6,174 +6,127 @@ var observability = require('@mastra/observability');
 var langfuse = require('langfuse');
 
 // src/tracing.ts
-var LangfuseExporter = class extends observability.BaseExporter {
+
+// 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();
-  constructor(config) {
-    super(config);
-    this.realtime = config.realtime ?? false;
-    if (!config.publicKey || !config.secretKey) {
+  #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: ${!!config.publicKey}, secretKey: ${!!config.secretKey})`
+        `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,
+    this.#client = new langfuse.Langfuse({
+      publicKey,
+      secretKey,
+      baseUrl,
       ...config.options
     });
   }
-  async _exportTracingEvent(event) {
-    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) {
+  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 langfuseParent = this.getLangfuseParent({ traceData, span, method });
+    const payload = this.buildSpanPayload(span, true, traceData);
+    return langfuseParent.event(payload);
+  }
+  async _buildSpan(args) {
+    const { span, traceData } = args;
+    const langfuseParent = traceData.getParentOrRoot({ span });
     if (!langfuseParent) {
       return;
     }
-    const payload = this.buildSpanPayload(span, true);
+    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);
+    this.logger.debug(`${this.name}: built span`, {
+      traceId: span.traceId,
+      spanId: payload.id,
+      method: "_buildSpan"
+    });
+    return langfuseSpan;
   }
-  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", {
+  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,
-        spanType: span.type,
-        isRootSpan: span.isRootSpan,
-        parentSpanId: span.parentSpanId,
-        method
+        spanId: langfuseSpan.id,
+        method: "_updateSpan"
       });
-      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 updatePayload = this.buildSpanPayload(span, false, traceData);
+      langfuseSpan.update(updatePayload);
     }
   }
-  async handleEventSpan(span) {
+  async _finishSpan(args) {
+    const { span, traceData } = args;
+    const langfuseSpan = traceData.getSpan({ spanId: span.id });
+    langfuseSpan?.update(this.buildSpanPayload(span, false, traceData));
     if (span.isRootSpan) {
-      this.logger.debug("Langfuse exporter: Creating trace", {
-        traceId: span.traceId,
-        spanId: span.id,
-        spanName: span.name,
-        method: "handleEventSpan"
-      });
-      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 payload = this.buildSpanPayload(span, true);
-    const langfuseEvent = langfuseParent.event(payload);
-    traceData.events.set(span.id, langfuseEvent);
-    if (!span.endTime) {
-      traceData.activeSpans.add(span.id);
+      const langfuseRoot = traceData.getRoot();
+      langfuseRoot?.update({ output: span.output });
     }
   }
-  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);
-    }
-    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) {
@@ -185,6 +138,7 @@ var LangfuseExporter = class extends observability.BaseExporter {
     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,
@@ -193,59 +147,46 @@ var LangfuseExporter = class extends observability.BaseExporter {
     return payload;
   }
   /**
-   * Normalize usage data to handle both AI SDK v4 and v5 formats.
-   *
-   * AI SDK v4 uses: promptTokens, completionTokens
-   * AI SDK v5 uses: inputTokens, outputTokens
-   *
-   * This function normalizes to a unified format that Langfuse can consume,
-   * prioritizing v5 format while maintaining backward compatibility.
-   *
-   * @param usage - Token usage data from AI SDK (v4 or v5 format)
-   * @returns Normalized usage object, or undefined if no usage data available
+   * 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
    */
-  normalizeUsage(usage) {
-    if (!usage) return void 0;
-    const normalized = {};
-    const inputTokens = usage.inputTokens ?? usage.promptTokens;
-    if (inputTokens !== void 0) {
-      normalized.input = inputTokens;
-    }
-    const outputTokens = usage.outputTokens ?? usage.completionTokens;
-    if (outputTokens !== void 0) {
-      normalized.output = outputTokens;
-    }
-    if (usage.totalTokens !== void 0) {
-      normalized.total = usage.totalTokens;
-    } else if (normalized.input !== void 0 && normalized.output !== void 0) {
-      normalized.total = normalized.input + normalized.output;
-    }
-    if (usage.reasoningTokens !== void 0) {
-      normalized.reasoning = usage.reasoningTokens;
-    }
-    if (usage.cachedInputTokens !== void 0) {
-      normalized.cachedInput = usage.cachedInputTokens;
-    }
-    if (usage.promptCacheHitTokens !== void 0) {
-      normalized.promptCacheHit = usage.promptCacheHitTokens;
-    }
-    if (usage.promptCacheMissTokens !== void 0) {
-      normalized.promptCacheMiss = usage.promptCacheMissTokens;
+  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 Object.keys(normalized).length > 0 ? normalized : void 0;
+    return void 0;
   }
-  buildSpanPayload(span, isCreate) {
+  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 = [];
+    const metadataToOmit = [];
     if (span.type === observability$1.SpanType.MODEL_GENERATION) {
       const modelAttr = attributes;
       if (modelAttr.model !== void 0) {
@@ -253,21 +194,32 @@ var LangfuseExporter = class extends observability.BaseExporter {
         attributesToOmit.push("model");
       }
       if (modelAttr.usage !== void 0) {
-        const normalizedUsage = this.normalizeUsage(modelAttr.usage);
-        if (normalizedUsage) {
-          payload.usage = normalizedUsage;
-        }
+        payload.usageDetails = formatUsageMetrics(modelAttr.usage);
         attributesToOmit.push("usage");
       }
       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,
       ...utils.omitKeys(attributes, attributesToOmit),
-      ...span.metadata
+      ...utils.omitKeys(metadata, metadataToOmit)
     };
     if (span.errorInfo) {
       payload.level = "ERROR";
@@ -283,9 +235,9 @@ var LangfuseExporter = class extends observability.BaseExporter {
     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,
@@ -304,15 +256,40 @@ var LangfuseExporter = class extends observability.BaseExporter {
       });
     }
   }
-  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();
-    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.withLangfusePrompt = withLangfusePrompt;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map