@mastra/core 1.7.0 → 1.8.0

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

@@ -0,0 +1,272 @@
+# 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,
+          }),
+        ],
+      },
+    },
+  }),
+})
+```
+
+> **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

@@ -0,0 +1,111 @@
+# 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

@@ -0,0 +1,127 @@
+# 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

@@ -0,0 +1,187 @@
+# 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/)