@mastra/mcp-docs-server 1.0.0-beta.0 → 1.0.0-beta.10

package/.docs/raw/observability/tracing/bridges/otel.mdx

@@ -0,0 +1,200 @@
+---
+title: "OpenTelemetry Bridge | Tracing | Observability"
+description: "Integrate Mastra tracing with existing OpenTelemetry infrastructure"
+---
+
+# OpenTelemetry Bridge
+
+:::warning
+
+The OpenTelemetry Bridge is currently **experimental**. APIs and configuration options may change in future releases.
+
+:::
+
+The OpenTelemetry (OTEL) Bridge enables bidirectional integration between Mastra's tracing system and existing OpenTelemetry infrastructure. Unlike exporters that send trace data to external platforms, the bridge creates native OTEL spans that participate in your distributed tracing context.
+
+:::info Looking to send traces without existing OTEL infrastructure?
+
+If you don't have existing OpenTelemetry instrumentation, the [OpenTelemetry Exporter](/docs/v1/observability/tracing/exporters/otel) may be simpler — it sends traces directly without requiring an OTEL SDK setup.
+
+:::
+
+## When to Use the Bridge
+
+Use the OtelBridge when you:
+
+- Have existing OTEL instrumentation in your application (HTTP servers, database clients, etc.)
+- Want Mastra operations to appear as child spans of your existing OTEL traces
+- Need OTEL-instrumented code inside Mastra tools to maintain proper parent-child relationships
+- Are building a distributed system where trace context must propagate across services
+
+## How It Works
+
+The OtelBridge provides two-way integration:
+
+**From OTEL to Mastra:**
+- Reads from OTEL ambient context (AsyncLocalStorage) automatically
+- Inherits trace ID and parent span ID from active OTEL spans
+- Respects OTEL sampling decisions — if a trace is not sampled, Mastra won't create spans for it
+- No manual trace ID passing required when OTEL auto-instrumentation is active
+
+**From Mastra to OTEL:**
+- 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
+
+## Installation
+
+```bash npm2yarn
+npm install @mastra/otel-bridge
+```
+
+The bridge works with your existing OpenTelemetry setup. Depending on your configuration, you may also need some of these packages:
+
+- `@opentelemetry/sdk-node` - Core Node.js SDK for OTEL
+- `@opentelemetry/auto-instrumentations-node` - Auto-instrumentation for common libraries
+- `@opentelemetry/exporter-trace-otlp-proto` - OTLP exporter (Protobuf over HTTP)
+- `@opentelemetry/exporter-trace-otlp-http` - OTLP exporter (JSON over HTTP)
+- `@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.)
+
+## Configuration
+
+Using the OtelBridge requires two steps:
+
+1. Configure OpenTelemetry instrumentation in your application
+2. Add the OtelBridge to your Mastra observability config
+
+### Step 1: OpenTelemetry Instrumentation
+
+Create an instrumentation file that initializes OTEL. This must run before your application code:
+
+```typescript title="instrumentation.ts" showLineNumbers copy
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { W3CTraceContextPropagator } from "@opentelemetry/core";
+
+const sdk = new NodeSDK({
+  serviceName: "my-service",
+  spanProcessors: [
+    new BatchSpanProcessor(
+      new OTLPTraceExporter({
+        url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || "http://localhost:4318/v1/traces",
+      })
+    ),
+  ],
+  instrumentations: [getNodeAutoInstrumentations()],
+  textMapPropagator: new W3CTraceContextPropagator(),
+});
+
+sdk.start();
+
+export { sdk };
+```
+
+### Step 2: Mastra Configuration
+
+Add the OtelBridge to your Mastra observability config:
+
+```typescript title="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core";
+import { Observability } from "@mastra/observability";
+import { OtelBridge } from "@mastra/otel-bridge";
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: "my-service",
+        bridge: new OtelBridge(),
+      },
+    },
+  }),
+  agents: {
+    /* your agents */
+  },
+});
+```
+
+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.
+
+### Running Your Application
+
+Use the `--import` flag to ensure instrumentation loads before your application:
+
+```bash
+tsx --import ./instrumentation.ts ./src/index.ts
+```
+
+## Semantic Conventions
+
+The OtelBridge exports Mastra spans using [OpenTelemetry Semantic Conventions for GenAI v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai). This includes standardized span names (`chat {model}`, `execute_tool {tool_name}`, etc.) and attributes (`gen_ai.usage.input_tokens`, `gen_ai.request.model`, etc.).
+
+For details on span naming and attributes, see the [OpenTelemetry Exporter semantic conventions](/docs/v1/observability/tracing/exporters/otel#opentelemetry-semantic-conventions).
+
+## Trace Hierarchy
+
+With the OtelBridge, your traces maintain proper hierarchy across OTEL and Mastra boundaries:
+
+```
+HTTP POST /api/chat (from Hono middleware)
+└── agent.assistant (from Mastra via OtelBridge)
+    ├── chat gpt-4o (LLM call)
+    ├── tool.execute search (tool execution)
+    │   └── HTTP GET api.example.com (from OTEL auto-instrumentation)
+    └── chat gpt-4o (follow-up LLM call)
+```
+
+## Multi-Service Distributed Tracing
+
+The OtelBridge enables trace propagation across service boundaries. When Service A calls Service B via HTTP, trace context propagates automatically:
+
+```
+Service A: HTTP POST /api/process
+└── HTTP POST service-b/api/analyze (outgoing call)
+
+Service B: HTTP POST /api/analyze (incoming call - same trace!)
+└── agent.analyzer (Mastra agent inherits trace context)
+    └── chat gpt-4o
+```
+
+Both services must have:
+1. OTEL instrumentation configured
+2. W3C Trace Context propagator enabled
+3. Mastra with OtelBridge configured
+
+## Using Tags
+
+Tags help you categorize and filter traces in your OTEL backend. Add tags when executing agents or workflows:
+
+```typescript
+const result = await agent.generate({
+  messages: [{ role: "user", content: "Hello" }],
+  tracingOptions: {
+    tags: ["production", "experiment-v2", "user-request"],
+  },
+});
+```
+
+Tags are exported as a JSON string in the `mastra.tags` span attribute for broad backend compatibility. Common use cases include:
+
+- Environment labels: `"production"`, `"staging"`
+- Experiment tracking: `"experiment-v1"`, `"control-group"`
+- Priority levels: `"priority-high"`, `"batch-job"`
+
+## Troubleshooting
+
+If traces aren't appearing or connecting as expected:
+
+- Verify OTEL SDK is initialized before Mastra (use `--import` flag or import at top of entry point)
+- Ensure the OtelBridge is added to your observability config
+- Check that your OTEL backend is running and accessible
+
+## Related
+
+- [Tracing Overview](/docs/v1/observability/tracing/overview)
+- [OpenTelemetry Exporter](/docs/v1/observability/tracing/exporters/otel) - For sending traces to OTEL backends
+- [OtelBridge Reference](/reference/v1/observability/tracing/bridges/otel) - API documentation

package/.docs/raw/observability/tracing/exporters/arize.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Arize Exporter | Tracing | Observability | Mastra Docs"
+title: "Arize Exporter | Tracing | Observability"
 description: "Send traces to Arize Phoenix or Arize AX using OpenTelemetry and OpenInference"
 ---
 
@@ -10,7 +10,7 @@ description: "Send traces to Arize Phoenix or Arize AX using OpenTelemetry and O
 ## Installation
 
 ```bash npm2yarn
-npm install @mastra/arize
+npm install @mastra/arize@beta
 ```
 
 ## Configuration
@@ -182,13 +182,49 @@ new ArizeExporter({
 });
 ```
 
+### Custom metadata
+
+Non-reserved span attributes are serialized into the OpenInference `metadata` payload and surface in Arize/Phoenix. You can add them via `tracingOptions.metadata`:
+
+```ts
+await agent.generate(input, {
+  tracingOptions: {
+    metadata: {
+      companyId: "acme-co",
+      tier: "enterprise",
+    },
+  },
+});
+```
+
+Reserved fields such as `input`, `output`, `sessionId`, thread/user IDs, and OpenInference IDs are excluded automatically.
+
 ## OpenInference Semantic Conventions
 
 This exporter implements the [OpenInference Semantic Conventions](https://github.com/Arize-ai/openinference/tree/main/spec) for generative AI applications, providing standardized trace structure across different observability platforms.
 
+## Using Tags
+
+Tags help you categorize and filter traces in Phoenix and Arize AX. Add tags when executing agents or workflows:
+
+```typescript
+const result = await agent.generate({
+  messages: [{ role: "user", content: "Hello" }],
+  tracingOptions: {
+    tags: ["production", "experiment-v2", "user-request"],
+  },
+});
+```
+
+Tags appear as the `tag.tags` attribute following OpenInference conventions and can be used to filter and search traces. Common use cases include:
+
+- Environment labels: `"production"`, `"staging"`
+- Experiment tracking: `"experiment-v1"`, `"control-group"`
+- Priority levels: `"priority-high"`, `"batch-job"`
+
 ## Related
 
-- [Tracing Overview]/docs/v1/observability/tracing/overview)
+- [Tracing Overview](/docs/v1/observability/tracing/overview)
 - [Phoenix Documentation](https://docs.arize.com/phoenix)
 - [Arize AX Documentation](https://docs.arize.com/)
 - [OpenInference Specification](https://github.com/Arize-ai/openinference/tree/main/spec)

package/.docs/raw/observability/tracing/exporters/braintrust.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Braintrust Exporter | Tracing | Observability | Mastra Docs"
+title: "Braintrust Exporter | Tracing | Observability"
 description: "Send traces to Braintrust for evaluation and monitoring"
 ---
 
@@ -10,7 +10,7 @@ description: "Send traces to Braintrust for evaluation and monitoring"
 ## Installation
 
 ```bash npm2yarn
-npm install @mastra/braintrust
+npm install @mastra/braintrust@beta
 ```
 
 ## Configuration
@@ -65,7 +65,26 @@ new BraintrustExporter({
 });
 ```
 
+## Using Tags
+
+Tags help you categorize and filter traces in the Braintrust dashboard. Add tags when executing agents or workflows:
+
+```typescript
+const result = await agent.generate({
+  messages: [{ role: "user", content: "Hello" }],
+  tracingOptions: {
+    tags: ["production", "experiment-v2", "user-request"],
+  },
+});
+```
+
+Tags appear in Braintrust's trace view and can be used to filter and search traces. Common use cases include:
+
+- Environment labels: `"production"`, `"staging"`
+- Experiment tracking: `"experiment-v1"`, `"control-group"`
+- Priority levels: `"priority-high"`, `"batch-job"`
+
 ## Related
 
-- [Tracing Overview]/docs/v1/observability/tracing/overview)
+- [Tracing Overview](/docs/v1/observability/tracing/overview)
 - [Braintrust Documentation](https://www.braintrust.dev/docs)

package/.docs/raw/observability/tracing/exporters/cloud.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Cloud Exporter | Tracing | Observability | Mastra Docs"
+title: "Cloud Exporter | Tracing | Observability"
 description: "Send traces to Mastra Cloud for production monitoring"
 ---
 
@@ -110,6 +110,6 @@ CloudExporter uses intelligent batching to optimize network usage. Traces are bu
 
 ## Related
 
-- [Tracing Overview]/docs/v1/observability/tracing/overview)
-- [DefaultExporter]/docs/v1/observability/tracing/exporters/default)
-- [Mastra Cloud Documentation](https://cloud.mastra.ai/docs)
+- [Tracing Overview](/docs/v1/observability/tracing/overview)
+- [DefaultExporter](/docs/v1/observability/tracing/exporters/default)
+- [Mastra Cloud Documentation](/docs/v1/deployment/mastra-cloud/overview)

package/.docs/raw/observability/tracing/exporters/default.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Default Exporter | Tracing | Observability | Mastra Docs"
+title: "Default Exporter | Tracing | Observability"
 description: "Store traces locally for development and debugging"
 ---
 
@@ -102,8 +102,8 @@ If you set the strategy to `'auto'`, the `DefaultExporter` automatically selects
 
 | Storage Provider                                | Preferred Strategy | Supported Strategies                      | Notes                                 |
 | ----------------------------------------------- | ------------------ | ----------------------------------------- | ------------------------------------- |
-| **[LibSQL]/reference/v1/storage/libsql)**         | batch-with-updates | realtime, batch-with-updates, insert-only | Default storage, good for development |
-| **[PostgreSQL]/reference/v1/storage/postgresql)** | batch-with-updates | batch-with-updates, insert-only           | Recommended for production            |
+| **[LibSQL](/reference/v1/storage/libsql)**         | batch-with-updates | realtime, batch-with-updates, insert-only | Default storage, good for development |
+| **[PostgreSQL](/reference/v1/storage/postgresql)** | batch-with-updates | batch-with-updates, insert-only           | Recommended for production            |
 
 ### Strategy Benefits
 
@@ -158,6 +158,6 @@ new DefaultExporter({
 
 ## Related
 
-- [Tracing Overview]/docs/v1/observability/tracing/overview)
-- [CloudExporter]/docs/v1/observability/tracing/exporters/cloud)
-- [Storage Configuration]/docs/v1/server-db/storage)
+- [Tracing Overview](/docs/v1/observability/tracing/overview)
+- [CloudExporter](/docs/v1/observability/tracing/exporters/cloud)
+- [Storage Configuration](/docs/v1/server-db/storage)

package/.docs/raw/observability/tracing/exporters/langfuse.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Langfuse Exporter | Tracing | Observability | Mastra Docs"
+title: "Langfuse Exporter | Tracing | Observability"
 description: "Send traces to Langfuse for LLM observability and analytics"
 ---
 
@@ -10,7 +10,7 @@ description: "Send traces to Langfuse for LLM observability and analytics"
 ## Installation
 
 ```bash npm2yarn
-npm install @mastra/langfuse
+npm install @mastra/langfuse@beta
 ```
 
 ## Configuration
@@ -107,7 +107,90 @@ new LangfuseExporter({
 });
 ```
 
+## 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.
+
+### Using the Helper (Recommended)
+
+Use `withLangfusePrompt` with `buildTracingOptions` for the cleanest API:
+
+```typescript title="src/agents/support-agent.ts"
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+import { buildTracingOptions } from "@mastra/observability";
+import { withLangfusePrompt } from "@mastra/langfuse";
+import { Langfuse } from "langfuse";
+
+const langfuse = new Langfuse({
+  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
+  secretKey: process.env.LANGFUSE_SECRET_KEY!,
+});
+
+// Fetch the prompt from Langfuse Prompt Management
+const prompt = await langfuse.getPrompt("customer-support");
+
+export const supportAgent = new Agent({
+  name: "support-agent",
+  instructions: prompt.prompt, // Use the prompt text from Langfuse
+  model: openai("gpt-4o"),
+  defaultGenerateOptions: {
+    tracingOptions: buildTracingOptions(withLangfusePrompt(prompt)),
+## Using Tags
+
+Tags help you categorize and filter traces in the Langfuse dashboard. Add tags when executing agents or workflows:
+
+```typescript
+const result = await agent.generate({
+  messages: [{ role: "user", content: "Hello" }],
+  tracingOptions: {
+    tags: ["production", "experiment-v2", "user-request"],
+  },
+});
+```
+
+The `withLangfusePrompt` helper automatically extracts `name`, `version`, and `id` from the Langfuse prompt object.
+
+### Manual Fields
+
+You can also pass manual fields if you're not using the Langfuse SDK:
+
+```typescript
+const tracingOptions = buildTracingOptions(
+  withLangfusePrompt({ name: "my-prompt", version: 1 }),
+);
+
+// Or with just an ID
+const tracingOptions = buildTracingOptions(
+  withLangfusePrompt({ id: "prompt-uuid-12345" }),
+);
+```
+
+### Prompt Object Fields
+
+The prompt object supports these fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | The prompt name in Langfuse |
+| `version` | number | The prompt version number |
+| `id` | string | The prompt UUID for direct linking |
+
+You can link prompts using either:
+- `id` alone (the UUID uniquely identifies a prompt version)
+- `name` + `version` together
+- All three fields
+
+When set on a `MODEL_GENERATION` span, the Langfuse exporter automatically links the generation to the corresponding prompt.
+Tags appear in Langfuse's trace view and can be used to filter and search traces. Common use cases include:
+
+- Environment labels: `"production"`, `"staging"`
+- Experiment tracking: `"experiment-v1"`, `"control-group"`
+- Priority levels: `"priority-high"`, `"batch-job"`
+- User segments: `"beta-user"`, `"enterprise"`
+
 ## Related
 
-- [Tracing Overview]/docs/v1/observability/tracing/overview)
+- [Tracing Overview](/docs/v1/observability/tracing/overview)
 - [Langfuse Documentation](https://langfuse.com/docs)
+- [Langfuse Prompt Management](https://langfuse.com/docs/prompt-management)

package/.docs/raw/observability/tracing/exporters/langsmith.mdx

@@ -1,5 +1,5 @@
 ---
-title: "LangSmith Exporter | Tracing | Observability | Mastra Docs"
+title: "LangSmith Exporter | Tracing | Observability"
 description: "Send traces to LangSmith for LLM observability and evaluation"
 ---
 
@@ -10,7 +10,7 @@ description: "Send traces to LangSmith for LLM observability and evaluation"
 ## Installation
 
 ```bash npm2yarn
-npm install @mastra/langsmith
+npm install @mastra/langsmith@beta
 ```
 
 ## Configuration
@@ -23,6 +23,7 @@ npm install @mastra/langsmith
 
 ```bash title=".env"
 LANGSMITH_API_KEY=ls-xxxxxxxxxxxx
+LANGCHAIN_PROJECT=my-project  # Optional: default project for traces
 LANGSMITH_BASE_URL=https://api.smith.langchain.com  # Optional for self-hosted
 ```
 
@@ -60,6 +61,7 @@ new LangSmithExporter({
 
   // Optional settings
   apiUrl: process.env.LANGSMITH_BASE_URL, // Default: https://api.smith.langchain.com
+  projectName: "my-project", // Project to send traces to (overrides LANGCHAIN_PROJECT env var)
   callerOptions: {
     // HTTP client options
     timeout: 30000, // Request timeout in ms
@@ -73,7 +75,17 @@ new LangSmithExporter({
 });
 ```
 
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `LANGSMITH_API_KEY` | Your LangSmith API key (required) |
+| `LANGCHAIN_PROJECT` | Default project name for traces (optional, defaults to "default") |
+| `LANGSMITH_BASE_URL` | API URL for self-hosted instances (optional) |
+
+The `projectName` config option takes precedence over the `LANGCHAIN_PROJECT` environment variable, allowing you to programmatically route traces to different projects.
+
 ## Related
 
-- [Tracing Overview]/docs/v1/observability/tracing/overview)
+- [Tracing Overview](/docs/v1/observability/tracing/overview)
 - [LangSmith Documentation](https://docs.smith.langchain.com/)