Mastra

Overview

Mastra is a TypeScript framework for building AI agents and workflows. Confident AI traces and evaluates Mastra applications with confident-trace, Confident AI's OpenTelemetry-native tracing SDK, with no changes to your agent code — every agent run shows up in the Observatory as a trace with the full agent → model → tool hierarchy, so you can see which tools an agent chose, what each model call cost, and run evals on the result.

Auto-Instrument

1. Install Dependencies

   Install @mastra/observability to trace Mastra; it is not included with confident-trace.

   Add confident-trace to your Mastra project. tsx is only needed if you run TypeScript source directly:

   npm install confident-trace '@mastra/core@>=1.64.0 <2' '@mastra/observability@>=1.17.5 <2'
   npm install -D tsx

2. Set Your API Keys

   Get your project API key from Confident AI and set it as an environment variable, along with the provider key your agent uses:

   export CONFIDENT_API_KEY="<your-confident-project-key>"
   export OPENAI_API_KEY="<your-openai-key>"

3. Initialize Tracing

   Call init() once when your app starts, before constructing Mastra. The preload attaches the Confident exporter to each Mastra instance automatically — no exporter, observability config, or wrapper is required:

   import { init } from "confident-trace";
   import { Mastra } from "@mastra/core";
   import { Agent } from "@mastra/core/agent";
   
   const runtime = init();
   
   const assistant = new Agent({
     id: "assistant",
     name: "Assistant",
     instructions: "You are a helpful assistant.",
     model: "openai/gpt-4.1-mini",
   });
   const mastra = new Mastra({ agents: { assistant }, logger: false });
   
   try {
     const result = await mastra.getAgent("assistant").generate("How do I make the best coffee?");
     console.log(result.text);
   } finally {
     await runtime.shutdown();
   }

4. Run Your Application

   Launch your entry-point file with the confident-trace/register preload so the SDK can hook Mastra as Node loads it. init() handles export, the preload handles instrumentation — you need both:

   # Running TypeScript source directly
   node --import tsx --import confident-trace/register src/index.ts
   
   # Running compiled JavaScript
   node --import confident-trace/register dist/index.js

   Done ✅. You can view the trace and its child spans on Confident AI's traces page inside the Observatory.

What Gets Captured

Mastra agent runs are exported with their original hierarchy intact, so you can follow the complete path from an agent or workflow through its model and tool calls.

• Agent and workflow execution — operation names, timing, status, and the parent-child relationships between steps.
• Model calls — model details, messages, finish reasons, and token usage.
• Tool calls — tool names and their input/output.
• Trace details — the root operation's name, tags, metadata, and input/output.
• Errors — failed operations retain their error status to make failures visible in the trace.

Captured inputs, outputs, and messages follow the content policy.

Set Trace Span Properties

Use a trace context to add properties you know before the call starts. It creates no extra span; the trace started by agent.generate() inherits the tags, metadata, user ID, and customer ID.

import { init, traceContext } from "confident-trace";

init();

const agent = mastra.getAgent("assistant");
const result = await traceContext(
  {
    tags: ["support"],
    metadata: { release: "2026-09" },
    userId: "user-42",
    customerId: "customer-7",
  },
  () => agent.generate("Explain OpenTelemetry in one sentence."),
);

See users and customers to set an optional display name alongside each ID, and trace context for every supported trace property and update behavior.

Instrumenting Multi-Turn

You do not need turn() when one Mastra entry-point call is already one conversational turn—the integration creates that turn's trace automatically. Use turn() when you want to define the boundary yourself, such as grouping two sequential Mastra calls into one turn. Reuse the same thread ID on later turns to group them into one conversation.

import { init, turn } from "confident-trace";

init();

const agent = mastra.getAgent("assistant");
const answer = await turn({ name: "support-turn", threadId: "chat-42" }, async () => {
  const context = await agent.generate("Find the relevant account details.");
  return agent.generate(`Summarize these details: ${context.text}`);
});

See threads for thread I/O, turn IDs, and user IDs.

Disable Mastra Instrumentation

Pass init() a list of integration identifiers to opt in to only those integrations. The identifier for Mastra is "mastra" in TypeScript; omit it to disable this integration. An empty list disables all automatic instrumentation:

import { init } from "confident-trace";
init({ instrumentations: [] });
// Use ["mastra"] to opt in; omit "mastra" to disable it.

This turns off Confident AI's automatic instrumentation; calls made after initialization are not instrumented by this integration.

Next Steps

Now that your Mastra agents are traced, dive deeper into:

Last updated on September 23, 2026