Observability

See production

Agents are non-deterministic, so production debugging is impossible without tracing. Mastra builds observability on OpenTelemetry: every model call, tool call, and workflow step emits a span, and those spans export to the tool of your choice. One request becomes one trace you can replay.

From call to dashboard

Each model/tool/step call emits an OpenTelemetry span; an exporter ships the trace to your backend where you debug and monitor.

What gets traced

A single trace stitches together the whole request: the agent’s reasoning, each tool call with its validated input/output, and — for workflows — every step, branch, and suspend/resume. Because it all flows through the one runtime, you get a coherent timeline instead of scattered logs.

Exporters

Point Mastra at an OTEL-compatible backend or a first-class integration (Langfuse, Braintrust). On a long-running host, tracing exports in the background; on serverless, flush before the function returns so spans aren’t lost:

// Serverless: flush pending traces before the invocation ends.
await mastra.getObservability().flush();

Redact sensitive data

Traces can capture prompts and tool I/O — scrub anything sensitive before it leaves your system with a sensitive-data filter, and sample in high-traffic paths so you keep signal without exporting every span.

Note

Exporter package names and tracing config are version-sensitive — the dossier at _Sources/ai-system/mastra/ pins the exact versions and current integrations. Confirm against what you install, and treat the snippet above as the shape of the API.

---

Reference: Observability overview · Tracing · Langfuse

Next: MCP — interoperate with the wider agent ecosystem.