@mastra/core 1.6.0 → 1.7.0-alpha.0

package/dist/docs/references/docs-observability-tracing-exporters-arize.md

@@ -1,274 +0,0 @@
-# Arize Exporter
-
-[Arize](https://arize.com/) provides observability platforms for AI applications through [Phoenix](https://phoenix.arize.com/) (open-source) and [Arize AX](https://arize.com/generative-ai/) (enterprise). The Arize exporter sends traces using OpenTelemetry and [OpenInference](https://github.com/Arize-ai/openinference/tree/main/spec) semantic conventions, compatible with any OpenTelemetry platform that supports OpenInference.
-
-## Installation
-
-**npm**:
-
-```bash
-npm install @mastra/arize@latest
-```
-
-**pnpm**:
-
-```bash
-pnpm add @mastra/arize@latest
-```
-
-**Yarn**:
-
-```bash
-yarn add @mastra/arize@latest
-```
-
-**Bun**:
-
-```bash
-bun add @mastra/arize@latest
-```
-
-## Configuration
-
-### Phoenix Setup
-
-Phoenix is an open-source observability platform that can be self-hosted or used via Phoenix Cloud.
-
-#### Prerequisites
-
-1. **Phoenix Instance**: Deploy using Docker or sign up at [Phoenix Cloud](https://app.phoenix.arize.com/login)
-2. **Endpoint**: Your Phoenix endpoint URL (ends in `/v1/traces`)
-3. **API Key**: Optional for unauthenticated instances, required for Phoenix Cloud
-4. **Environment Variables**: Set your configuration
-
-```bash
-# Required
-PHOENIX_ENDPOINT=http://localhost:6006/v1/traces  # Or your Phoenix Cloud URL
-
-# Optional
-PHOENIX_API_KEY=your-api-key  # For authenticated Phoenix instances
-PHOENIX_PROJECT_NAME=mastra-service  # Defaults to 'mastra-service'
-```
-
-#### Zero-Config Setup
-
-With environment variables set, use the exporter with no configuration:
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { Observability } from "@mastra/observability";
-import { ArizeExporter } from "@mastra/arize";
-
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      arize: {
-        serviceName: "mastra-service",
-        exporters: [new ArizeExporter()],
-      },
-    },
-  }),
-});
-```
-
-#### Explicit Configuration
-
-You can also pass credentials directly (takes precedence over environment variables):
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { Observability } from "@mastra/observability";
-import { ArizeExporter } from "@mastra/arize";
-
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      arize: {
-        serviceName: process.env.PHOENIX_PROJECT_NAME || "mastra-service",
-        exporters: [
-          new ArizeExporter({
-            endpoint: process.env.PHOENIX_ENDPOINT!,
-            apiKey: process.env.PHOENIX_API_KEY,
-            projectName: process.env.PHOENIX_PROJECT_NAME,
-          }),
-        ],
-      },
-    },
-  }),
-});
-```
-
-> **Info:** **Quick Start with Docker**
->
-> Test locally with an in-memory Phoenix instance:
->
-> ```bash
-> docker run --pull=always -d --name arize-phoenix -p 6006:6006 \
->   -e PHOENIX_SQL_DATABASE_URL="sqlite:///:memory:" \
->   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).
-
-### Arize AX Setup
-
-Arize AX is an enterprise observability platform with advanced features for production AI systems.
-
-#### Prerequisites
-
-1. **Arize AX Account**: Sign up at [app.arize.com](https://app.arize.com/)
-2. **Space ID**: Your organization's space identifier
-3. **API Key**: Generate in Arize AX settings
-4. **Environment Variables**: Set your credentials
-
-```bash
-# Required
-ARIZE_SPACE_ID=your-space-id
-ARIZE_API_KEY=your-api-key
-
-# Optional
-ARIZE_PROJECT_NAME=mastra-service
-```
-
-#### Zero-Config Setup
-
-With environment variables set, use the exporter with no configuration:
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { Observability } from "@mastra/observability";
-import { ArizeExporter } from "@mastra/arize";
-
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      arize: {
-        serviceName: "mastra-service",
-        exporters: [new ArizeExporter()],
-      },
-    },
-  }),
-});
-```
-
-#### Explicit Configuration
-
-You can also pass credentials directly (takes precedence over environment variables):
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { Observability } from "@mastra/observability";
-import { ArizeExporter } from "@mastra/arize";
-
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      arize: {
-        serviceName: process.env.ARIZE_PROJECT_NAME || "mastra-service",
-        exporters: [
-          new ArizeExporter({
-            apiKey: process.env.ARIZE_API_KEY!,
-            spaceId: process.env.ARIZE_SPACE_ID!,
-            projectName: process.env.ARIZE_PROJECT_NAME,
-          }),
-        ],
-      },
-    },
-  }),
-});
-```
-
-## Configuration Options
-
-The Arize exporter supports advanced configuration for fine-tuning OpenTelemetry behavior:
-
-### Complete Configuration
-
-```typescript
-new ArizeExporter({
-  // Phoenix Configuration
-  endpoint: "https://your-collector.example.com/v1/traces", // Required for Phoenix
-
-  // Arize AX Configuration
-  spaceId: "your-space-id", // Required for Arize AX
-
-  // Shared Configuration
-  apiKey: "your-api-key", // Required for authenticated endpoints
-  projectName: "mastra-service", // Optional project name
-
-  // Optional OTLP settings
-  headers: {
-    "x-custom-header": "value", // Additional headers for OTLP requests
-  },
-
-  // Debug and performance tuning
-  logLevel: "debug", // Logging: debug | info | warn | error
-  batchSize: 512, // Batch size before exporting spans
-  timeout: 30000, // Timeout in ms before exporting spans
-
-  // Custom resource attributes
-  resourceAttributes: {
-    "deployment.environment": process.env.NODE_ENV,
-    "service.version": process.env.APP_VERSION,
-  },
-});
-```
-
-### Batch Processing Options
-
-Control how traces are batched and exported:
-
-```typescript
-new ArizeExporter({
-  endpoint: process.env.PHOENIX_ENDPOINT!,
-  apiKey: process.env.PHOENIX_API_KEY,
-
-  // Batch processing configuration
-  batchSize: 512, // Number of spans to batch (default: 512)
-  timeout: 30000, // Max time in ms to wait before export (default: 30000)
-});
-```
-
-### Resource Attributes
-
-Add custom attributes to all exported spans:
-
-```typescript
-new ArizeExporter({
-  endpoint: process.env.PHOENIX_ENDPOINT!,
-  resourceAttributes: {
-    "deployment.environment": process.env.NODE_ENV,
-    "service.namespace": "production",
-    "service.instance.id": process.env.HOSTNAME,
-    "custom.attribute": "value",
-  },
-});
-```
-
-### 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.
-
-## Related
-
-- [Tracing Overview](https://mastra.ai/docs/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/dist/docs/references/docs-observability-tracing-exporters-braintrust.md

@@ -1,111 +0,0 @@
-# Braintrust Exporter
-
-[Braintrust](https://www.braintrust.dev/) is an evaluation and monitoring platform that helps you measure and improve LLM application quality. The Braintrust exporter sends your traces to Braintrust, enabling systematic evaluation, scoring, and experimentation.
-
-## Installation
-
-**npm**:
-
-```bash
-npm install @mastra/braintrust@latest
-```
-
-**pnpm**:
-
-```bash
-pnpm add @mastra/braintrust@latest
-```
-
-**Yarn**:
-
-```bash
-yarn add @mastra/braintrust@latest
-```
-
-**Bun**:
-
-```bash
-bun add @mastra/braintrust@latest
-```
-
-## Configuration
-
-### Prerequisites
-
-1. **Braintrust Account**: Sign up at [braintrust.dev](https://www.braintrust.dev/)
-2. **Project**: Create or select a project for your traces
-3. **API Key**: Generate in Braintrust Settings → API Keys
-4. **Environment Variables**: Set your credentials:
-
-```bash
-BRAINTRUST_API_KEY=sk-xxxxxxxxxxxxxxxx
-
-# Optional
-BRAINTRUST_ENDPOINT=https://api.braintrust.dev  # Custom endpoint if needed
-```
-
-### Zero-Config Setup
-
-With environment variables set, use the exporter with no configuration:
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { Observability } from "@mastra/observability";
-import { BraintrustExporter } from "@mastra/braintrust";
-
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      braintrust: {
-        serviceName: "my-service",
-        exporters: [new BraintrustExporter()],
-      },
-    },
-  }),
-});
-```
-
-### Explicit Configuration
-
-You can also pass credentials directly (takes precedence over environment variables):
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { Observability } from "@mastra/observability";
-import { BraintrustExporter } from "@mastra/braintrust";
-
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      braintrust: {
-        serviceName: "my-service",
-        exporters: [
-          new BraintrustExporter({
-            apiKey: process.env.BRAINTRUST_API_KEY,
-            projectName: "my-project",
-          }),
-        ],
-      },
-    },
-  }),
-});
-```
-
-### Complete Configuration
-
-```typescript
-new BraintrustExporter({
-  // Required
-  apiKey: process.env.BRAINTRUST_API_KEY!,
-
-  // Optional settings
-  projectName: "my-project", // Default: 'mastra-tracing'
-  endpoint: "https://api.braintrust.dev", // Custom endpoint if needed
-  logLevel: "info", // Diagnostic logging: debug | info | warn | error
-});
-```
-
-## Related
-
-- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
-- [Braintrust Documentation](https://www.braintrust.dev/docs)

package/dist/docs/references/docs-observability-tracing-exporters-cloud.md

@@ -1,129 +0,0 @@
-# Cloud Exporter
-
-The `CloudExporter` sends traces to Mastra Cloud for centralized monitoring and team collaboration. It's automatically enabled when using the default observability configuration with a valid access token.
-
-## Configuration
-
-### Prerequisites
-
-1. **Mastra Cloud Account**: Sign up at [cloud.mastra.ai](https://cloud.mastra.ai)
-2. **Mastra Cloud Project**: Create a project in Mastra Cloud. Traces are scoped per project, so even if you only want observability, you need a project to act as the destination for your traces.
-3. **Access Token**: Generate in your project's sidebar under **Project Settings → Access Tokens**
-4. **Environment Variables**: Set your credentials:
-
-```bash
-MASTRA_CLOUD_ACCESS_TOKEN=mst_xxxxxxxxxxxxxxxx
-```
-
-### Basic Setup
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { Observability, CloudExporter } from "@mastra/observability";
-
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      production: {
-        serviceName: "my-service",
-        exporters: [
-          new CloudExporter(), // Uses MASTRA_CLOUD_ACCESS_TOKEN env var
-        ],
-      },
-    },
-  }),
-});
-```
-
-### Recommended Configuration
-
-Include CloudExporter in your observability configuration:
-
-```typescript
-import { Mastra } from "@mastra/core";
-import {
-  Observability,
-  DefaultExporter,
-  CloudExporter,
-  SensitiveDataFilter,
-} from "@mastra/observability";
-
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      default: {
-        serviceName: "mastra",
-        exporters: [
-          new DefaultExporter(),
-          new CloudExporter(), // Sends traces to Mastra Cloud (requires MASTRA_CLOUD_ACCESS_TOKEN)
-        ],
-        spanOutputProcessors: [
-          new SensitiveDataFilter(),
-        ],
-      },
-    },
-  }),
-});
-```
-
-### Complete Configuration
-
-```typescript
-new CloudExporter({
-  // Optional - defaults to env var
-  accessToken: process.env.MASTRA_CLOUD_ACCESS_TOKEN,
-
-  // Optional - for self-hosted Mastra Cloud
-  endpoint: "https://cloud.your-domain.com",
-
-  // Batching configuration
-  maxBatchSize: 1000, // Max spans per batch
-  maxBatchWaitMs: 5000, // Max wait before sending batch
-
-  // Diagnostic logging
-  logLevel: "info", // debug | info | warn | error
-});
-```
-
-## Viewing Traces
-
-### Mastra Cloud Dashboard
-
-1. Navigate to [cloud.mastra.ai](https://cloud.mastra.ai)
-
-2. Select the project associated with your access token
-
-3. Go to **Observability → Traces**
-
-4. Use filters to find specific traces:
-
-   - Service name
-   - Time range
-   - Trace ID
-   - Error status
-
-> **Note:** Traces are scoped to the project that issued the access token. To view traces, make sure you're viewing the same project you generated the token from.
-
-### Features
-
-- **Trace Timeline** - Visual execution flow
-- **Span Details** - Inputs, outputs, metadata
-- **Performance Metrics** - Latency, token usage
-- **Team Collaboration** - Share trace links
-
-## Performance
-
-> **Info:** CloudExporter uses intelligent batching to optimize network usage. Traces are buffered and sent in batches, reducing overhead while maintaining near real-time visibility.
-
-### Batching Behavior
-
-- Traces are batched up to `maxBatchSize` (default: 1000)
-- Batches are sent when full or after `maxBatchWaitMs` (default: 5 seconds)
-- Failed batches are retried with exponential backoff
-- Graceful degradation if Mastra Cloud is unreachable
-
-## Related
-
-- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
-- [DefaultExporter](https://mastra.ai/docs/observability/tracing/exporters/default)
-- [Mastra Cloud Documentation](https://mastra.ai/docs/mastra-cloud/overview)

package/dist/docs/references/docs-observability-tracing-exporters-datadog.md

@@ -1,187 +0,0 @@
-# Datadog Exporter
-
-[Datadog](https://datadoghq.com/) is a comprehensive monitoring platform with dedicated LLM Observability features. The Datadog exporter sends your traces to Datadog's LLM Observability product, providing insights into model performance, token usage, and conversation flows.
-
-## Installation
-
-**npm**:
-
-```bash
-npm install @mastra/datadog@latest
-```
-
-**pnpm**:
-
-```bash
-pnpm add @mastra/datadog@latest
-```
-
-**Yarn**:
-
-```bash
-yarn add @mastra/datadog@latest
-```
-
-**Bun**:
-
-```bash
-bun add @mastra/datadog@latest
-```
-
-## Configuration
-
-### Prerequisites
-
-1. **Datadog Account**: Sign up at [datadoghq.com](https://datadoghq.com/) with LLM Observability enabled
-2. **API Key**: Get your API key from Datadog Organization Settings → API Keys
-3. **Environment Variables**: Set your credentials
-
-```bash
-DD_API_KEY=your-datadog-api-key
-DD_LLMOBS_ML_APP=my-llm-app
-DD_SITE=datadoghq.com  # Optional: defaults to datadoghq.com
-DD_ENV=production      # Optional: environment name
-```
-
-### Zero-Config Setup
-
-With environment variables set, use the exporter with no configuration:
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { Observability } from "@mastra/observability";
-import { DatadogExporter } from "@mastra/datadog";
-
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      datadog: {
-        serviceName: "my-service",
-        exporters: [new DatadogExporter()],
-      },
-    },
-  }),
-});
-```
-
-### Explicit Configuration
-
-You can also pass credentials directly (takes precedence over environment variables):
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { Observability } from "@mastra/observability";
-import { DatadogExporter } from "@mastra/datadog";
-
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      datadog: {
-        serviceName: "my-service",
-        exporters: [
-          new DatadogExporter({
-            mlApp: process.env.DD_LLMOBS_ML_APP!,
-            apiKey: process.env.DD_API_KEY!,
-          }),
-        ],
-      },
-    },
-  }),
-});
-```
-
-## Configuration Options
-
-### Complete Configuration
-
-```typescript
-new DatadogExporter({
-  // Required settings
-  mlApp: process.env.DD_LLMOBS_ML_APP!, // Groups traces under this ML app name
-  apiKey: process.env.DD_API_KEY!, // Required for agentless mode (default)
-
-  // Optional settings
-  site: "datadoghq.com", // Datadog site (datadoghq.eu, us3.datadoghq.com, etc.)
-  service: "my-service", // Service name (defaults to mlApp)
-  env: "production", // Environment name
-  agentless: true, // true = direct HTTPS, false = local Datadog Agent
-
-  // Advanced settings
-  integrationsEnabled: false, // Enable dd-trace auto-instrumentation
-
-  // Diagnostic logging
-  logLevel: "info", // debug | info | warn | error
-});
-```
-
-### With Local Datadog Agent
-
-If you have a Datadog Agent running locally, you can route traces through it instead of direct HTTPS:
-
-```typescript
-new DatadogExporter({
-  mlApp: process.env.DD_LLMOBS_ML_APP!,
-  agentless: false, // Use local Datadog Agent
-  env: "production",
-});
-```
-
-Note: When using agent mode, the API key is read from the local agent's configuration.
-
-## Span Type Mapping
-
-Mastra span types are automatically mapped to Datadog LLMObs span kinds:
-
-| Mastra SpanType      | Datadog Kind |
-| -------------------- | ------------ |
-| `AGENT_RUN`          | `agent`      |
-| `MODEL_GENERATION`   | `workflow`   |
-| `MODEL_STEP`         | `llm`        |
-| `TOOL_CALL`          | `tool`       |
-| `MCP_TOOL_CALL`      | `tool`       |
-| `WORKFLOW_RUN`       | `workflow`   |
-| Other workflow types | `task`       |
-| `GENERIC`            | `task`       |
-
-Other/future Mastra span types will default to 'task' when mapped unless specified.
-
-## Troubleshooting
-
-### Native module ABI mismatch
-
-If you see errors like:
-
-```text
-Error: No native build was found for runtime=node abi=137 platform=linuxglibc arch=x64
-```
-
-This indicates a Node.js version compatibility issue with `dd-trace`'s native modules. These native modules are **optional** and provide performance monitoring features.
-
-**Solutions:**
-
-1. **Use Node.js 22.x**: Native modules have the best compatibility with Node.js 22.x.
-
-2. **Ignore native module warnings**: The native modules (`@datadog/native-metrics`, `@datadog/native-appsec`, etc.) are optional. If they fail to load, core tracing functionality still works.
-
-### Bundler externals configuration
-
-When using bundlers like esbuild, webpack, or the Mastra CLI bundler, you may need to mark `dd-trace` and its dependencies as external:
-
-```typescript
-export const mastra = new Mastra({
-  bundler: {
-    externals: [
-      "dd-trace",
-      "@datadog/native-metrics",
-      "@datadog/native-appsec",
-      "@datadog/native-iast-taint-tracking",
-      "@datadog/pprof",
-    ],
-  },
-});
-```
-
-## Related
-
-- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
-- [Datadog LLM Observability Documentation](https://docs.datadoghq.com/llm_observability/)