@mastra/mcp-docs-server 1.0.0-beta.8 → 1.0.0

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

@@ -0,0 +1,89 @@
+---
+title: "Laminar Exporter | Tracing | Observability"
+description: "Send traces to Laminar for LLM observability, evaluation, and analysis"
+packages:
+  - "@mastra/laminar"
+  - "@mastra/core"
+  - "@mastra/observability"
+---
+
+# Laminar Exporter
+
+[Laminar](https://laminar.sh/) is an open-source platform for engineering LLM products. The Laminar exporter sends your Mastra traces to Laminar via OTLP/HTTP (protobuf), with Laminar-native span attributes for correct rendering (paths, inputs/outputs, tags, metadata).
+
+## Installation
+
+```bash npm2yarn
+npm install @mastra/laminar@beta
+```
+
+## Configuration
+
+### Prerequisites
+
+1. **Laminar Project**: Create/select a project in Laminar
+2. **Project API Key**: Copy from Laminar Project Settings
+3. **Environment Variables**: Set your credentials
+
+```bash title=".env"
+# Required
+LMNR_PROJECT_API_KEY=lmnr_...
+
+# Optional
+LMNR_BASE_URL=https://api.lmnr.ai
+LAMINAR_ENDPOINT=https://api.lmnr.ai/v1/traces
+```
+
+### Zero-Config Setup
+
+With environment variables set, use the exporter with no configuration:
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { Observability } from "@mastra/observability";
+import { LaminarExporter } from "@mastra/laminar";
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      laminar: {
+        serviceName: "my-service",
+        exporters: [new LaminarExporter()],
+      },
+    },
+  }),
+});
+```
+
+### Explicit Configuration
+
+You can also pass credentials directly (takes precedence over environment variables):
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { Observability } from "@mastra/observability";
+import { LaminarExporter } from "@mastra/laminar";
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      laminar: {
+        serviceName: "my-service",
+        exporters: [
+          new LaminarExporter({
+            apiKey: process.env.LMNR_PROJECT_API_KEY!,
+            baseUrl: process.env.LMNR_BASE_URL, // Optional
+            endpoint: process.env.LAMINAR_ENDPOINT, // Optional
+            realtime: process.env.NODE_ENV === "development", // Optional
+          }),
+        ],
+      },
+    },
+  }),
+});
+```
+
+## Related
+
+- [Tracing Overview](/docs/v1/observability/tracing/overview)
+- [Laminar Documentation](https://docs.laminar.sh)

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

@@ -1,6 +1,10 @@
 ---
 title: "Langfuse Exporter | Tracing | Observability"
 description: "Send traces to Langfuse for LLM observability and analytics"
+packages:
+  - "@mastra/core"
+  - "@mastra/langfuse"
+  - "@mastra/observability"
 ---
 
 # Langfuse Exporter
@@ -27,7 +31,30 @@ LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxxxxxx
 LANGFUSE_BASE_URL=https://cloud.langfuse.com  # Or your self-hosted URL
 ```
 
-### Basic Setup
+### Zero-Config Setup
+
+With environment variables set, use the exporter with no configuration:
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { Observability } from "@mastra/observability";
+import { LangfuseExporter } from "@mastra/langfuse";
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      langfuse: {
+        serviceName: "my-service",
+        exporters: [new LangfuseExporter()],
+      },
+    },
+  }),
+});
+```
+
+### Explicit Configuration
+
+You can also pass credentials directly (takes precedence over environment variables):
 
 ```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
@@ -117,15 +144,12 @@ 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!,
-});
+// Reads credentials from LANGFUSE_SECRET_KEY, LANGFUSE_PUBLIC_KEY, LANGFUSE_BASE_URL env vars
+const langfuse = new Langfuse();
 
 // Fetch the prompt from Langfuse Prompt Management
 const prompt = await langfuse.getPrompt("customer-support");
@@ -133,18 +157,9 @@ 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"),
+  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"],
   },
 });
 ```
@@ -182,12 +197,6 @@ You can link prompts using either:
 - 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
 

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

@@ -1,6 +1,10 @@
 ---
 title: "LangSmith Exporter | Tracing | Observability"
 description: "Send traces to LangSmith for LLM observability and evaluation"
+packages:
+  - "@mastra/core"
+  - "@mastra/langsmith"
+  - "@mastra/observability"
 ---
 
 # LangSmith Exporter
@@ -22,12 +26,38 @@ npm install @mastra/langsmith@beta
 3. **Environment Variables**: Set your credentials
 
 ```bash title=".env"
+# Required
 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
+
+# Optional
+LANGCHAIN_PROJECT=my-project  # Default project for traces
+LANGSMITH_BASE_URL=https://api.smith.langchain.com  # For self-hosted
+```
+
+### Zero-Config Setup
+
+With environment variables set, use the exporter with no configuration:
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { Observability } from "@mastra/observability";
+import { LangSmithExporter } from "@mastra/langsmith";
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      langsmith: {
+        serviceName: "my-service",
+        exporters: [new LangSmithExporter()],
+      },
+    },
+  }),
+});
 ```
 
-### Basic Setup
+### Explicit Configuration
+
+You can also pass credentials directly (takes precedence over environment variables):
 
 ```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";

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

@@ -1,6 +1,10 @@
 ---
 title: "OpenTelemetry Exporter | Tracing | Observability"
 description: "Send traces to any OpenTelemetry-compatible observability platform"
+packages:
+  - "@mastra/core"
+  - "@mastra/observability"
+  - "@mastra/otel-exporter"
 ---
 
 # OpenTelemetry Exporter
@@ -23,7 +27,7 @@ Each provider requires specific protocol packages. Install the base exporter plu
 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
@@ -35,6 +39,18 @@ npm install @mastra/otel-exporter@beta @opentelemetry/exporter-trace-otlp-grpc @
 npm install @mastra/otel-exporter@beta @opentelemetry/exporter-trace-otlp-http
 ```
 
+## Environment Variables
+
+All providers support zero-config setup via environment variables. Set the appropriate variables and the exporter will automatically use them:
+
+| Provider  | Environment Variables                                                                      |
+| --------- | ------------------------------------------------------------------------------------------ |
+| Dash0     | `DASH0_API_KEY` (required), `DASH0_ENDPOINT` (required), `DASH0_DATASET` (optional)        |
+| SigNoz    | `SIGNOZ_API_KEY` (required), `SIGNOZ_REGION` (optional), `SIGNOZ_ENDPOINT` (optional)      |
+| New Relic | `NEW_RELIC_LICENSE_KEY` (required), `NEW_RELIC_ENDPOINT` (optional)                        |
+| Traceloop | `TRACELOOP_API_KEY` (required), `TRACELOOP_DESTINATION_ID`, `TRACELOOP_ENDPOINT` (optional)|
+| Laminar   | `LMNR_PROJECT_API_KEY` (required), `LAMINAR_ENDPOINT` (optional)                           |
+
 ## Provider Configurations
 
 
@@ -60,6 +76,38 @@ new OtelExporter({
 
 [Dash0](https://www.dash0.com/) provides real-time observability with automatic insights.
 
+#### Zero-Config Setup
+
+Set environment variables and use the exporter with an empty config:
+
+```bash title=".env"
+# Required
+DASH0_API_KEY=your-api-key
+DASH0_ENDPOINT=ingress.us-west-2.aws.dash0.com:4317
+
+# Optional
+DASH0_DATASET=production
+```
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { Observability } from "@mastra/observability";
+import { OtelExporter } from "@mastra/otel-exporter";
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      otel: {
+        serviceName: "my-service",
+        exporters: [new OtelExporter({ provider: { dash0: {} } })],
+      },
+    },
+  }),
+});
+```
+
+#### Explicit Configuration
+
 ```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { Observability } from "@mastra/observability";
@@ -101,6 +149,23 @@ Get your Dash0 endpoint from your dashboard. It should be in the format `ingress
 
 [SigNoz](https://signoz.io/) is an open-source APM alternative with built-in Tracing support.
 
+#### Zero-Config Setup
+
+```bash title=".env"
+# Required
+SIGNOZ_API_KEY=your-api-key
+
+# Optional
+SIGNOZ_REGION=us  # 'us' | 'eu' | 'in'
+SIGNOZ_ENDPOINT=https://my-signoz.example.com  # For self-hosted
+```
+
+```typescript title="src/mastra/index.ts"
+new OtelExporter({ provider: { signoz: {} } })
+```
+
+#### Explicit Configuration
+
 ```typescript title="src/mastra/index.ts"
 new OtelExporter({
   provider: {
@@ -117,6 +182,22 @@ new OtelExporter({
 
 [New Relic](https://newrelic.com/) provides comprehensive observability with AI monitoring capabilities.
 
+#### Zero-Config Setup
+
+```bash title=".env"
+# Required
+NEW_RELIC_LICENSE_KEY=your-license-key
+
+# Optional
+NEW_RELIC_ENDPOINT=https://otlp.eu01.nr-data.net  # For EU region
+```
+
+```typescript title="src/mastra/index.ts"
+new OtelExporter({ provider: { newrelic: {} } })
+```
+
+#### Explicit Configuration
+
 ```typescript title="src/mastra/index.ts"
 new OtelExporter({
   provider: {
@@ -132,6 +213,23 @@ new OtelExporter({
 
 [Traceloop](https://www.traceloop.com/) specializes in LLM observability with automatic prompt tracking.
 
+#### Zero-Config Setup
+
+```bash title=".env"
+# Required
+TRACELOOP_API_KEY=your-api-key
+
+# Optional
+TRACELOOP_DESTINATION_ID=my-destination
+TRACELOOP_ENDPOINT=https://custom.traceloop.com
+```
+
+```typescript title="src/mastra/index.ts"
+new OtelExporter({ provider: { traceloop: {} } })
+```
+
+#### Explicit Configuration
+
 ```typescript title="src/mastra/index.ts"
 new OtelExporter({
   provider: {
@@ -145,19 +243,111 @@ new OtelExporter({
 
 ### Laminar
 
-[Laminar](https://www.lmnr.ai/) provides specialized LLM observability and analytics.
+[Laminar](https://laminar.sh/) provides specialized LLM observability and analytics.
+
+#### Zero-Config Setup
+
+```bash title=".env"
+# Required
+LMNR_PROJECT_API_KEY=your-api-key
+
+# Optional
+LAMINAR_ENDPOINT=https://api.lmnr.ai/v1/traces
+```
+
+```typescript title="src/mastra/index.ts"
+new OtelExporter({ provider: { laminar: {} } })
+```
+
+#### Explicit Configuration
 
 ```typescript title="src/mastra/index.ts"
 new OtelExporter({
   provider: {
     laminar: {
       apiKey: process.env.LMNR_PROJECT_API_KEY,
-      // teamId: process.env.LAMINAR_TEAM_ID, // Optional, for backwards compatibility
     },
   },
 });
 ```
 
+:::tip Laminar-Native Exporter
+
+For Laminar-specific features like native span paths, metadata, and tags rendering in the Laminar dashboard, consider using the dedicated [`@mastra/laminar`](/docs/v1/observability/tracing/exporters/laminar) exporter instead. It provides optimized integration with Laminar's platform.
+
+:::
+
+### 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](/reference/v1/configuration#bundlerexternals) 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`](/reference/v1/configuration#bundlerexternals) configuration, are required for the gRPC transport to work correctly. Without these, you may encounter connection issues.
+
+:::
+
+:::tip Datadog-Native Exporter
+
+For Datadog-specific features like automatic span type mapping, LLM span categorization, and simplified setup without gRPC configuration, consider using the dedicated [`@mastra/datadog`](/docs/v1/observability/tracing/exporters/datadog) exporter instead. It provides optimized integration with Datadog's APM platform.
+
+:::
+
 ### Custom/Generic OTEL Endpoints
 
 For other OTEL-compatible platforms or custom collectors:
@@ -226,6 +416,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`  |
@@ -258,25 +449,6 @@ Install the suggested package for your provider.
 2. **Invalid endpoint**: Check endpoint format matches provider requirements
 3. **Authentication failures**: Verify API keys and headers are correct
 
-## 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)

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

@@ -1,6 +1,10 @@
 ---
 title: "PostHog Exporter | Tracing | Observability"
 description: "Send traces to PostHog for AI observability and analytics"
+packages:
+  - "@mastra/core"
+  - "@mastra/observability"
+  - "@mastra/posthog"
 ---
 
 # PostHog Exporter
@@ -22,11 +26,37 @@ npm install @mastra/posthog@beta
 3. **Environment Variables**: Set your credentials
 
 ```bash title=".env"
+# Required
 POSTHOG_API_KEY=phc_xxxxxxxxxxxxxxxx
-POSTHOG_HOST=https://us.i.posthog.com  # Optional: EU region or self-hosted URL
+
+# Optional
+POSTHOG_HOST=https://us.i.posthog.com  # or eu.i.posthog.com for EU region
+```
+
+### Zero-Config Setup
+
+With environment variables set, use the exporter with no configuration:
+
+```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()],
+      },
+    },
+  }),
+});
 ```
 
-### Basic Setup
+### Explicit Configuration
+
+You can also pass credentials directly (takes precedence over environment variables):
 
 ```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
@@ -101,26 +131,6 @@ new PosthogExporter({
 });
 ```
 
-## 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)