Skip to main content

Documentation Index

Fetch the complete documentation index at: https://arize-ax.mintlify.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

Mastra is a TypeScript framework for building agents, workflows, and tool integrations on top of the Vercel AI SDK. Arize AX captures every Mastra agent run via the official @mastra/arize exporter, which Mastra invokes from its observability layer when the dev server is running.

​
Prerequisites

  • Node.js 18+
  • An Arize AX account (sign up)
  • An OPENAI_API_KEY from the OpenAI Platform (or any other provider supported by @ai-sdk/*)
The Mastra constructor registers the OTel SDK and the ArizeExporter as soon as it runs, so any entry point that imports your configured mastra value will emit spans — mastra dev is the easiest way to get there (it bundles your code and starts an HTTP playground at http://localhost:4111), but a plain tsx script that imports mastra and calls mastra.getAgent("...").generate(...) works just as well. The Running programmatically section below shows that pattern.

​
Launch Arize AX

  1. Sign in to your Arize AX account.
  2. From Space Settings, copy your Space ID and API Key. You will set them as ARIZE_SPACE_ID and ARIZE_API_KEY below.

​
Install

Bootstrap a Mastra project (if you don’t already have one), then add the Arize AX exporter: 
npm create mastra@latest
# answer the prompts: include "agent", "tools", and the example
cd <chosen-project-name>

npm install @mastra/arize @mastra/observability @mastra/core
npm install --save-dev mastra

​
Configure credentials

export ARIZE_SPACE_ID="<your-space-id>"
export ARIZE_API_KEY="<your-api-key>"
export ARIZE_PROJECT_NAME="mastra-tracing-example"
export OPENAI_API_KEY="<your-openai-api-key>"
The ArizeExporter reads ARIZE_SPACE_ID, ARIZE_API_KEY, and ARIZE_PROJECT_NAME from the environment. You can also pass them explicitly to the constructor (see below).

​
Setup tracing

Edit your project’s main Mastra entry point (typically src/mastra/index.ts) to register the exporter: 
// src/mastra/index.ts
import { Mastra } from "@mastra/core";
import { Observability } from "@mastra/observability";
import { ArizeExporter } from "@mastra/arize";
import { weatherAgent } from "./agents/weather-agent";

export const mastra = new Mastra({
  agents: { weatherAgent },
  observability: new Observability({
    configs: {
      arize: {
        serviceName: process.env.ARIZE_PROJECT_NAME ?? "mastra-tracing-example",
        exporters: [new ArizeExporter()],
      },
    },
  }),
});
If you’d rather hard-code credentials (e.g. for a one-off test), pass them to ArizeExporter: 
new ArizeExporter({
  apiKey: process.env.ARIZE_API_KEY!,
  spaceId: process.env.ARIZE_SPACE_ID!,
  projectName: process.env.ARIZE_PROJECT_NAME,
})

​
Run Mastra

Start the dev server — this is what wires OTel into your app: 
mastra dev
mastra dev does four things:
  1. Generates OTel bootstrap files into .mastra/output/.
  2. Registers the ArizeExporter against the global tracer provider.
  3. Starts the Mastra playground at http://localhost:4111/playground.
  4. Begins streaming spans to Arize AX as agents are invoked.
Open the playground and chat with one of your agents — for example, ask the weather agent “What’s the weather in Berlin?” Each prompt produces an agent run that is exported to Arize AX.

​
Expected output

[mastra dev] Starting Mastra dev server on http://localhost:4111
[mastra dev] Observability configured: arize → otlp.arize.com
[mastra dev] Playground ready at http://localhost:4111/playground

​
Running programmatically

For automated tests, batch jobs, or production code that doesn’t need the playground UI, import the mastra value and call getAgent(...).generate(...) directly. The Mastra constructor registers OTel + the ArizeExporter at module load, so spans flow exactly as they do under mastra dev: 
// run-mastra.ts
import { mastra } from "./src/mastra/index";

async function main() {
  console.log("Arize AX tracing initialized for Mastra.");

  const agent = mastra.getAgent("oceanAgent");
  const result = await agent.generate([
    {
      role: "user",
      content: "Why is the ocean salty? Answer in two sentences.",
    },
  ]);

  console.log(result.text);

  // BatchSpanProcessor batches spans before export — wait for the
  // wrapping invoke_agent root span to flush before the process exits.
  await new Promise((r) => setTimeout(r, 8000));
}

main().catch((err) => { console.error(err); process.exit(1); });
Run it with tsx: 
npx tsx run-mastra.ts
You’ll see the agent’s reply on stdout and the same invoke_agent / model_step / model_chunk span tree appear in Arize AX. This is the mode our integration test harness drives — see the doc’s GitHub source for the full scaffold.

​
Verify in Arize AX

  1. Open your Arize AX space and select project mastra-tracing-example.
  2. Trigger an agent from the playground at http://localhost:4111/playground, then return to Arize AX. You should see a new trace within ~30 seconds with this shape: an invoke_agent <agentName> root span (AGENT) wraps model_step <agentName> and model_chunk <agentName> LLM child spans, plus a chat <model-id> LLM span with the prompt, response, and token usage attached.
  3. If no traces appear, see Troubleshooting.

​
Troubleshooting

  • No traces in Arize AX. Check that you actually import the mastra value before calling the agent — the Mastra constructor is what registers OTel. A script that imports an agent directly from ./agents/<name> without ever touching the configured mastra instance will run the agent but skip registration. The pattern in the Running programmatically section imports mastra first.
  • BatchSpanProcessor: span dropped warnings, or partial traces. The process exited before the span batch was flushed. Add await new Promise((r) => setTimeout(r, 8000)) (or mastra.shutdown() if you’re on a version that exposes it) before the script exits, so the OTel exporter has time to drain. mastra dev handles this automatically because the dev server stays alive.
  • 401 from OpenAI. Verify OPENAI_API_KEY is set and your model selection is valid. The dev server inherits the shell environment that started it.
  • Auth errors from Arize AX. Re-check ARIZE_SPACE_ID and ARIZE_API_KEY were set before mastra dev started. Restart the dev server after exporting them — already-running processes do not pick up new env vars.
  • Production / serverless deployments. Outside the dev server, you must register OTel yourself before Mastra runs. The @mastra/arize exporter still works, but you wire it in via your platform’s instrumentation entry point (e.g. instrumentation.ts in Next.js). See the Mastra observability docs for the platform-specific setup.

​
Resources

Mastra Documentation

Mastra Arize AX Exporter Reference

Mastra GitHub