Mastra Tracing

Instrument Mastra projects to export AI tracing data to Arize AX using OpenTelemetry and OpenInference semantics.

Mastra integrates directly with Arize AX through the @mastra/arize exporter, enabling OpenTelemetry tracing that follows the OpenInference semantic conventions for enterprise observability.

Prerequisites

• Mastra project generated with npm create mastra@latest

• Node.js environment configured for your application

• Access to an Arize AX space with API credentials

Installation

Install the Mastra Arize exporter alongside your Mastra project dependencies:

npm install @mastra/arize

Arize AX Setup

Arize AX is the managed Arize AX for production workloads and enterprise governance.

Prerequisites

• Arize AX account (https://app.arize.com)

• Space ID for your organization

• API key with tracing permissions

Environment variables

ARIZE_SPACE_ID=your-space-id
ARIZE_API_KEY=your-api-key
ARIZE_PROJECT_NAME=mastra-service  # Optional override

Basic setup

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,
          }),
        ],
      },
    },
  },
});

Advanced configuration

Fine-tune exporter behavior for Arize AX deployments.

Complete configuration

import { ArizeExporter } from "@mastra/arize";

const exporter = new ArizeExporter({
  spaceId: "your-space-id",
  apiKey: "your-api-key",
  projectName: "mastra-service",

  // Optional OTLP settings
  headers: {
    "x-custom-header": "value",
  },

  // Debug and performance tuning
  logLevel: "debug",
  batchSize: 512,
  timeout: 30000,

  // Custom resource attributes
  resourceAttributes: {
    "deployment.environment": process.env.NODE_ENV,
    "service.version": process.env.APP_VERSION,
  },
});

Batch processing options

const exporter = new ArizeExporter({
  spaceId: process.env.ARIZE_SPACE_ID!,
  apiKey: process.env.ARIZE_API_KEY!,
  batchSize: 512,
  timeout: 30000,
});

Resource attributes

const exporter = new ArizeExporter({
  spaceId: process.env.ARIZE_SPACE_ID!,
  apiKey: process.env.ARIZE_API_KEY!,
  resourceAttributes: {
    "deployment.environment": process.env.NODE_ENV,
    "service.namespace": "production",
    "service.instance.id": process.env.HOSTNAME,
    "custom.attribute": "value",
  },
});

Running your Mastra application

Use the Mastra dev server to ensure tracing hooks are initialized and spans are exported.

mastra dev

When the dev server starts, Mastra generates the required instrumentation under .mastra/output/, boots the playground at http://localhost:4111, and begins streaming traces to your configured exporter.

Observe

Once connected, Mastra exports comprehensive traces that include agent steps, tool usage, LLM spans, embeddings, and retrieval analytics. The exporter adheres to OpenTelemetry and OpenInference semantics, streaming telemetry directly into Arize AX.

Resources

• Mastra Arize Exporter Guide

• Mastra API Reference – Arize Exporter

• Arize AX Documentation

• OpenInference Specification