@mastra/mcp-docs-server 0.13.34 → 0.13.35-alpha.0

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

@@ -0,0 +1,201 @@
+---
+title: "Arize Exporter | AI Tracing | Observability | Mastra Docs"
+description: "Send AI traces to Arize Phoenix or Arize AX using OpenTelemetry and OpenInference"
+---
+
+import { Callout } from "nextra/components";
+
+# 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 AI traces using OpenTelemetry and [OpenInference](https://github.com/Arize-ai/openinference/tree/main/spec) semantic conventions, compatible with any OpenTelemetry platform that supports OpenInference.
+
+## When to Use Arize
+
+Arize is ideal when you need:
+- **OpenInference standards** - Industry-standard semantic conventions for AI traces
+- **Flexible deployment** - Self-hosted Phoenix or managed Arize AX
+- **OpenTelemetry compatibility** - Works with any OTLP-compatible platform
+- **Comprehensive AI observability** - LLM traces, embeddings, and retrieval analytics
+- **Open-source option** - Full-featured local deployment with Phoenix
+
+## Installation
+
+```bash npm2yarn
+npm install @mastra/arize
+```
+
+## 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 filename=".env"
+PHOENIX_ENDPOINT=http://localhost:6006/v1/traces  # Or your Phoenix Cloud URL
+PHOENIX_API_KEY=your-api-key  # Optional for local instances
+PHOENIX_PROJECT_NAME=mastra-service  # Optional, defaults to 'mastra-service'
+```
+
+#### Basic Setup
+
+```typescript filename="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { ArizeExporter } from "@mastra/arize";
+
+export const mastra = new Mastra({
+  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,
+          }),
+        ],
+      },
+    },
+  },
+});
+```
+
+<Callout type="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).
+</Callout>
+
+### 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 filename=".env"
+ARIZE_SPACE_ID=your-space-id
+ARIZE_API_KEY=your-api-key
+ARIZE_PROJECT_NAME=mastra-service  # Optional
+```
+
+#### Basic Setup
+
+```typescript filename="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { ArizeExporter } from "@mastra/arize";
+
+export const mastra = new Mastra({
+  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',
+  },
+})
+```
+
+## 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
+
+- [AI Tracing Overview](/docs/observability/ai-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/ai-tracing/overview.mdx

@@ -89,14 +89,13 @@ Mastra provides two built-in exporters that work out of the box:
 
 In addition to the internal exporters, Mastra supports integration with popular observability platforms. These exporters allow you to leverage your existing monitoring infrastructure and take advantage of platform-specific features like alerting, dashboards, and correlation with other application metrics.
 
+- **[Arize](/docs/observability/ai-tracing/exporters/arize)** - Exports traces to Arize Phoenix or Arize AX using OpenInference semantic conventions
 - **[Braintrust](/docs/observability/ai-tracing/exporters/braintrust)** - Exports traces to Braintrust's eval and observability platform
 - **[Langfuse](/docs/observability/ai-tracing/exporters/langfuse)** - Sends traces to the Langfuse open-source LLM engineering platform
-- **[LangSmith](/docs/observability/ai-tracing/exporters/langsmith)** - Pushes traces into LangSmith’s observability and evaluation toolkit
+- **[LangSmith](/docs/observability/ai-tracing/exporters/langsmith)** - Pushes traces into LangSmith's observability and evaluation toolkit
 - **[OpenTelemetry](/docs/observability/ai-tracing/exporters/otel)** - Deliver traces to any OpenTelemetry-compatible observability system
   - Supports: Dash0, Laminar, New Relic, SigNoz, Traceloop, Zipkin, and others!
 
-- **Arize** - Coming soon!
-
 ## Sampling Strategies
 
 Sampling allows you to control which traces are collected, helping you balance between observability needs and resource costs. In production environments with high traffic, collecting every trace can be expensive and unnecessary. Sampling strategies let you capture a representative subset of traces while ensuring you don't miss critical information about errors or important operations.
@@ -311,7 +310,7 @@ When creating a custom config with external exporters, you might lose access to
 
 ```ts filename="src/mastra/index.ts" showLineNumbers copy
 import { DefaultExporter, CloudExporter } from '@mastra/core/ai-tracing';
-import { LangfuseExporter } from '@mastra/langfuse';
+import { ArizeExporter } from '@mastra/arize';
 
 export const mastra = new Mastra({
   observability: {
@@ -320,7 +319,10 @@ export const mastra = new Mastra({
       production: {
         serviceName: 'my-service',
         exporters: [
-          new LangfuseExporter(), // External exporter
+          new ArizeExporter({    // External exporter
+            endpoint: process.env.PHOENIX_ENDPOINT,
+            apiKey: process.env.PHOENIX_API_KEY,
+          }),
           new DefaultExporter(),  // Keep Playground access
           new CloudExporter(),    // Keep Cloud access
         ],
@@ -331,7 +333,7 @@ export const mastra = new Mastra({
 ```
 
 This configuration sends traces to all three destinations simultaneously:
-- **Langfuse** for external observability
+- **Arize Phoenix/AX** for external observability
 - **DefaultExporter** for local Playground access
 - **CloudExporter** for Mastra Cloud dashboard
 
@@ -759,8 +761,9 @@ Traces are available in multiple locations:
 
 - **Mastra Playground** - Local development environment
 - **Mastra Cloud** - Production monitoring dashboard
-- **Langfuse Dashboard** - When using Langfuse exporter
+- **Arize Phoenix / Arize AX** - When using Arize exporter
 - **Braintrust Console** - When using Braintrust exporter
+- **Langfuse Dashboard** - When using Langfuse exporter
 
 ## See Also
 
@@ -777,8 +780,9 @@ Traces are available in multiple locations:
 - [DefaultExporter](/reference/observability/ai-tracing/exporters/default-exporter) - Storage persistence
 - [CloudExporter](/reference/observability/ai-tracing/exporters/cloud-exporter) - Mastra Cloud integration
 - [ConsoleExporter](/reference/observability/ai-tracing/exporters/console-exporter) - Debug output
-- [Langfuse](/reference/observability/ai-tracing/exporters/langfuse) - Langfuse integration
+- [Arize](/reference/observability/ai-tracing/exporters/arize) - Arize Phoenix and Arize AX integration
 - [Braintrust](/reference/observability/ai-tracing/exporters/braintrust) - Braintrust integration
+- [Langfuse](/reference/observability/ai-tracing/exporters/langfuse) - Langfuse integration
 - [OpenTelemetry](/reference/observability/ai-tracing/exporters/otel) - OTEL-compatible platforms
 
 ### Processors

package/.docs/raw/reference/observability/ai-tracing/exporters/arize.mdx

@@ -0,0 +1,160 @@
+---
+title: "ArizeExporter | Exporters | AI Tracing | Reference"
+description: Arize exporter for AI tracing using OpenInference
+---
+
+import { PropertiesTable } from "@/components/properties-table";
+
+# ArizeExporter
+
+Sends AI tracing data to Arize Phoenix, Arize AX, or any OpenTelemetry-compatible observability platform that supports OpenInference semantic conventions.
+
+## Constructor
+
+```typescript
+new ArizeExporter(config: ArizeExporterConfig)
+```
+
+## ArizeExporterConfig
+
+```typescript
+interface ArizeExporterConfig {
+  // Phoenix / OpenTelemetry configuration
+  endpoint?: string;
+  apiKey?: string;
+
+  // Arize AX configuration
+  spaceId?: string;
+
+  // Common configuration
+  projectName?: string;
+  headers?: Record<string, string>;
+
+  // Inherited from OtelExporterConfig
+  timeout?: number;
+  batchSize?: number;
+  logLevel?: 'debug' | 'info' | 'warn' | 'error';
+  resourceAttributes?: Record<string, any>;
+}
+```
+
+<PropertiesTable
+  props={[
+    {
+      name: "endpoint",
+      type: "string",
+      description: "Collector endpoint for trace exports (e.g., 'http://localhost:6006/v1/traces' for Phoenix). Required for Phoenix. Optional for Arize AX (defaults to https://otlp.arize.com/v1/traces).",
+      required: false,
+    },
+    {
+      name: "apiKey",
+      type: "string",
+      description: "API key for authentication. Required for Phoenix Cloud and Arize AX. Optional for self-hosted Phoenix.",
+      required: false,
+    },
+    {
+      name: "spaceId",
+      type: "string",
+      description: "Arize AX space identifier. Required when sending traces to Arize AX.",
+      required: false,
+    },
+    {
+      name: "projectName",
+      type: "string",
+      description: "Project name added as OpenInference resource attribute",
+      required: false,
+    },
+    {
+      name: "headers",
+      type: "Record<string, string>",
+      description: "Additional headers for OTLP requests",
+      required: false,
+    },
+    {
+      name: "timeout",
+      type: "number",
+      description: "Timeout in milliseconds before exporting spans (default: 30000)",
+      required: false,
+    },
+    {
+      name: "batchSize",
+      type: "number",
+      description: "Number of spans to batch before export (default: 512)",
+      required: false,
+    },
+    {
+      name: "logLevel",
+      type: "'debug' | 'info' | 'warn' | 'error'",
+      description: "Logger level (default: 'warn')",
+      required: false,
+    },
+    {
+      name: "resourceAttributes",
+      type: "Record<string, any>",
+      description: "Custom resource attributes added to each span",
+      required: false,
+    },
+  ]}
+/>
+
+## Methods
+
+### exportEvent
+
+```typescript
+async exportEvent(event: AITracingEvent): Promise<void>
+```
+
+Exports a tracing event to the configured endpoint.
+
+### export
+
+```typescript
+async export(spans: ReadOnlyAISpan[]): Promise<void>
+```
+
+Batch exports spans using OpenTelemetry with OpenInference semantic conventions.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Flushes pending data and shuts down the client.
+
+## Usage
+
+### Phoenix Configuration
+
+```typescript
+import { ArizeExporter } from '@mastra/arize';
+
+const exporter = new ArizeExporter({
+  endpoint: 'http://localhost:6006/v1/traces',
+  apiKey: process.env.PHOENIX_API_KEY, // Optional for local Phoenix
+  projectName: 'my-ai-project',
+});
+```
+
+### Arize AX Configuration
+
+```typescript
+import { ArizeExporter } from '@mastra/arize';
+
+const exporter = new ArizeExporter({
+  spaceId: process.env.ARIZE_SPACE_ID!,
+  apiKey: process.env.ARIZE_API_KEY!,
+  projectName: 'my-ai-project',
+});
+```
+
+## OpenInference Semantic Conventions
+
+The ArizeExporter implements [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
+
+- [ArizeExporter Documentation](/docs/observability/ai-tracing/exporters/arize)
+- [Phoenix Documentation](https://docs.arize.com/phoenix)
+- [Arize AX Documentation](https://docs.arize.com/)

package/.docs/raw/reference/observability/ai-tracing/exporters/braintrust.mdx

@@ -103,8 +103,8 @@ const exporter = new BraintrustExporter({
 
 | AI Span Type | Braintrust Type |
 |--------------|-----------------|
-| `LLM_GENERATION` | `llm` |
-| `LLM_CHUNK` | `llm` |
+| `MODEL_GENERATION` | `llm` |
+| `MODEL_CHUNK` | `llm` |
 | `TOOL_CALL` | `tool` |
 | `MCP_TOOL_CALL` | `tool` |
 | `WORKFLOW_CONDITIONAL_EVAL` | `function` |

package/.docs/raw/reference/observability/ai-tracing/exporters/langfuse.mdx

@@ -111,6 +111,6 @@ const exporter = new LangfuseExporter({
 ## Span Mapping
 
 - Root spans → Langfuse traces
-- `LLM_GENERATION` spans → Langfuse generations
+- `MODEL_GENERATION` spans → Langfuse generations
 - All other spans → Langfuse spans
 - Event spans → Langfuse events

package/.docs/raw/reference/observability/ai-tracing/exporters/langsmith.mdx

@@ -105,8 +105,8 @@ const exporter = new LangSmithExporter({
 
 | AI Span Type | LangSmith Type |
 |--------------|----------------|
-| `LLM_GENERATION` | `llm` |
-| `LLM_CHUNK` | `llm` |
+| `MODEL_GENERATION` | `llm` |
+| `MODEL_CHUNK` | `llm` |
 | `TOOL_CALL` | `tool` |
 | `MCP_TOOL_CALL` | `tool` |
 | All others | `chain` |

package/.docs/raw/reference/observability/ai-tracing/exporters/otel.mdx

@@ -317,7 +317,7 @@ const exporter = new OtelExporter({
 The exporter maps Mastra AI spans to OpenTelemetry spans following GenAI semantic conventions:
 
 ### Span Names
-- `LLM_GENERATION` → `chat {model}` or `tool_selection {model}`
+- `MODEL_GENERATION` → `chat {model}` or `tool_selection {model}`
 - `TOOL_CALL` → `tool.execute {tool_name}`
 - `AGENT_RUN` → `agent.{agent_id}`
 - `WORKFLOW_RUN` → `workflow.{workflow_id}`

package/.docs/raw/reference/observability/ai-tracing/interfaces.mdx

@@ -43,8 +43,9 @@ Mapping of span types to their corresponding attribute interfaces.
 interface AISpanTypeMap {
   AGENT_RUN: AgentRunAttributes;
   WORKFLOW_RUN: WorkflowRunAttributes;
-  LLM_GENERATION: LLMGenerationAttributes;
-  LLM_CHUNK: LLMChunkAttributes;
+  MODEL_GENERATION: ModelGenerationAttributes;
+  MODEL_STEP: ModelStepAttributes;
+  MODEL_CHUNK: ModelChunkAttributes;
   TOOL_CALL: ToolCallAttributes;
   MCP_TOOL_CALL: MCPToolCallAttributes;
   WORKFLOW_STEP: WorkflowStepAttributes;
@@ -160,16 +161,19 @@ AI-specific span types with their associated metadata.
 enum AISpanType {
   /** Agent run - root span for agent processes */
   AGENT_RUN = 'agent_run',
-  
+
   /** Generic span for custom operations */
   GENERIC = 'generic',
-  
-  /** LLM generation with model calls, token usage, prompts, completions */
-  LLM_GENERATION = 'llm_generation',
-  
-  /** Individual LLM streaming chunk/event */
-  LLM_CHUNK = 'llm_chunk',
-  
+
+  /** Model generation with model calls, token usage, prompts, completions */
+  MODEL_GENERATION = 'model_generation',
+
+  /** Single model execution step within a generation (one API call) */
+  MODEL_STEP = 'model_step',
+
+  /** Individual model streaming chunk/event */
+  MODEL_CHUNK = 'model_chunk',
+
   /** MCP (Model Context Protocol) tool execution */
   MCP_TOOL_CALL = 'mcp_tool_call',
   
@@ -235,19 +239,19 @@ interface AgentRunAttributes {
 }
 ```
 
-### LLMGenerationAttributes
+### ModelGenerationAttributes
 
-LLM Generation attributes.
+Model Generation attributes.
 
 ```typescript
-interface LLMGenerationAttributes {
+interface ModelGenerationAttributes {
   /** Model name (e.g., 'gpt-4', 'claude-3') */
   model?: string;
   
   /** Model provider (e.g., 'openai', 'anthropic') */
   provider?: string;
   
-  /** Type of result/output this LLM call produced */
+  /** Type of result/output this model call produced */
   resultType?: 'tool_selection' | 'response_generation' | 'reasoning' | 'planning';
   
   /** Token usage statistics */
@@ -280,12 +284,35 @@ interface LLMGenerationAttributes {
 }
 ```
 
-### LLMChunkAttributes
+### ModelStepAttributes
 
-LLM Chunk attributes - for individual streaming chunks/events.
+Model Step attributes - for a single model execution within a generation.
 
 ```typescript
-interface LLMChunkAttributes {
+interface ModelStepAttributes {
+  /** Index of this step in the generation (0, 1, 2, ...) */
+  stepIndex?: number;
+
+  /** Token usage statistics */
+  usage?: UsageStats;
+
+  /** Reason this step finished (stop, tool-calls, length, etc.) */
+  finishReason?: string;
+
+  /** Should execution continue */
+  isContinued?: boolean;
+
+  /** Result warnings */
+  warnings?: Record<string, any>;
+}
+```
+
+### ModelChunkAttributes
+
+Model Chunk attributes - for individual streaming chunks/events.
+
+```typescript
+interface ModelChunkAttributes {
   /** Type of chunk (text-delta, reasoning-delta, tool-call, etc.) */
   chunkType?: string;
   
@@ -626,10 +653,10 @@ enum InternalSpans {
   
   /** Tool spans are marked internal */
   TOOL = 1 << 2,
-  
-  /** LLM spans are marked internal */
-  LLM = 1 << 3,
-  
+
+  /** Model spans are marked internal */
+  MODEL = 1 << 3,
+
   /** All spans are marked internal */
   ALL = (1 << 4) - 1,
 }