@mastra/mcp-docs-server 1.1.35-alpha.8 → 1.1.35

package/.docs/docs/memory/observational-memory.md

@@ -77,6 +77,48 @@ The observer also sees these markers when it processes the thread, so the observ
 
 See [the API reference](https://mastra.ai/reference/memory/observational-memory) for the full configuration shape.
 
+## Early activation
+
+OM can activate buffered observations before the token threshold is reached. This is useful when a prompt cache is likely to expire, or when the agent changes model providers.
+
+Top-level early activation settings apply to observations by default:
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      activateAfterIdle: '5m',
+      activateOnProviderChange: true,
+    },
+  },
+})
+```
+
+Use nested `observation` and `reflection` settings for per-phase control. Reflection early activation is opt-in, so top-level settings affect only observations.
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      activateAfterIdle: '5m',
+      observation: {
+        activateAfterIdle: false,
+      },
+      reflection: {
+        activateAfterIdle: '10m',
+        activateOnProviderChange: true,
+      },
+    },
+  },
+})
+```
+
+In this example, the top-level idle setting is disabled for observations, while reflections opt into idle and provider-change activation.
+
+See [the API reference](https://mastra.ai/reference/memory/observational-memory) for the full configuration shape.
+
 ## Benefits
 
 - **Prompt caching**: OM's context is stable and observations append over time rather than being dynamically retrieved each turn. This keeps the prompt prefix cacheable, which reduces costs.
@@ -216,7 +258,7 @@ The Observer and Reflector run in the background. Any model that works with Mast
 
 Generally speaking, we recommend using a model that has a large context window (128K+ tokens) and is fast enough to run in the background without slowing down your actions.
 
-If you're unsure which model to use, start with the default `google/gemini-2.5-flash`. We've also successfully tested `openai/gpt-5-mini`, `anthropic/claude-haiku-4-5`, `deepseek/deepseek-reasoner`, `qwen3`, and `glm-4.7`.
+If you're unsure which model to use, start with the default `google/gemini-2.5-flash`. We've also successfully tested `openai/gpt-5-mini`, `anthropic/claude-haiku-4-5`, `deepseek/deepseek-reasoner`, `deepseek/deepseek-v4-pro`, `deepseek/deepseek-v4-flash`, `xai/grok-4-1-fast`, `qwen3`, and `glm-4.7`.
 
 ```typescript
 const memory = new Memory({
@@ -230,6 +272,10 @@ const memory = new Memory({
 
 See [model configuration](https://mastra.ai/reference/memory/observational-memory) for using different models per agent.
 
+> **Note:** `google/gemini-2.5-flash` is unusually good at preserving detail in long output. As a result, the Reflector can produce reflections that stay above the configured `reflection.observationTokens` threshold even after the maximum compression retry. When this happens, the Reflector returns the smallest non-degenerate candidate produced during retries so the loop terminates instead of running forever.
+>
+> If you'd rather have more aggressive compression on the Reflector, swap to a model that condenses more readily, such as `xai/grok-4-1-fast`, `deepseek/deepseek-v4-pro`, or `deepseek/deepseek-v4-flash`. You can keep `google/gemini-2.5-flash` for the Observer and use a different model for the Reflector — see [different models per agent](https://mastra.ai/reference/memory/observational-memory).
+
 ### Token-tiered model selection
 
 **Added in:** `@mastra/memory@1.10.0`
@@ -364,17 +410,19 @@ Reflection works similarly — the Reflector runs in the background when observa
 
 ### Settings
 
-| Setting                        | Default | What it controls                                                                                                                                                                                                                                                                                                                       |
-| ------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `observation.bufferTokens`     | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens` — with the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).                                                                                                                                                     |
-| `observation.bufferActivation` | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history.                                                                                                                                                  |
-| `observation.blockAfter`       | `1.2`   | Safety threshold as a multiplier of `messageTokens`. At `1.2`, synchronous observation is forced at 36k tokens (1.2 × 30k). Only matters if buffering can't keep up.                                                                                                                                                                   |
-| `activateAfterIdle`            | none    | Forces buffered observations and buffered reflections to activate after a period of inactivity, even if their token thresholds have not been reached yet. Accepts milliseconds or duration strings like `300_000`, `"5m"`, or `"1hr"`. Set this to your prompt cache TTL if you want activation to happen before the next cold prompt. |
-| `activateOnProviderChange`     | `false` | Forces buffered observations and reflections to activate when the next step uses a different `provider/model` than the one that produced the latest assistant step. Use this when switching providers or models would invalidate prompt cache reuse.                                                                                   |
-| `reflection.bufferActivation`  | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                                                                                                                                                                   |
-| `reflection.blockAfter`        | `1.2`   | Safety threshold for reflection, same logic as observation.                                                                                                                                                                                                                                                                            |
+| Setting                               | Default | What it controls                                                                                                                                                                                                                                                                                                              |
+| ------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `observation.bufferTokens`            | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens` — with the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).                                                                                                                                            |
+| `observation.bufferActivation`        | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history.                                                                                                                                         |
+| `observation.blockAfter`              | `1.2`   | Safety threshold as a multiplier of `messageTokens`. At `1.2`, synchronous observation is forced at 36k tokens (1.2 × 30k). Only matters if buffering can't keep up.                                                                                                                                                          |
+| `activateAfterIdle`                   | none    | Forces buffered observations to activate after a period of inactivity, even before `observation.messageTokens` is reached. Accepts a numeric millisecond value such as `300_000`, or duration strings like `"5m"` or `"1hr"`. Set this to your prompt cache TTL if you want activation to happen before the next cold prompt. |
+| `activateOnProviderChange`            | `false` | Forces buffered observations to activate when the next step uses a different `provider/model` than the one that produced the latest assistant step. Use this when switching providers or models would invalidate prompt cache reuse.                                                                                          |
+| `reflection.bufferActivation`         | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                                                                                                                                                          |
+| `reflection.activateAfterIdle`        | none    | Opts buffered reflections into idle activation. Reflections don't inherit top-level `activateAfterIdle`.                                                                                                                                                                                                                      |
+| `reflection.activateOnProviderChange` | `false` | Opts buffered reflections into provider-change activation. Reflections don't inherit top-level `activateOnProviderChange`.                                                                                                                                                                                                    |
+| `reflection.blockAfter`               | `1.2`   | Safety threshold for reflection, same logic as observation.                                                                                                                                                                                                                                                                   |
 
-If you're relying on prompt caching, set `activateAfterIdle` to match your cache TTL. That way, once a thread has been idle long enough for the cache to expire, the next request can activate buffered observations or reflections first and send a smaller compressed context window.
+If you're relying on prompt caching, set `activateAfterIdle` to match your cache TTL. That way, once a thread has been idle long enough for the cache to expire, the next request can activate buffered observations first and send a smaller compressed context window.
 
 ```typescript
 const memory = new Memory({
@@ -388,9 +436,9 @@ const memory = new Memory({
 })
 ```
 
-With a 5-minute prompt cache TTL, this activates buffered context after 5 minutes of inactivity so the next uncached prompt uses observations and reflections instead of a larger raw message window. If you prefer, `300_000` works the same way.
+With a 5-minute prompt cache TTL, this activates buffered observations after 5 minutes of inactivity so the next uncached prompt uses compressed observations instead of a larger raw message window. If you prefer, `300_000` works the same way.
 
-Changing model or providers mid-thread will invalidate the prompt cache. If your agent can switch between providers or models mid-thread, `activateOnProviderChange: true` forces buffered context to activate before the new provider runs. That avoids sending a large raw window to a provider that cannot reuse the previous prompt cache.
+Changing model or providers mid-thread will invalidate the prompt cache. If your agent can switch between providers or models mid-thread, `activateOnProviderChange: true` forces buffered observations to activate before the new provider runs. That avoids sending a large raw window to a provider that can't reuse the previous prompt cache.
 
 ### Disabling
 

package/.docs/docs/memory/semantic-recall.md

@@ -121,26 +121,88 @@ Each vector store page below includes installation instructions, configuration p
 
 ## Recall configuration
 
-The three main parameters that control semantic recall behavior are:
+The following options control semantic recall behavior:
 
-1. **topK**: How many semantically similar messages to retrieve
-2. **messageRange**: How much surrounding context to include with each match
-3. **scope**: Whether to search within the current thread or across all threads owned by a resource (the default is resource scope).
+1. **topK**: The number of similar messages to retrieve
+2. **messageRange**: The surrounding messages to include with each match
+3. **scope**: Whether to search the current thread or all threads for a resource
+4. **filter**: Metadata criteria that restrict search results
 
 ```typescript
 const agent = new Agent({
   memory: new Memory({
     options: {
       semanticRecall: {
-        topK: 3, // Retrieve 3 most similar messages
+        topK: 3, // Retrieve 3 similar messages
         messageRange: 2, // Include 2 messages before and after each match
-        scope: 'resource', // Search across all threads for this user (default setting if omitted)
+        scope: 'resource', // Search all threads for this resource
+        filter: { projectId: { $eq: 'project-a' } },
       },
     },
   }),
 })
 ```
 
+> **Note:** `scope: 'resource'` is supported by the LibSQL, PostgreSQL, and Upstash storage adapters.
+
+### Metadata filtering
+
+The `filter` option restricts semantic recall results to messages with matching thread metadata.
+
+```typescript
+const agent = new Agent({
+  memory: new Memory({
+    options: {
+      semanticRecall: {
+        scope: 'resource',
+        filter: {
+          projectId: { $eq: 'project-a' },
+          category: { $in: ['work', 'personal'] },
+        },
+      },
+    },
+  }),
+})
+```
+
+Filters match metadata stored on message embeddings when messages are saved. If thread metadata changes later, existing embeddings keep their previous metadata until those messages are saved or indexed again.
+
+Supported filter operators:
+
+- `$and`: Logical AND
+- `$eq`: Equal to
+- `$gt`: Greater than
+- `$gte`: Greater than or equal
+- `$in`: In array
+- `$lt`: Less than
+- `$lte`: Less than or equal
+- `$ne`: Not equal to
+- `$nin`: Not in array
+- `$or`: Logical OR
+
+The following example demonstrates metadata filters for common use cases:
+
+```typescript
+// Filter by project
+const options = {
+  semanticRecall: { filter: { projectId: { $eq: 'my-project' } } },
+}
+
+// Filter by multiple categories
+const options = {
+  semanticRecall: { filter: { category: { $in: ['work', 'research'] } } },
+}
+
+// Filter by project and priority
+const options = {
+  semanticRecall: {
+    filter: {
+      $and: [{ projectId: { $eq: 'project-a' } }, { priority: { $gte: 3 } }],
+    },
+  },
+}
+```
+
 ## Embedder configuration
 
 Semantic recall relies on an [embedding model](https://mastra.ai/reference/memory/memory-class) to convert messages into embeddings. Mastra supports embedding models through the model router using `provider/model` strings, or you can use any [embedding model](https://sdk.vercel.ai/docs/ai-sdk-core/embeddings) compatible with the AI SDK.

package/.docs/docs/observability/logging.md

@@ -35,7 +35,7 @@ You can control which log levels reach observability storage independently from
 ```typescript
 import { Mastra } from '@mastra/core/mastra'
 import { PinoLogger } from '@mastra/loggers'
-import { Observability, DefaultExporter } from '@mastra/observability'
+import { Observability, MastraStorageExporter } from '@mastra/observability'
 
 export const mastra = new Mastra({
   logger: new PinoLogger({ name: 'Mastra', level: 'debug' }),
@@ -43,7 +43,7 @@ export const mastra = new Mastra({
     configs: {
       default: {
         serviceName: 'my-app',
-        exporters: [new DefaultExporter()],
+        exporters: [new MastraStorageExporter()],
         logging: {
           enabled: true, // set to false to disable log forwarding
           level: 'info', // minimum level: 'debug' | 'info' | 'warn' | 'error' | 'fatal'

package/.docs/docs/observability/metrics/overview.md

@@ -54,7 +54,7 @@ import { Mastra } from '@mastra/core/mastra'
 import { LibSQLStore } from '@mastra/libsql'
 import { DuckDBStore } from '@mastra/duckdb'
 import { MastraCompositeStore } from '@mastra/core/storage'
-import { Observability, DefaultExporter, SensitiveDataFilter } from '@mastra/observability'
+import { Observability, MastraStorageExporter, SensitiveDataFilter } from '@mastra/observability'
 
 export const mastra = new Mastra({
   storage: new MastraCompositeStore({
@@ -71,7 +71,7 @@ export const mastra = new Mastra({
     configs: {
       default: {
         serviceName: 'mastra',
-        exporters: [new DefaultExporter()],
+        exporters: [new MastraStorageExporter()],
         spanOutputProcessors: [new SensitiveDataFilter()],
       },
     },
@@ -103,7 +103,7 @@ Mastra auto-instruments agent runs, workflow steps, tool calls, and model genera
 2. **Token usage**: Extracted from the `usage` attribute on model generation spans.
 3. **Cost estimation**: Runs each token metric through an embedded pricing registry that matches by provider and model name.
 
-Before storage, all metric labels pass through a cardinality filter that blocks known high-cardinality values (such as trace IDs and UUIDs) to keep storage efficient. Metrics are then batched by an internal event buffer and flushed to storage by the `DefaultExporter`.
+Before storage, all metric labels pass through a cardinality filter that blocks known high-cardinality values (such as trace IDs and UUIDs) to keep storage efficient. Metrics are then batched by an internal event buffer and flushed to storage by the `MastraStorageExporter`.
 
 ## Next steps
 
@@ -111,4 +111,4 @@ Before storage, all metric labels pass through a cardinality filter that blocks
 - [Tracing overview](https://mastra.ai/docs/observability/tracing/overview)
 - [Studio observability](https://mastra.ai/docs/studio/observability)
 - [Observability overview](https://mastra.ai/docs/observability/overview)
-- [DefaultExporter reference](https://mastra.ai/docs/observability/tracing/exporters/default)
+- [MastraStorageExporter reference](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage)

package/.docs/docs/observability/overview.md

@@ -61,8 +61,8 @@ import { DuckDBStore } from '@mastra/duckdb'
 import { MastraCompositeStore } from '@mastra/core/storage'
 import {
   Observability,
-  DefaultExporter,
-  CloudExporter,
+  MastraStorageExporter,
+  MastraPlatformExporter,
   SensitiveDataFilter,
 } from '@mastra/observability'
 
@@ -82,8 +82,8 @@ export const mastra = new Mastra({
       default: {
         serviceName: 'mastra',
         exporters: [
-          new DefaultExporter(), // Persists traces to storage for Mastra Studio
-          new CloudExporter(), // Sends observability data to hosted Mastra Studio (if MASTRA_CLOUD_ACCESS_TOKEN is set)
+          new MastraStorageExporter(), // Persists observability events to Mastra Storage
+          new MastraPlatformExporter(), // Sends observability events to Mastra Platform (if MASTRA_CLOUD_ACCESS_TOKEN is set)
         ],
         spanOutputProcessors: [
           new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
@@ -98,9 +98,9 @@ This enables tracing, log forwarding, and metrics. Mastra also supports external
 
 ## Storage
 
-Not all storage backends support every signal. Traces and logs work with most backends, but metrics require an OLAP-capable store like DuckDB (development) or ClickHouse (production). For the full compatibility list, see [storage provider support](https://mastra.ai/docs/observability/tracing/exporters/default).
+Not all storage backends support every signal. Traces and logs work with most backends, but metrics require an OLAP-capable store like DuckDB (development) or ClickHouse (production). For the full compatibility list, see [storage provider support](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage).
 
-For production environments with high traffic, use composite storage to route the observability domain to a dedicated backend. See [production recommendations](https://mastra.ai/docs/observability/tracing/exporters/default) for details.
+For production environments with high traffic, use composite storage to route the observability domain to a dedicated backend. See [production recommendations](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage) for details.
 
 ## Next steps
 

package/.docs/docs/observability/tracing/bridges/otel.md

@@ -31,6 +31,7 @@ The OtelBridge provides two-way integration:
 - Creates native OTEL spans for Mastra operations (agents, LLM calls, tools, workflows)
 - Maintains proper parent-child relationships in distributed traces
 - Allows OTEL-instrumented code (HTTP clients, database calls) within Mastra operations to nest correctly
+- Forwards Mastra log events to the globally-registered OTEL `LoggerProvider`. Logs that originate inside a Mastra span are emitted under that span's OTEL context so backends correlate them with the trace. If no `LoggerProvider` is registered, log emission is a silent no-op.
 
 ## Installation
 
@@ -67,6 +68,7 @@ The bridge works with your existing OpenTelemetry setup. Depending on your confi
 - `@opentelemetry/exporter-trace-otlp-grpc` - OTLP exporter (gRPC)
 - `@opentelemetry/sdk-trace-base` - Base tracing SDK (for BatchSpanProcessor, etc.)
 - `@opentelemetry/core` - Core utilities (for W3CTraceContextPropagator, etc.)
+- `@opentelemetry/sdk-logs` and an OTLP log exporter (e.g. `@opentelemetry/exporter-logs-otlp-http`) - Required if you want the bridge to forward Mastra log events too
 
 ## Configuration
 
@@ -130,6 +132,29 @@ export const mastra = new Mastra({
 
 No Mastra exporters are required when using the bridge — traces are sent via your OTEL SDK configuration. You can optionally add Mastra exporters if you want to send traces to additional destinations.
 
+### Forwarding logs (optional)
+
+The bridge also forwards Mastra log events to the globally-registered OTEL `LoggerProvider`. To wire up logs alongside traces, register a `logRecordProcessor` on `NodeSDK`:
+
+```typescript
+import { NodeSDK } from '@opentelemetry/sdk-node'
+import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http'
+import { BatchLogRecordProcessor } from '@opentelemetry/sdk-logs'
+
+const sdk = new NodeSDK({
+  // ...trace config as usual
+  logRecordProcessor: new BatchLogRecordProcessor(
+    new OTLPLogExporter({
+      url: process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT || 'http://localhost:4318/v1/logs',
+    }),
+  ),
+})
+```
+
+Logs that originate inside a Mastra span are emitted under that span's OTEL context, so backends like Datadog, Grafana, and Honeycomb correlate them with the surrounding trace automatically. Logs without trace context fall through to the currently active OTEL context.
+
+If you do not register a `LoggerProvider`, log emission is a silent no-op — traces continue to work as configured.
+
 ### Running Your Application
 
 Use the `--import` flag to ensure instrumentation loads before your application:

package/.docs/docs/observability/tracing/exporters/arize.md

@@ -43,7 +43,7 @@ Phoenix is an open-source observability platform that can be self-hosted or used
 
 ```bash
 # Required
-PHOENIX_ENDPOINT=http://localhost:6006/v1/traces  # Or your Phoenix Cloud URL
+PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006/v1/traces  # Or your Phoenix Cloud URL
 
 # Optional
 PHOENIX_API_KEY=your-api-key  # For authenticated Phoenix instances
@@ -87,7 +87,7 @@ export const mastra = new Mastra({
         serviceName: process.env.PHOENIX_PROJECT_NAME || 'mastra-service',
         exporters: [
           new ArizeExporter({
-            endpoint: process.env.PHOENIX_ENDPOINT!,
+            endpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT!,
             apiKey: process.env.PHOENIX_API_KEY,
             projectName: process.env.PHOENIX_PROJECT_NAME,
           }),
@@ -106,7 +106,7 @@ export const mastra = new Mastra({
 >   arizephoenix/phoenix:latest
 > ```
 >
-> Set `PHOENIX_ENDPOINT=http://localhost:6006/v1/traces` and run your Mastra agent to see traces at [localhost:6006](http://localhost:6006).
+> Set `PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006/v1/traces` and run your Mastra agent to see traces at [localhost:6006](http://localhost:6006).
 
 ### Arize AX Setup
 
@@ -218,7 +218,7 @@ Control how traces are batched and exported:
 
 ```typescript
 new ArizeExporter({
-  endpoint: process.env.PHOENIX_ENDPOINT!,
+  endpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT!,
   apiKey: process.env.PHOENIX_API_KEY,
 
   // Batch processing configuration
@@ -233,7 +233,7 @@ Add custom attributes to all exported spans:
 
 ```typescript
 new ArizeExporter({
-  endpoint: process.env.PHOENIX_ENDPOINT!,
+  endpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT!,
   resourceAttributes: {
     'deployment.environment': process.env.NODE_ENV,
     'service.namespace': 'production',

package/.docs/docs/observability/tracing/exporters/braintrust.md

@@ -105,6 +105,43 @@ new BraintrustExporter({
 })
 ```
 
+## Attach traces to Braintrust evals
+
+When you run Mastra inside Braintrust `Eval()` or `logger.traced()`, pass the Braintrust logger and `currentSpan` resolver to the exporter. Import `currentSpan` from the same `braintrust` package instance that creates the eval or traced span.
+
+This helps Mastra attach its spans under the active Braintrust span when your app and `@mastra/braintrust` resolve different installed copies of the Braintrust SDK.
+
+```typescript
+import { currentSpan, initLogger } from 'braintrust'
+import { BraintrustExporter } from '@mastra/braintrust'
+
+const logger = initLogger({
+  projectName: 'my-project',
+  apiKey: process.env.BRAINTRUST_API_KEY,
+})
+
+const exporter = new BraintrustExporter({
+  braintrustLogger: logger,
+  currentSpan,
+})
+```
+
+Use the configured Mastra instance inside the Braintrust eval task. The `currentSpan` resolver above reads the active span created by `Eval()`.
+
+```typescript
+import { Eval } from 'braintrust'
+import { mastra } from '../mastra'
+
+await Eval('my-project', {
+  data: () => [{ input: 'Say hello', expected: 'Hello' }],
+  task: async input => {
+    const agent = mastra.getAgent('assistant')
+    return (await agent.generate(input)).text
+  },
+  scores: [],
+})
+```
+
 ## Querying Braintrust with returned `spanId`
 
 For Braintrust, use `spanId` as the root span identifier when searching for traces because Braintrust root-span queries are typically faster than trace-id queries.

package/.docs/docs/observability/tracing/exporters/langfuse.md

@@ -172,6 +172,27 @@ new LangfuseExporter({
 })
 ```
 
+## Scoping evaluators per agent
+
+Langfuse evaluators (such as LLM-as-a-Judge) can be filtered to run only against specific traces. The Mastra Langfuse exporter automatically scopes each trace to the agent or workflow that started it, so trace-level filters resolve to the right runs.
+
+For every trace whose root span is an `AGENT_RUN`, the exporter sets:
+
+- `langfuse.trace.name`: the agent name (or id, when no name is set)
+- `langfuse.trace.metadata.agentId`: the agent id
+- `langfuse.trace.metadata.agentName`: the agent name
+
+The same applies to `WORKFLOW_RUN` root spans, which set `langfuse.trace.metadata.workflowId` and `langfuse.trace.metadata.workflowName`.
+
+To scope an evaluator to a specific agent, configure either filter in Langfuse:
+
+- **Trace name**: equals the agent name (for example, `weather-agent`).
+- **Metadata**: `agentId` equals the agent id.
+
+The trace name dropdown in Langfuse evaluator filters lists every distinct value seen, so each agent appears as its own entry once it has produced at least one trace.
+
+If you set a custom `traceName` via `mastra.metadata.traceName`, your value takes precedence over the default agent name.
+
 ## Prompt linking
 
 You can link LLM generations to prompts stored in [Langfuse Prompt Management](https://langfuse.com/docs/prompt-management). This enables version tracking and metrics for your prompts.

package/.docs/docs/observability/tracing/exporters/{cloud.md → mastra-platform.md}

@@ -1,8 +1,10 @@
-# Cloud exporter
+# Mastra Platform exporter
 
-The `CloudExporter` sends traces, logs, metrics, scores, and feedback to the Mastra platform. Use it to route observability data from any Mastra app to a hosted project in the Mastra platform.
+The `MastraPlatformExporter` sends traces, logs, metrics, scores, and feedback to the Mastra platform. Use it to route observability data from any Mastra app to a hosted project in the Mastra platform.
 
-> **Self-hosted or standalone apps:** If you host your Mastra application on your own infrastructure (not on Mastra Platform), you still need a deployed Studio project to view traces, logs, and metrics. `CloudExporter` sends data to a Studio project, so one must exist before you can use it.
+> **Note:** `MastraPlatformExporter` was previously called `CloudExporter`. The original `CloudExporter` class is still exported from `@mastra/observability` for backward compatibility, but it is deprecated. New code should use `MastraPlatformExporter`.
+
+> **Self-hosted or standalone apps:** If you host your Mastra application on your own infrastructure (not on Mastra Platform), you still need a deployed Studio project to view traces, logs, and metrics. `MastraPlatformExporter` sends data to a Studio project, so one must exist before you can use it.
 >
 > 1. [Create a Mastra project](https://mastra.ai/guides/getting-started/quickstart) if you don't have one yet.
 > 2. [Deploy Studio](https://mastra.ai/docs/studio/deployment) to the Mastra platform with `mastra studio deploy`.
@@ -10,13 +12,13 @@ The `CloudExporter` sends traces, logs, metrics, scores, and feedback to the Mas
 
 ## Version compatibility
 
-- Use `CloudExporter` with `@mastra/observability@1.8.0` or later.
-- If you use `@mastra/observability@1.8.0` through `1.9.1`, set `MASTRA_CLOUD_TRACES_ENDPOINT=https://observability.mastra.ai` in addition to `MASTRA_CLOUD_ACCESS_TOKEN` and `MASTRA_PROJECT_ID`.
-- Starting in `@mastra/observability@1.9.2`, `CloudExporter` defaults to `https://observability.mastra.ai`, so `MASTRA_CLOUD_TRACES_ENDPOINT` is only required when you want to send telemetry to a different collector.
+- `MastraPlatformExporter` is available starting in `@mastra/observability@1.12.0`. In `1.8.0` through `1.11.x` the same exporter ships only as `CloudExporter`; the constructor signature and environment variables are identical.
+- In `@mastra/observability@1.8.0` through `1.9.1`, set `MASTRA_CLOUD_TRACES_ENDPOINT=https://observability.mastra.ai` in addition to `MASTRA_CLOUD_ACCESS_TOKEN` and `MASTRA_PROJECT_ID`.
+- Starting in `@mastra/observability@1.9.2`, the exporter defaults to `https://observability.mastra.ai`, so `MASTRA_CLOUD_TRACES_ENDPOINT` is only required when you want to send telemetry to a different collector.
 
 ## Quickstart
 
-To connect `CloudExporter`, create an access token, find the destination `projectId`, and add the exporter to your observability config.
+To connect `MastraPlatformExporter`, create an access token, find the destination `projectId`, and add the exporter to your observability config.
 
 ### 1. Create an access token
 
@@ -69,7 +71,7 @@ MASTRA_PROJECT_ID=<your-project-id>
 
 ### 3. Set your environment variables
 
-Set both values in your environment so `CloudExporter` can authenticate and route telemetry to the correct project:
+Set both values in your environment so `MastraPlatformExporter` can authenticate and route telemetry to the correct project:
 
 ```bash
 MASTRA_CLOUD_ACCESS_TOKEN=<your-cloud-access-token>
@@ -88,29 +90,29 @@ If you want to send telemetry somewhere other than Mastra platform, set `MASTRA_
 MASTRA_CLOUD_TRACES_ENDPOINT=https://collector.example.com
 ```
 
-When you pass a base origin, `CloudExporter` derives the matching publish URLs for traces, logs, metrics, scores, and feedback automatically.
+When you pass a base origin, `MastraPlatformExporter` derives the matching publish URLs for traces, logs, metrics, scores, and feedback automatically.
 
-### 4. Enable `CloudExporter`
+### 4. Enable `MastraPlatformExporter`
 
-The following example demonstrates how to add `CloudExporter` to your observability config:
+The following example demonstrates how to add `MastraPlatformExporter` to your observability config:
 
 ```ts
 import { Mastra } from '@mastra/core'
-import { Observability, CloudExporter } from '@mastra/observability'
+import { Observability, MastraPlatformExporter } from '@mastra/observability'
 
 export const mastra = new Mastra({
   observability: new Observability({
     configs: {
       production: {
         serviceName: 'api-server',
-        exporters: [new CloudExporter()],
+        exporters: [new MastraPlatformExporter()],
       },
     },
   }),
 })
 ```
 
-Set `serviceName` on the observability config, not on `CloudExporter` itself.
+Set `serviceName` on the observability config, not on `MastraPlatformExporter` itself.
 
 Use a stable `serviceName` value. In Studio, traces can be filtered by **Deployments → Service Name**, so a consistent name makes traces easier to find.
 
@@ -119,23 +121,23 @@ Visit [Observability configuration reference](https://mastra.ai/reference/observ
 If you prefer, rely entirely on environment variables:
 
 ```ts
-new CloudExporter()
+new MastraPlatformExporter()
 ```
 
-With `MASTRA_CLOUD_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` set, `CloudExporter` sends data to the Mastra platform project you configured. If you also set `MASTRA_CLOUD_TRACES_ENDPOINT`, it sends data to that collector instead.
+With `MASTRA_CLOUD_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` set, `MastraPlatformExporter` sends data to the Mastra platform project you configured. If you also set `MASTRA_CLOUD_TRACES_ENDPOINT`, it sends data to that collector instead.
 
-> **Note:** Visit [CloudExporter reference](https://mastra.ai/reference/observability/tracing/exporters/cloud-exporter) for the full list of configuration options.
+> **Note:** Visit [MastraPlatformExporter reference](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter) for the full list of configuration options.
 
 ## Recommended configuration
 
-Include `DefaultExporter` if you also want to inspect local traces in Studio or persist observability data to your configured storage.
+Include `MastraStorageExporter` if you also want to inspect local traces in Studio or persist observability data to your configured storage.
 
 ```ts
 import { Mastra } from '@mastra/core'
 import {
   Observability,
-  DefaultExporter,
-  CloudExporter,
+  MastraStorageExporter,
+  MastraPlatformExporter,
   SensitiveDataFilter,
 } from '@mastra/observability'
 
@@ -144,7 +146,7 @@ export const mastra = new Mastra({
     configs: {
       default: {
         serviceName: 'mastra',
-        exporters: [new DefaultExporter(), new CloudExporter()],
+        exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
         spanOutputProcessors: [new SensitiveDataFilter()],
       },
     },
@@ -154,7 +156,7 @@ export const mastra = new Mastra({
 
 ## Complete configuration
 
-`CloudExporter` defaults to Mastra platform. If you want to send telemetry to a different collector, set `MASTRA_CLOUD_TRACES_ENDPOINT` in your environment or pass `endpoint` in code.
+`MastraPlatformExporter` defaults to Mastra platform. If you want to send telemetry to a different collector, set `MASTRA_CLOUD_TRACES_ENDPOINT` in your environment or pass `endpoint` in code.
 
 ```bash
 MASTRA_CLOUD_TRACES_ENDPOINT=https://collector.example.com
@@ -163,7 +165,7 @@ MASTRA_CLOUD_TRACES_ENDPOINT=https://collector.example.com
 The following example demonstrates how to override the collector endpoint and batching behavior in code:
 
 ```ts
-new CloudExporter({
+new MastraPlatformExporter({
   endpoint: 'https://collector.example.com',
   maxBatchSize: 1000,
   maxBatchWaitMs: 5000,
@@ -173,7 +175,7 @@ new CloudExporter({
 
 ## Viewing data in Mastra Studio
 
-After you enable `CloudExporter`, open your project in [Mastra Studio](https://projects.mastra.ai) to inspect the exported data.
+After you enable `MastraPlatformExporter`, open your project in [Mastra Studio](https://projects.mastra.ai) to inspect the exported data.
 
 - Open the project you set `MASTRA_PROJECT_ID` to and select **Open Studio**.
 - In Studio, go to **Traces** to inspect agent and workflow traces.
@@ -184,7 +186,7 @@ When you deploy with Mastra Studio, set **Deployment → Service Name** to a sta
 
 ## Performance
 
-> **Info:** CloudExporter uses batching to optimize network usage. Events are buffered and sent in batches, reducing overhead while maintaining near real-time visibility.
+> **Info:** MastraPlatformExporter uses batching to optimize network usage. Events are buffered and sent in batches, reducing overhead while maintaining near real-time visibility.
 
 ### Batching behavior
 
@@ -196,4 +198,4 @@ When you deploy with Mastra Studio, set **Deployment → Service Name** to a sta
 ## Related
 
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
-- [DefaultExporter](https://mastra.ai/docs/observability/tracing/exporters/default)
+- [MastraStorageExporter](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage)