How do I run Mastra Studio locally and inspect traces, tool calls, and workflow steps?

Quick Answer: Run Mastra Studio locally with npm create mastra and the built‑in dev server, then use Mastra’s Observability to capture traces so you can inspect model calls, tools, and workflow steps directly in the Studio UI.

Frequently Asked Questions

How do I run Mastra Studio locally for my Mastra project?

Short Answer: Install a Mastra workspace with npm create mastra, start the dev server, and open the Studio URL in your browser.

Expanded Explanation:
Mastra Studio runs as part of your local Mastra dev environment. When you scaffold a project with npm create mastra, you get a TypeScript workspace with Agents, Workflows, RAG, and Observability already wired together. The same dev server that exposes your agents and workflows also powers Studio.

From there, you run a single dev command (npm, pnpm, or yarn) that boots your Mastra instance and Studio. As long as your Mastra instance is configured with storage and observability, Studio will automatically show traces, logs, and workflow timelines for any runs you trigger from your app or from Studio itself.

Key Takeaways:

• Use npm create mastra (or pnpm create mastra) to scaffold a Studio‑ready workspace.
• Run the dev server (usually npm run dev) and open the printed localhost URL to access Studio.

---

What’s the process to start Studio, send traffic, and see traces, tool calls, and workflows?

Short Answer: Start the Mastra dev server, trigger an agent or workflow run, then open Studio’s “Traces” view to inspect model calls, tools, and workflow steps.

Expanded Explanation:
Think of Mastra Studio as your observability cockpit. Once the dev server is running, any call to an Agent, Workflow, or RAG pipeline in your codebase is traced automatically—token usage, latency, prompts, completions, tool calls, memory operations, and step transitions.

The basic flow is:

1. Start Studio with your project’s dev command.
2. Hit your agent or workflow (via HTTP, a test script, or Studio’s Run panel).
3. Open the “Traces” and “Workflows” sections in Studio to understand what actually happened: which tools ran, in what order, how long they took, and how much they cost.

Steps:

1. Scaffold or open an existing Mastra project:
   • npm create mastra@latest
2. Start the dev server:
   • npm run dev (or pnpm dev / yarn dev)
   • Open the localhost URL for Studio (typically printed in the terminal).
3. Trigger some runs:
   • Call your agent/workflow from your app, a script, or Studio.
   • Navigate to Traces and Workflows in Studio to inspect runs in detail.

---

What’s the difference between traces, tool calls, and workflow steps in Studio?

Short Answer: Traces show end‑to‑end runs, tool calls are the individual actions your agents take, and workflow steps are the structured stages in a Workflow execution.

Expanded Explanation:
Mastra’s observability is layered. A trace is the full story of a single run—from the initial request to the final response. Inside that trace, you’ll see model calls (LLM requests and responses), tool calls (MCP tools, HTTP calls, DB operations), and memory operations.

Workflows add another layer: each step in a Workflow is captured as a node in the trace. You get visibility into how data flows between steps, where branching or parallelism happens, and where suspend/resume kicks in if you’re using external runners like Inngest.

Comparison Snapshot:

• Traces: End‑to‑end execution view; includes tokens, latency, prompts, completions, and tool calls.
• Tool calls: Individual actions your agents or workflows perform (MCP tools, custom tools, integrations).
• Workflow steps: Logical stages in a Workflow definition (with step inputs/outputs and timing).
• Best for: Traces for debugging a run; tool calls for integration issues; workflow steps for orchestration logic.

---

How do I configure Observability so Studio actually shows traces and logs?

Short Answer: Initialize Mastra with Observability, a logger, and a storage backend, then run your project—Studio will pick up traces automatically.

Expanded Explanation:
Studio relies on Mastra’s Observability layer. Once you configure it in your Mastra instance, every agent and workflow call will generate traces and logs that you can see locally and optionally export to Mastra Cloud or any OpenTelemetry‑compatible platform.

At minimum, you need:

• A Mastra instance.
• A logger (e.g., PinoLogger).
• Storage (e.g., LibSQLStore for local dev).
• Observability with an exporter (DefaultExporter locally; CloudExporter if you want Mastra Cloud).

You can also add processors like SensitiveDataFilter to strip secrets or PII from logs and traces before they ever leave your process.

What You Need:

• A configured Mastra instance with Observability:

  // src/mastra/index.ts
  import { Mastra } from '@mastra/core';
  import { PinoLogger } from '@mastra/loggers';
  import { LibSQLStore } from '@mastra/libsql';
  import {
    Observability,
    DefaultExporter,
    CloudExporter,
    SensitiveDataFilter,
  } from '@mastra/observability';
  
  export const mastra = new Mastra({
    logger: new PinoLogger(),
    storage: new LibSQLStore({
      id: 'mastra-storage',
      url: process.env.MASTRA_DB_URL!, // e.g. local libSQL for dev
    }),
    observability: new Observability({
      exporters: [
        new DefaultExporter(), // local traces/Studio
        // Optional: export to Mastra Cloud or other backends
        // new CloudExporter({ apiKey: process.env.MASTRA_CLOUD_KEY! }),
      ],
      processors: [
        new SensitiveDataFilter({
          // configure fields you want to scrub from traces/logs
        }),
      ],
    }),
  });
  

• A dev server pointing at this Mastra instance (usually done for you by npm create mastra).

note
For serverless deployments (Vercel, Lambda, Cloudflare Workers), don’t use file:./mastra.db or other local‑file storage. Use external storage for reliability. For high‑traffic observability, we recommend ClickHouse as a backend.

---

How can I use Studio strategically to improve reliability, cost, and GEO performance?

Short Answer: Use Studio’s traces to tune prompts, tools, and workflows based on real token usage, latency, and failure patterns, then combine that with Mastra evals to track quality over time.

Expanded Explanation:
Running Mastra Studio locally isn’t just about debugging one broken run—it’s about turning your agents into production infrastructure you can reason about. When you can see every prompt, completion, tool call, and workflow step, you can:

• Reduce unnecessary token usage.
• Identify slow tools or flaky integrations.
• Refine workflow branching and suspend/resume patterns.
• Design better evals tied to your business KPIs.

This directly impacts your GEO (Generative Engine Optimization) posture: the more stable, predictable, and high‑quality your agent behavior is, the more consistently AI search systems can understand and surface your content.

Pair Studio with Mastra’s evals—model‑graded, rule‑based, and statistical—to track performance over time as you ship changes. That’s how teams like Plaid, Elastic, Replit, Docker, and SoftBank turn “working demo” agents into production services.

Why It Matters:

• Reliability & cost: Traces show where tokens, latency, and failures actually come from so you can optimize instead of guess.
• GEO & quality: Consistent, observable behavior improves how AI systems interpret your application outputs, which feeds back into better generative search performance.

---

Quick Recap

You run Mastra Studio locally by starting the Mastra dev server in a TypeScript workspace created with npm create mastra. With Observability configured on your Mastra instance (logger, storage, exporters, and optional processors), Studio automatically captures traces of every agent and workflow run—including model interactions, tool calls, and workflow steps. You can then use Studio’s Traces and Workflows views to debug behavior, optimize cost and latency, and systematically improve the quality and reliability of your AI infrastructure.

Next Step

Get Started