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

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"
 ---
 
@@ -182,10 +182,46 @@ 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)

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"
 ---
 
@@ -65,6 +65,25 @@ 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)

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"
 ---
 
@@ -112,4 +112,4 @@ CloudExporter uses intelligent batching to optimize network usage. Traces are bu
 
 - [Tracing Overview](/docs/v1/observability/tracing/overview)
 - [DefaultExporter](/docs/v1/observability/tracing/exporters/default)
-- [Mastra Cloud Documentation](https://cloud.mastra.ai/docs)
+- [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"
 ---
 

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"
 ---
 
@@ -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)
 - [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"
 ---
 
@@ -23,6 +23,7 @@ npm install @mastra/langsmith@beta
 
 ```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,6 +75,16 @@ 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)

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

@@ -1,29 +1,29 @@
 ---
-title: "OpenTelemetry Exporter | Tracing | Observability | Mastra Docs"
+title: "OpenTelemetry Exporter | Tracing | Observability"
 description: "Send traces to any OpenTelemetry-compatible observability platform"
 ---
 
 # OpenTelemetry Exporter
 
-:::warning
+The OpenTelemetry (OTEL) exporter sends your traces to any OTEL-compatible observability platform using standardized [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/). This ensures broad compatibility with platforms like Datadog, New Relic, SigNoz, MLflow, Dash0, Traceloop, Laminar, and more.
 
-The OpenTelemetry exporter is currently **experimental**. APIs and configuration options may change in future releases.
+:::info Looking for bidirectional OTEL integration?
 
-:::
+If you have existing OpenTelemetry instrumentation and want Mastra traces to inherit context from active OTEL spans, see the [OpenTelemetry Bridge](/docs/v1/observability/tracing/bridges/otel) instead.
 
-The OpenTelemetry (OTEL) exporter sends your traces to any OTEL-compatible observability platform using standardized [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/). This ensures broad compatibility with platforms like Datadog, New Relic, SigNoz, Dash0, Traceloop, Laminar, and more.
+:::
 
 ## Installation
 
 Each provider requires specific protocol packages. Install the base exporter plus the protocol package for your provider:
 
-### For HTTP/Protobuf Providers (SigNoz, New Relic, Laminar)
+### For HTTP/Protobuf Providers (SigNoz, New Relic, Laminar, MLflow)
 
 ```bash npm2yarn
 npm install @mastra/otel-exporter@beta @opentelemetry/exporter-trace-otlp-proto
 ```
 
-### For gRPC Providers (Dash0)
+### For gRPC Providers (Dash0, Datadog)
 
 ```bash npm2yarn
 npm install @mastra/otel-exporter@beta @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
@@ -37,6 +37,25 @@ npm install @mastra/otel-exporter@beta @opentelemetry/exporter-trace-otlp-http
 
 ## Provider Configurations
 
+
+### MLflow
+
+[MLflow](https://mlflow.org/docs/latest/genai/tracing/integrations/listing/mastra) supports native Mastra tracing through its OTLP endpoint at `/v1/traces`. Use the `custom` provider with HTTP/Protobuf and include the experiment header so traces land in the correct MLflow experiment:
+
+```typescript title="src/mastra/index.ts"
+new OtelExporter({
+  provider: {
+    custom: {
+      endpoint: `${process.env.MLFLOW_TRACKING_URI}/v1/traces`,
+      protocol: "http/protobuf",
+      headers: {
+        "x-mlflow-experiment-id": process.env.MLFLOW_EXPERIMENT_ID,
+      },
+    },
+  },
+})
+```
+
 ### Dash0
 
 [Dash0](https://www.dash0.com/) provides real-time observability with automatic insights.
@@ -139,6 +158,72 @@ new OtelExporter({
 });
 ```
 
+### Datadog
+
+[Datadog](https://www.datadoghq.com/) APM provides application performance monitoring with distributed tracing. To send traces to Datadog via OTLP, you need the Datadog Agent running with OTLP ingestion enabled.
+
+Datadog uses gRPC for OTLP ingestion, which requires explicit imports and bundler configuration to work correctly:
+
+```typescript title="src/mastra/index.ts"
+// Explicitly import gRPC dependencies for the bundler
+import "@grpc/grpc-js";
+import "@opentelemetry/exporter-trace-otlp-grpc";
+import { Mastra } from "@mastra/core";
+import { Observability } from "@mastra/observability";
+import { OtelExporter, type ExportProtocol } from "@mastra/otel-exporter";
+
+export const mastra = new Mastra({
+  // Add grpc-js to externals so it's handled at runtime
+  bundler: {
+    externals: ["@grpc/grpc-js"],
+  },
+
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: "my-service",
+        exporters: [
+          new OtelExporter({
+            provider: {
+              custom: {
+                endpoint:
+                  process.env.OTEL_EXPORTER_OTLP_ENDPOINT ||
+                  "http://localhost:4317",
+                protocol: (process.env.OTEL_EXPORTER_OTLP_PROTOCOL ||
+                  "grpc") as ExportProtocol,
+                headers: {},
+              },
+            },
+          }),
+        ],
+      },
+    },
+  }),
+});
+```
+
+:::info
+
+The Datadog Agent must be configured with OTLP ingestion enabled. Add the following to your `datadog.yaml`:
+
+```yaml
+otlp_config:
+  receiver:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+```
+
+The default OTLP endpoint is `http://localhost:4317` when running the Datadog Agent locally.
+
+:::
+
+:::warning
+
+The explicit imports of `@grpc/grpc-js` and `@opentelemetry/exporter-trace-otlp-grpc` at the top of the file, along with the `bundler.externals` configuration, are required for the gRPC transport to work correctly. Without these, you may encounter connection issues.
+
+:::
+
 ### Custom/Generic OTEL Endpoints
 
 For other OTEL-compatible platforms or custom collectors:
@@ -179,33 +264,26 @@ new OtelExporter({
 
 ## OpenTelemetry Semantic Conventions
 
-The exporter follows [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/), ensuring compatibility with observability platforms:
+The exporter follows [OpenTelemetry Semantic Conventions for GenAI v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai), ensuring compatibility with observability platforms:
 
 ### Span Naming
 
-- **LLM Operations**: `chat {model}` or `tool_selection {model}`
-- **Tool Execution**: `tool.execute {tool_name}`
-- **Agent Runs**: `agent.{agent_id}`
-- **Workflow Runs**: `workflow.{workflow_id}`
+- **LLM Operations**: `chat {model}`
+- **Tool Execution**: `execute_tool {tool_name}`
+- **Agent Runs**: `invoke_agent {agent_id}`
+- **Workflow Runs**: `invoke_workflow {workflow_id}`
 
 ### Key Attributes
 
 - `gen_ai.operation.name` - Operation type (chat, tool.execute, etc.)
-- `gen_ai.system` - AI provider (openai, anthropic, etc.)
+- `gen_ai.provider.name` - AI provider (openai, anthropic, etc.)
 - `gen_ai.request.model` - Model identifier
+- `gen_ai.input.messages` - Chat history provided to the model
+- `gen_ai.output.messages` - Messages returned by the model
 - `gen_ai.usage.input_tokens` - Number of input tokens
 - `gen_ai.usage.output_tokens` - Number of output tokens
 - `gen_ai.request.temperature` - Sampling temperature
-- `gen_ai.response.finish_reasons` - Completion reason
-
-## Buffering Strategy
-
-The exporter buffers spans until a trace is complete:
-
-1. Collects all spans for a trace
-2. Waits 5 seconds after root span completes
-3. Exports complete trace with preserved parent-child relationships
-4. Ensures no orphaned spans
+- `gen_ai.response.finish_reasons` - Completion reasons
 
 ## Protocol Selection Guide
 
@@ -214,6 +292,7 @@ Choose the right protocol package based on your provider:
 | Provider  | Protocol      | Required Package                           |
 | --------- | ------------- | ------------------------------------------ |
 | Dash0     | gRPC          | `@opentelemetry/exporter-trace-otlp-grpc`  |
+| Datadog   | gRPC          | `@opentelemetry/exporter-trace-otlp-grpc`  |
 | SigNoz    | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
 | New Relic | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
 | Traceloop | HTTP/JSON     | `@opentelemetry/exporter-trace-otlp-http`  |
@@ -245,10 +324,29 @@ Install the suggested package for your provider.
 1. **Wrong protocol package**: Verify you installed the correct exporter for your provider
 2. **Invalid endpoint**: Check endpoint format matches provider requirements
 3. **Authentication failures**: Verify API keys and headers are correct
-4. **No traces appearing**: Check that traces complete (root span must end)
+
+## Using Tags
+
+Tags help you categorize and filter traces in your observability platform. 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"`
 
 ## Related
 
 - [Tracing Overview](/docs/v1/observability/tracing/overview)
-- [OpenTelemetry GenAI Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
+- [OpenTelemetry Bridge](/docs/v1/observability/tracing/bridges/otel)
+- [OpenTelemetry Semantic Conventions for GenAI v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai)
 - [OTEL Exporter Reference](/reference/v1/observability/tracing/exporters/otel)

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

@@ -0,0 +1,127 @@
+---
+title: "PostHog Exporter | Tracing | Observability"
+description: "Send traces to PostHog for AI observability and analytics"
+---
+
+# PostHog Exporter
+
+[PostHog](https://posthog.com/) is an analytics platform with AI observability features for monitoring LLM applications. The PostHog exporter sends your traces to PostHog as structured events, providing insights into token usage, costs, latency, and conversation flows.
+
+## Installation
+
+```bash npm2yarn
+npm install @mastra/posthog@beta
+```
+
+## Configuration
+
+### Prerequisites
+
+1. **PostHog Account**: Sign up at [posthog.com](https://posthog.com/)
+2. **Project API Key**: Get your project API key from PostHog Settings → Project API Key
+3. **Environment Variables**: Set your credentials
+
+```bash title=".env"
+POSTHOG_API_KEY=phc_xxxxxxxxxxxxxxxx
+POSTHOG_HOST=https://us.i.posthog.com  # Optional: EU region or self-hosted URL
+```
+
+### Basic Setup
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { Observability } from "@mastra/observability";
+import { PosthogExporter } from "@mastra/posthog";
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      posthog: {
+        serviceName: "my-service",
+        exporters: [
+          new PosthogExporter({
+            apiKey: process.env.POSTHOG_API_KEY,
+          }),
+        ],
+      },
+    },
+  }),
+});
+```
+
+## Configuration Options
+
+### Complete Configuration
+
+```typescript
+new PosthogExporter({
+  // Required credentials
+  apiKey: process.env.POSTHOG_API_KEY!,
+
+  // Optional settings
+  host: "https://us.i.posthog.com", // Default: US region
+  // or "https://eu.i.posthog.com" for EU region
+  // or your self-hosted URL
+
+  // Batching configuration
+  flushAt: 20, // Batch size (default: 20)
+  flushInterval: 10000, // Flush interval in ms (default: 10000)
+  serverless: false, // Serverless mode: flushAt=10, flushInterval=2000
+
+  // User identification
+  defaultDistinctId: "anonymous", // Fallback if no userId in metadata
+
+  // Privacy settings
+  enablePrivacyMode: false, // Excludes input/output from generation events
+
+  // Diagnostic logging
+  logLevel: "info", // debug | info | warn | error
+});
+```
+
+### Serverless Mode
+
+Optimized batching for serverless environments:
+
+```typescript
+new PosthogExporter({
+  apiKey: process.env.POSTHOG_API_KEY!,
+  serverless: true, // Configures smaller batches for faster flushing
+});
+```
+
+### Privacy Mode
+
+Exclude input/output data from generation events while preserving token metrics:
+
+```typescript
+new PosthogExporter({
+  apiKey: process.env.POSTHOG_API_KEY!,
+  enablePrivacyMode: true, // Removes $ai_input and $ai_output_choices
+});
+```
+
+## Using Tags
+
+Tags help you categorize and filter traces in PostHog's AI analytics. 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 added as event properties where the tag name is the key and the value is set to `true`. In PostHog's trace view, filter by a tag using the `is set` filter (e.g., "production is set" shows all traces with the production tag). 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)
+- [PostHog Documentation](https://posthog.com/docs)