@mastra/braintrust 1.0.0-beta.11 → 1.0.0-beta.13

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # @mastra/braintrust
 
+## 1.0.0-beta.13
+
+### 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
+
+- Fix `logFeedback()` not working because span_id differs from row id. ([#11927](https://github.com/mastra-ai/mastra/pull/11927))
+
+  **Problem**: When using `BraintrustExporter`, user feedback intended for specific agent responses appeared as separate rows in Braintrust rather than being attached to the original generation. The `startSpan()` call passed `spanId: span.id` but omitted the `event: { id: span.id }` parameter, causing Braintrust to auto-generate a different UUID for the row `id` field.
+
+  **Solution**: Add `event: { id: span.id }` to the `startSpan()` call so that the Mastra span ID is used as both the Braintrust `span_id` and row `id`. This allows `logFeedback({ id: span.id })` to correctly attach feedback to existing records.
+
+- Fix Thread view truncation in Braintrust when LLM generations include tool calls. ([#11984](https://github.com/mastra-ai/mastra/pull/11984))
+
+  The Braintrust exporter now reconstructs LLM output in OpenAI Chat Completion format by examining child `MODEL_STEP` and `TOOL_CALL` spans. This enables Braintrust's Thread view to properly display the full conversation flow including tool calls and their results.
+
+- 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.12
+
+### 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.11
 
 ### Minor Changes

package/README.md

@@ -10,21 +10,52 @@ npm install @mastra/braintrust
 
 ## Usage
 
+### Zero-Config Setup
+
+The exporter automatically reads credentials from environment variables:
+
+```bash
+# Required
+BRAINTRUST_API_KEY=sk-...
+
+# Optional
+BRAINTRUST_ENDPOINT=https://api.braintrust.dev
+```
+
+```typescript
+import { BraintrustExporter } from '@mastra/braintrust';
+
+const mastra = new Mastra({
+  ...,
+  observability: {
+    configs: {
+      braintrust: {
+        serviceName: 'my-service',
+        exporters: [new BraintrustExporter()],
+      },
+    },
+  },
+});
+```
+
+### Explicit Configuration
+
+You can also pass credentials directly:
+
 ```typescript
 import { BraintrustExporter } from '@mastra/braintrust';
 
-// Use with Mastra
 const mastra = new Mastra({
   ...,
   observability: {
     configs: {
       braintrust: {
-        serviceName: 'service',
+        serviceName: 'my-service',
         exporters: [
           new BraintrustExporter({
-            apiKey: process.env.BRAINTRUST_API_KEY,
-            projectName: "mastra-tracing", // optional
-            endpoint: process.env.BRAINTRUST_ENDPOINT, // optional
+            apiKey: 'sk-...',
+            projectName: 'mastra-tracing', // Optional, defaults to 'mastra-tracing'
+            endpoint: 'https://api.braintrust.dev', // Optional
           }),
         ],
       },
@@ -33,6 +64,16 @@ const mastra = new Mastra({
 });
 ```
 
+### Configuration Options
+
+| Option             | Type                 | Description                                                    |
+| ------------------ | -------------------- | -------------------------------------------------------------- |
+| `apiKey`           | `string`             | Braintrust API key. Defaults to `BRAINTRUST_API_KEY` env var   |
+| `endpoint`         | `string`             | Custom endpoint URL. Defaults to `BRAINTRUST_ENDPOINT` env var |
+| `projectName`      | `string`             | Project name. Defaults to `'mastra-tracing'`                   |
+| `braintrustLogger` | `Logger<true>`       | Optional Braintrust logger instance for context integration    |
+| `tuningParameters` | `Record<string,any>` | Support tuning parameters                                      |
+
 ## Features
 
 ### Tracing
@@ -42,3 +83,4 @@ const mastra = new Mastra({
 - **Error tracking**: Automatic error status and message tracking
 - **Hierarchical traces**: Maintains parent-child relationships
 - **Event span support**: Zero-duration spans for event-type traces
+- **Context integration**: Attach to existing Braintrust spans from `logger.traced()` or `Eval()`

package/dist/formatter.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Message format conversion utilities for Braintrust.
+ *
+ * Converts AI SDK message format (v4/v5) to OpenAI Chat Completion format,
+ * which Braintrust requires for proper rendering of threads.
+ */
+/**
+ * Remove null and undefined values from an object (shallow)
+ */
+export declare function removeNullish<T extends Record<string, unknown>>(obj: T): Partial<T>;
+/**
+ * AI SDK content part types (both v4 and v5)
+ */
+interface AISDKTextPart {
+    type: 'text';
+    text: string;
+}
+interface AISDKImagePart {
+    type: 'image';
+    image?: string | Uint8Array | URL;
+    mimeType?: string;
+}
+interface AISDKFilePart {
+    type: 'file';
+    data?: string | Uint8Array | URL;
+    filename?: string;
+    name?: string;
+    mimeType?: string;
+}
+interface AISDKReasoningPart {
+    type: 'reasoning';
+    text?: string;
+}
+interface AISDKToolCallPart {
+    type: 'tool-call';
+    toolCallId: string;
+    toolName: string;
+    args?: unknown;
+    input?: unknown;
+}
+interface AISDKToolResultPart {
+    type: 'tool-result';
+    toolCallId: string;
+    result?: unknown;
+    output?: unknown;
+}
+type AISDKContentPart = AISDKTextPart | AISDKImagePart | AISDKFilePart | AISDKReasoningPart | AISDKToolCallPart | AISDKToolResultPart | {
+    type: string;
+    [key: string]: unknown;
+};
+/**
+ * AI SDK message format (input format for conversion)
+ */
+interface AISDKMessage {
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string | AISDKContentPart[];
+    [key: string]: unknown;
+}
+/**
+ * OpenAI Chat Completion tool call format
+ */
+export interface OpenAIToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/**
+ * OpenAI Chat Completion message format (output format)
+ */
+export interface OpenAIMessage {
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string;
+    tool_calls?: OpenAIToolCall[];
+    tool_call_id?: string;
+    [key: string]: unknown;
+}
+/**
+ * Converts AI SDK message format to OpenAI Chat Completion format for Braintrust.
+ *
+ * Supports both AI SDK v4 and v5 formats:
+ *   - v4 uses 'args' for tool calls and 'result' for tool results
+ *   - v5 uses 'input' for tool calls and 'output' for tool results
+ *
+ * AI SDK format:
+ *   { role: "user", content: [{ type: "text", text: "hello" }] }
+ *   { role: "assistant", content: [{ type: "text", text: "..." }, { type: "tool-call", toolCallId: "...", toolName: "...", args: {...} }] }
+ *   { role: "tool", content: [{ type: "tool-result", toolCallId: "...", result: {...} }] }
+ *
+ * OpenAI format (what Braintrust expects):
+ *   { role: "user", content: "hello" }
+ *   { role: "assistant", content: "...", tool_calls: [{ id: "...", type: "function", function: { name: "...", arguments: "..." } }] }
+ *   { role: "tool", content: "result", tool_call_id: "..." }
+ */
+export declare function convertAISDKMessage(message: AISDKMessage | OpenAIMessage | unknown): OpenAIMessage | unknown;
+export {};
+//# sourceMappingURL=formatter.d.ts.map

package/dist/formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.d.ts","sourceRoot":"","sources":["../src/formatter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAEnF;AAMD;;GAEG;AACH,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,GAAG,CAAC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,GAAG,CAAC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,kBAAkB;IAC1B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,UAAU,iBAAiB;IACzB,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,UAAU,mBAAmB;IAC3B,IAAI,EAAE,aAAa,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,KAAK,gBAAgB,GACjB,aAAa,GACb,cAAc,GACd,aAAa,GACb,kBAAkB,GAClB,iBAAiB,GACjB,mBAAmB,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AAE7C;;GAEG;AACH,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC/C,OAAO,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAAC;IACrC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAqFD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,YAAY,GAAG,aAAa,GAAG,OAAO,GAAG,aAAa,GAAG,OAAO,CA+F5G"}