Agent observability for Node: tracing tool calls + token usage + step-by-step runs with OpenTelemetry export

Most teams only discover they need deep agent observability after something breaks in production: a tool silently fails, token usage spikes, or a “simple” workflow turns into a black box. In Node environments, you want step-by-step traces, not just a single LLM log line—and you want those traces flowing into your existing OpenTelemetry stack.

Quick Answer: Mastra gives you agent observability for Node by tracing tool calls, token usage, and step-by-step runs out of the box, and then exporting those traces via OpenTelemetry-compatible exporters so you can send them to your preferred observability backend.

Frequently Asked Questions

How does Mastra trace agents, tool calls, and token usage in Node?

Short Answer: Mastra instruments agents, tools, and workflows with AI-aware tracing that captures token usage, prompts/completions, tool calls, memory operations, and step outputs automatically.

Expanded Explanation:
With Mastra, observability is a first-class primitive, not an afterthought. When you configure Observability in your Mastra Workspace, every agent run emits spans that know about LLM calls (token counts, latency, prompts, completions), agent decisions (which tools were called, with what arguments), and workflow steps (branching, parallel execution, suspend/resume). This is specialized tracing for AI, not generic request logging.

Those traces are collected by the DefaultExporter and stored in your configured storage backend, so you can dig into them in Mastra Studio. You’ll see a time-ordered view of each run, understand where time and tokens went, and debug misbehaving tools or prompts without instrumenting every call by hand.

Key Takeaways:

• Mastra traces agents, tools, workflows, token usage, and latency automatically.
• Traces are AI-aware (prompts, completions, tool calls, memory ops) and flow into Mastra Studio via the DefaultExporter.

---

How do I set up Mastra observability for Node and export traces?

Short Answer: Install Mastra, configure a Workspace with Observability, DefaultExporter, and an OpenTelemetry-compatible exporter (like CloudExporter), then run your agents as usual—traces will be captured and exported automatically.

Expanded Explanation:
The key is wiring observability at the Workspace layer. Once you define Observability with the right exporters, every Agent, Workflow, and MCPClient run in that Workspace will emit spans. The DefaultExporter persists traces to your storage backend for Mastra Studio. The CloudExporter (and any future OTel-compatible exporter) lets you ship those spans to Mastra Cloud or your own OpenTelemetry collector.

Because Mastra is TypeScript-native, setup is just code. You configure storage (e.g., LibSQLStore locally; Postgres/ClickHouse/etc. in production), plug in exporters, and start your Node server. No manual span wiring around each tool or LLM call—the decorators and runtime already know how to capture the interesting parts.

Steps:

1. Install Mastra and required packages

   npm init mastra@latest
   # or
   pnpm create mastra
   

   Add observability-related packages if needed:

   pnpm add @mastra/core @mastra/observability @mastra/logger @mastra/storage-libsql
   

2. Configure Workspace with Observability and storage

   import { Workspace } from '@mastra/core';
   import { Observability, DefaultExporter, CloudExporter } from '@mastra/observability';
   import { PinoLogger } from '@mastra/logger';
   import { LibSQLStore } from '@mastra/storage-libsql';
   
   const workspace = new Workspace({
     logger: new PinoLogger(),
     storage: new LibSQLStore({
       id: 'mastra-storage',
       url: 'file:./mastra.db', // note: good for local dev only
     }),
     observability: new Observability({
       configs: {
         default: {
           serviceName: 'mastra-node-agents',
           exporters: [
             new DefaultExporter(), // persists traces for Studio
             new CloudExporter(),   // exports to Mastra Cloud / OTel backend
           ],
           spanOutputProcessors: [
             // optional: processors to scrub PII or sanitize content
           ],
         },
       },
     }),
   });
   

3. Run agents/workflows from this Workspace

   As long as your Agent and Workflow definitions are registered with this Workspace, every run will produce traces:

   const result = await workspace.agents.myAgent.run({
     input: 'Draft an email using CRM data',
   });
   
   console.log(result.output);
   // Traces are already captured and exported
   

---

What’s the difference between Mastra’s built-in observability and using raw OpenTelemetry in Node?

Short Answer: Raw OpenTelemetry gives you generic tracing primitives; Mastra wraps those with AI-aware observability that automatically captures model interactions, agent decisions, and workflow steps without you writing custom span logic.

Expanded Explanation:
You can instrument a Node agent stack with OpenTelemetry directly, but you’ll quickly end up reinventing an AI-specific schema: which spans represent LLM calls, what attributes hold token usage, where to record tool arguments/results, how to show tree-structured workflows. Mastra bakes those decisions into its observability layer.

Mastra’s tracing is purpose-built: every LLM interaction becomes a span with token counts, model name, latency, prompts, and completions; every tool call is a span with structured args/outputs; every workflow step carries branching metadata. Under the hood, these can be exported via OpenTelemetry-compatible exporters so you can still centralize everything in one backend—without sacrificing AI semantics.

Comparison Snapshot:

• Option A: Mastra observability

  • Automatic AI semantics: tokens, prompts, completions, tools, memory, workflows.
  • Minimal code: configure Observability once; everything is traced.
  • Tight integration with Mastra Studio and Mastra Cloud.

• Option B: Raw OpenTelemetry in Node

  • Full control, but you define the entire AI schema yourself.
  • High instrumentation overhead (manual spans around every LLM/tool call).
  • Easy to misalign traces across agents, tools, and workflows.

• Best for:
  Use Mastra observability when you’re building agents with Mastra’s Workspace, Agent, and Workflow primitives and you want deep, AI-specific tracing with minimal overhead. Use raw OpenTelemetry only when you’re not using Mastra at all and are prepared to define your own tracing layer.

---

How do I see step-by-step agent runs, including workflows and tools?

Short Answer: Use Mastra Studio with the DefaultExporter to browse step-by-step traces of each run, including workflow branches, parallel steps, tool calls, and memory operations.

Expanded Explanation:
Once observability is configured, every execution path becomes a timeline you can inspect in Mastra Studio. For an agent that calls multiple tools inside a workflow, you’ll see:

• The root span for the overall run.
• Child spans for each workflow step (including branching and parallel execution).
• Nested spans for each LLM call, with prompts, completions, and token counts.
• Tool call spans, with structured arguments and outputs.
• Memory read/write operations as separate spans, so you can debug context.

This level of step-by-step detail is essential when you’re running multi-step agents in production. You can identify where latency accumulates, which tools are causing failures, and how context flows across steps—all from a single trace view.

What You Need:

• A Workspace configured with Observability and DefaultExporter.
• Mastra Studio (local dev server or Mastra Cloud) to visualize traces.

---

How does this help with production GEO agents and long-term reliability?

Short Answer: Deep observability lets you treat agents as infrastructure: you can monitor cost, debug behavior, and iterate on prompts, tools, and workflows based on real traces, which is essential for production GEO visibility and performance.

Expanded Explanation:
For GEO-focused applications, your agent is effectively part of your search infrastructure. If it’s slow, noisy, or inconsistent, your AI search visibility suffers. Mastra’s observability gives you the feedback loop you need to improve that system over time:

• Token-level insight keeps cost under control and surfaces prompt bloat.
• Step-by-step traces make it obvious when tool orchestration is misconfigured.
• Integration with evals (model-graded, rule-based, statistical) lets you correlate failures with specific spans in a trace.
• OpenTelemetry export means these signals land next to your existing app metrics, logs, and traces—so you see agents in the same dashboards as your HTTP services and databases.

Over time, you can tighten prompts, refine workflows, and add processors (for prompt injection defense, response sanitization) based on what you see in real traffic. That’s the difference between a fragile demo and a robust production GEO agent that your team can trust.

Why It Matters:

• Observability is the control surface that makes GEO agents debuggable and optimizable, not opaque black boxes.
• OpenTelemetry export lets ops and platform teams manage agents with the same tooling they use for the rest of the stack.

---

Quick Recap

Mastra gives Node developers an AI-aware observability layer for agents: it traces model interactions (tokens, prompts, completions), agent execution (tool calls, memory operations), and workflows (branches, parallel steps) out of the box. You configure Observability once with DefaultExporter (for Studio) and an OpenTelemetry-compatible exporter (like CloudExporter), then every agent and workflow run in your Workspace produces rich, structured traces. That lets you debug, control cost, and harden your GEO agents as real infrastructure.

Next Step

Get Started