When a Mastra application grows from one agent into a workflow, a single response log stops being enough. An agent can generate a useful intermediate answer while a later tool fails. A workflow can finish while the user-facing action remains incomplete.
Mastra observability should connect agent execution, workflow steps, and the product conversation. Use Mastra’s exporter layer for supported execution traces, attach stable identity at the call boundary, and define outcomes from the system that actually performs the work.
Agnost AI receives Mastra traces over OpenTelemetry and supports a separate conversation SDK. The Mastra integration guide describes the available setup. Start with the exporter if your application already uses Mastra Observability; add a request wrapper only when it supplies a missing application boundary.
Worked example: the workflow returns before the export exists
An illustrative Mastra assistant creates a dashboard export. The workflow submits an export job and immediately tells the user the file is ready, but the export service still reports pending.
| Boundary | Evidence | Interpretation |
|---|---|---|
| Agent request | User asked for a downloadable file | The goal requires a usable artifact |
| Workflow submission | Service returned a job ID | Work was accepted, not completed |
| Status lookup | Job is pending or failed | The artifact is not ready |
| Public answer | “Your export is ready” | Completion claim exceeds the evidence |
The issue may be the workflow’s completion contract rather than model quality. Record the job ID as an approved reference and keep job acceptance separate from artifact readiness. If work continues in another process, propagate request context and instrument that worker; the web server’s trace will not observe it automatically.
A better product response to a pending job is an accurate pending state with a continuation mechanism your application supports. Verify the eventual file or external status before recording success. This is proposed handling for the example, not a claim that the sample adapter implements job polling.
Use Agnost to follow the user request, tool submission, and subsequent evidence. If the status lookup was never recorded, mark the outcome unknown instead of deriving it from the assistant’s wording.
Metrics that answer useful Mastra questions
Use these definitions to design your measurement plan. Calculate them from the required application or tracing evidence; they are not all precomputed dashboard metrics.
| Metric | Definition | Interpretation |
|---|---|---|
| Workflow execution failures | Failed workflow attempts / started attempts | Keep job submission and job completion distinct. |
| Confirmed action completion | Externally confirmed actions / eligible action requests | Pending work remains in its own state. |
| Time to usable result | Artifact-ready time minus initial request time | Includes queue time outside agent generation. |
Route Mastra traces to Agnost
For an existing Mastra application, install the observability and exporter dependencies, including the HTTP/protobuf transport:
Example scope: the code below is an integration adapter for an existing application. Configure its framework, model, credentials, and output contract as described; the demo screenshots were not generated by running these snippets.
npm install @mastra/observability @mastra/otel-exporter \
@opentelemetry/exporter-trace-otlp-protoThe following creates an exporter to add to your existing active observability configuration:
import { OtelExporter } from '@mastra/otel-exporter';
const orgId = process.env.AGNOST_ORG_ID;
if (!orgId) throw new Error('AGNOST_ORG_ID is required');
export const agnostExporter = new OtelExporter({
provider: {
custom: {
endpoint: 'https://otel.agnost.ai/v1/traces',
protocol: 'http/protobuf',
headers: { 'X-Agnost-Org-ID': orgId },
},
},
});Add agnostExporter to the exporters array inside the Observability configuration used by your Mastra instance. If you already export elsewhere, preserve that configuration deliberately. Creating an exporter object without registering it will not send traces.
Mastra’s OpenTelemetry documentation explains custom destinations and required transport packages. Keep package versions compatible with your existing Mastra release rather than upgrading the whole application solely to copy a snippet.
Attach user and conversation context
For your existing agent, pass the application identity with the request:
await agent.generate(prompt, {
tracingOptions: {
metadata: {
userId: authenticatedUserId,
conversationId: applicationConversationId,
agentVersion: 'support-v1',
},
},
});Here agent, prompt, and the identity values come from your application. Reuse the conversation ID for follow-up turns. Derive the user ID from authenticated server context, not an untrusted client claim. Agnost’s integration recognizes the documented user and conversation metadata keys; arbitrary metadata should not be assumed to become a built-in analytics dimension.
Inspect a real received event to confirm grouping. Trace parentage and product identity solve different problems: a span can have the correct parent while still lacking the user or conversation needed for product review.
Decide whether you also need a conversation wrapper
The npm package agnostai can wrap the public agent.generate() call using agnost.begin(...) and interaction.end(result.text). That records the input and final response you choose to expose. It does not replace deeper framework tracing.
Use a wrapper when you need a clearly defined public interaction or an approved, sanitized representation that differs from internal messages. Avoid adding it merely to make more records appear. If the wrapper and exported root span describe the same request, choose one for request counts and use the other for detail.
For streaming, end the public interaction at an explicit terminal state rather than when a stream object is created. For background workflows, define where a user’s job starts and what event proves completion.
Diagnose a workflow from the failing boundary backward
Consider an assistant that reads a support request, looks up an account, proposes a change, and calls an external service. Investigate the earliest point where the evidence diverges from the intended behavior.
| Symptom | Evidence to inspect |
|---|---|
| Correct proposal, no actual change | External operation result and any approval state |
| Wrong account used | Lookup input and account scope |
| Slow final answer | Dependent workflow steps and tool latency |
| Repeated actions | Attempt IDs and external action identifiers |
| Fragmented conversation | Metadata propagation across calls |
A successful generation only establishes that generation returned. If the change requires approval or asynchronous processing, preserve that pending state. Do not mark the user request resolved because a workflow step emitted confident text.
Store compact evidence such as operation status and resource reference. Avoid exporting full account records when a small allowlist is sufficient. Content capture can expand as you add tools, even if your original agent handled only harmless text.
Measure the boundaries separately
Keep three measurements distinct: public request duration, individual step duration, and completion of the external action. Parallel steps overlap, and queue time may occur outside agent generation. The user’s wait can include both.
For cost, verify which provider usage fields are actually present in exported spans. Missing usage should remain unknown. If an exporter or application reports both aggregate and child usage, avoid summing both levels.
In Agnost Users, inspect the full interaction. In Events, examine the received execution evidence. Configured intents can organize demand by user goal; they do not establish that the associated workflow succeeded.
Troubleshooting the integration
No traces arrive. Check that the exporter is registered in the active configuration, the endpoint includes /v1/traces, the protocol matches HTTP/protobuf, and the organization header is populated.
Some steps are missing. Check instrumentation coverage and whether execution moved to another process. An asynchronous job needs propagated context; a trace exporter in the web process cannot observe an uninstrumented worker.
A conversation appears several times. Inspect whether IDs change between turns or whether request and execution records are being treated as separate customers.
Production differs from local development. Review sampling, environment configuration, and lifecycle flushing. A short-lived runtime can terminate before buffered telemetry is exported.
Frequently asked questions
Do I need to rewrite my Mastra agents?
Usually the exporter belongs in the observability configuration and identity belongs at invocation. Custom boundaries are additional instrumentation for application behavior the framework cannot know.
Does a trace show whether the user accepted the result?
Only if the application records that evidence. Use an explicit acceptance, confirmed operation, or reviewed outcome rather than inferring satisfaction from a completed trace.
Use Agnost’s Mastra setup for configuration. For stream lifecycle concerns, read Vercel AI SDK monitoring.
Browse all agent observability guides by framework.