@mastra/langfuse 1.0.0-beta.10 → 1.0.0-beta.12

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # @mastra/langfuse
 
+## 1.0.0-beta.12
+
+### Minor Changes
+
+- Added `TrackingExporter` base class with improved handling for: ([#11870](https://github.com/mastra-ai/mastra/pull/11870))
+  - **Out-of-order span processing**: Spans that arrive before their parents are now queued and processed once dependencies are available
+  - **Delayed cleanup**: Trace data is retained briefly after spans end to handle late-arriving updates
+  - **Memory management**: Configurable limits on pending and total traces to prevent memory leaks
+
+  New configuration options on `TrackingExporterConfig`:
+  - `earlyQueueMaxAttempts` - Max retry attempts for queued events (default: 5)
+  - `earlyQueueTTLMs` - TTL for queued events in ms (default: 30000)
+  - `traceCleanupDelayMs` - Delay before cleaning up completed traces (default: 30000)
+  - `maxPendingCleanupTraces` - Soft cap on traces awaiting cleanup (default: 100)
+  - `maxTotalTraces` - Hard cap on total traces (default: 500)
+
+  Updated @mastra/braintrust, @mastra/langfuse, @mastra/langsmith, @mastra/posthog to use the new TrackingExporter
+
+### Patch Changes
+
+- Updated dependencies [[`ebae12a`](https://github.com/mastra-ai/mastra/commit/ebae12a2dd0212e75478981053b148a2c246962d), [`c61a0a5`](https://github.com/mastra-ai/mastra/commit/c61a0a5de4904c88fd8b3718bc26d1be1c2ec6e7), [`69136e7`](https://github.com/mastra-ai/mastra/commit/69136e748e32f57297728a4e0f9a75988462f1a7), [`449aed2`](https://github.com/mastra-ai/mastra/commit/449aed2ba9d507b75bf93d427646ea94f734dfd1), [`eb648a2`](https://github.com/mastra-ai/mastra/commit/eb648a2cc1728f7678768dd70cd77619b448dab9), [`0131105`](https://github.com/mastra-ai/mastra/commit/0131105532e83bdcbb73352fc7d0879eebf140dc), [`9d5059e`](https://github.com/mastra-ai/mastra/commit/9d5059eae810829935fb08e81a9bb7ecd5b144a7), [`ef756c6`](https://github.com/mastra-ai/mastra/commit/ef756c65f82d16531c43f49a27290a416611e526), [`b00ccd3`](https://github.com/mastra-ai/mastra/commit/b00ccd325ebd5d9e37e34dd0a105caae67eb568f), [`3bdfa75`](https://github.com/mastra-ai/mastra/commit/3bdfa7507a91db66f176ba8221aa28dd546e464a), [`e770de9`](https://github.com/mastra-ai/mastra/commit/e770de941a287a49b1964d44db5a5763d19890a6), [`52e2716`](https://github.com/mastra-ai/mastra/commit/52e2716b42df6eff443de72360ae83e86ec23993), [`27b4040`](https://github.com/mastra-ai/mastra/commit/27b4040bfa1a95d92546f420a02a626b1419a1d6), [`610a70b`](https://github.com/mastra-ai/mastra/commit/610a70bdad282079f0c630e0d7bb284578f20151), [`8dc7f55`](https://github.com/mastra-ai/mastra/commit/8dc7f55900395771da851dc7d78d53ae84fe34ec), [`8379099`](https://github.com/mastra-ai/mastra/commit/8379099fc467af6bef54dd7f80c9bd75bf8bbddf), [`b06be72`](https://github.com/mastra-ai/mastra/commit/b06be7223d5ef23edc98c01a67ef713c6cc039f9), [`8c0ec25`](https://github.com/mastra-ai/mastra/commit/8c0ec25646c8a7df253ed1e5ff4863a0d3f1316c), [`ff4d9a6`](https://github.com/mastra-ai/mastra/commit/ff4d9a6704fc87b31a380a76ed22736fdedbba5a), [`69821ef`](https://github.com/mastra-ai/mastra/commit/69821ef806482e2c44e2197ac0b050c3fe3a5285), [`1ed5716`](https://github.com/mastra-ai/mastra/commit/1ed5716830867b3774c4a1b43cc0d82935f32b96), [`4186bdd`](https://github.com/mastra-ai/mastra/commit/4186bdd00731305726fa06adba0b076a1d50b49f), [`7aaf973`](https://github.com/mastra-ai/mastra/commit/7aaf973f83fbbe9521f1f9e7a4fd99b8de464617)]:
+  - @mastra/core@1.0.0-beta.22
+  - @mastra/observability@1.0.0-beta.11
+
+## 1.0.0-beta.11
+
+### Minor Changes
+
+- feat(observability): add zero-config environment variable support for all exporters ([#11686](https://github.com/mastra-ai/mastra/pull/11686))
+
+  All observability exporters now support zero-config setup via environment variables. Set the appropriate environment variables and instantiate exporters with no configuration:
+  - **Langfuse**: `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `LANGFUSE_BASE_URL`
+  - **Braintrust**: `BRAINTRUST_API_KEY`, `BRAINTRUST_ENDPOINT`
+  - **PostHog**: `POSTHOG_API_KEY`, `POSTHOG_HOST`
+  - **Arize/Phoenix**: `ARIZE_SPACE_ID`, `ARIZE_API_KEY`, `ARIZE_PROJECT_NAME`, `PHOENIX_ENDPOINT`, `PHOENIX_API_KEY`, `PHOENIX_PROJECT_NAME`
+  - **OTEL Providers**:
+    - Dash0: `DASH0_API_KEY`, `DASH0_ENDPOINT`, `DASH0_DATASET`
+    - SigNoz: `SIGNOZ_API_KEY`, `SIGNOZ_REGION`, `SIGNOZ_ENDPOINT`
+    - New Relic: `NEW_RELIC_LICENSE_KEY`, `NEW_RELIC_ENDPOINT`
+    - Traceloop: `TRACELOOP_API_KEY`, `TRACELOOP_DESTINATION_ID`, `TRACELOOP_ENDPOINT`
+    - Laminar: `LMNR_PROJECT_API_KEY`, `LAMINAR_ENDPOINT`
+
+  Example usage:
+
+  ```typescript
+  // Zero-config - reads from environment variables
+  new LangfuseExporter();
+  new BraintrustExporter();
+  new PosthogExporter();
+  new ArizeExporter();
+  new OtelExporter({ provider: { signoz: {} } });
+  ```
+
+  Explicit configuration still works and takes precedence over environment variables.
+
+### Patch Changes
+
+- Updated dependencies [[`08766f1`](https://github.com/mastra-ai/mastra/commit/08766f15e13ac0692fde2a8bd366c2e16e4321df), [`ae8baf7`](https://github.com/mastra-ai/mastra/commit/ae8baf7d8adcb0ff9dac11880400452bc49b33ff), [`cfabdd4`](https://github.com/mastra-ai/mastra/commit/cfabdd4aae7a726b706942d6836eeca110fb6267), [`a0e437f`](https://github.com/mastra-ai/mastra/commit/a0e437fac561b28ee719e0302d72b2f9b4c138f0), [`bec5efd`](https://github.com/mastra-ai/mastra/commit/bec5efde96653ccae6604e68c696d1bc6c1a0bf5), [`9eedf7d`](https://github.com/mastra-ai/mastra/commit/9eedf7de1d6e0022a2f4e5e9e6fe1ec468f9b43c)]:
+  - @mastra/core@1.0.0-beta.21
+
 ## 1.0.0-beta.10
 
 ### Patch Changes

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,6 +66,16 @@ 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
 
 ### Tracing

package/dist/index.cjs

@@ -6,6 +6,8 @@ var observability = require('@mastra/observability');
 var langfuse = require('langfuse');
 
 // src/tracing.ts
+
+// src/metrics.ts
 function formatUsageMetrics(usage) {
   if (!usage) return {};
   const metrics = {};
@@ -25,204 +27,106 @@ function formatUsageMetrics(usage) {
   if (usage.outputDetails?.reasoning !== void 0) {
     metrics.reasoning = usage.outputDetails.reasoning;
   }
-  if (metrics.input && metrics.output) {
+  if (metrics.input != null && metrics.output != null) {
     metrics.total = metrics.input + metrics.output;
-    if (metrics.cache_write_input_tokens) {
+    if (metrics.cache_write_input_tokens != null) {
       metrics.total += metrics.cache_write_input_tokens;
     }
   }
   return metrics;
 }
-var LangfuseExporter = class extends observability.BaseExporter {
+
+// 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) {
-      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 });
+  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, 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";
-    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
-      });
-      return;
-    }
-    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);
-      }
-    }
+    return langfuseParent.event(payload);
   }
-  async handleEventSpan(span) {
-    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 });
+  async _buildSpan(args) {
+    const { span, traceData } = args;
+    const langfuseParent = traceData.getParentOrRoot({ span });
     if (!langfuseParent) {
       return;
     }
     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);
-    }
+    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;
   }
-  initTrace(span) {
-    if (this.traceMap.has(span.traceId)) {
-      this.logger.debug("Langfuse exporter: Reusing existing trace from local map", {
+  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
+        spanId: langfuseSpan.id,
+        method: "_updateSpan"
       });
-      return;
+      const updatePayload = this.buildSpanPayload(span, false, traceData);
+      langfuseSpan.update(updatePayload);
     }
-    const trace = this.client.trace(this.buildTracePayload(span));
-    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;
-    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) {
@@ -243,18 +147,27 @@ var LangfuseExporter = class extends observability.BaseExporter {
     return payload;
   }
   /**
-   * Look up the Langfuse prompt from the closest parent span that has one.
+   * 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
    */
-  findParentLangfusePrompt(traceData, span) {
-    let currentSpanId = span.parentSpanId;
+  findLangfusePrompt(traceData, span) {
+    let currentSpanId = span.id;
     while (currentSpanId) {
-      const parentMetadata = traceData.spanMetadata.get(currentSpanId);
-      if (parentMetadata?.langfusePrompt) {
-        return parentMetadata.langfusePrompt;
+      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 = parentMetadata?.parentSpanId;
+      currentSpanId = traceData.getParentId({ spanId: currentSpanId });
     }
     return void 0;
   }
@@ -264,19 +177,13 @@ var LangfuseExporter = class extends observability.BaseExporter {
       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 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 } } : {}
+      ...span.metadata
     };
     const attributesToOmit = [];
     const metadataToOmit = [];
@@ -294,8 +201,7 @@ var LangfuseExporter = class extends observability.BaseExporter {
         payload.modelParameters = modelAttr.parameters;
         attributesToOmit.push("parameters");
       }
-      const langfuseData = metadata.langfuse;
-      const promptData = langfuseData?.prompt;
+      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) {
@@ -329,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,
@@ -350,12 +256,10 @@ var LangfuseExporter = class extends observability.BaseExporter {
       });
     }
   }
-  async shutdown() {
-    if (this.client) {
-      await this.client.shutdownAsync();
+  async _postShutdown() {
+    if (this.#client) {
+      await this.#client.shutdownAsync();
     }
-    this.traceMap.clear();
-    await super.shutdown();
   }
 };
 
@@ -378,7 +282,6 @@ function withLangfusePrompt(prompt) {
 }
 
 exports.LangfuseExporter = LangfuseExporter;
-exports.formatUsageMetrics = formatUsageMetrics;
 exports.withLangfusePrompt = withLangfusePrompt;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map