Trace Intelligence on Mastra platform
Trace Intelligence finds recurring patterns across your agent's interactions. It analyzes traces captured by Mastra Observability, produces trace signals for four dimensions, and clusters similar trace signals into themes.
Use Trace Intelligence to investigate questions such as:
- What are users trying to accomplish?
- Which goals tend to succeed, remain unresolved, or become blocked?
- Which agent behaviors appear in successful and unsuccessful interactions?
- How does user sentiment relate to goals and outcomes?
Trace Intelligence is available by invitation for selected Mastra platform projects.
Get accessDirect link to Get access
- Submit the Trace Intelligence private beta form to request access.
- Confirm that Mastra platform Observability is enabled and that completed agent traces appear under Traces.
- Requires at least
@mastra/core@1.53.0andmastra@1.20.2. Upgrade your project then deploy or redeploy Studio for the enrolled project. Local Studio and server-only deployments aren't supported during the private beta. - Open the deployed Studio and select Intelligence in the sidebar.
- Send representative traffic to your agent and allow time for analysis.
Once Mastra enrolls the project, you don't need to change your agent definition or calls.
When data is availableDirect link to When data is available
Trace Intelligence needs enough processed traces from one agent to identify recurring patterns. Initial themes are usually available after at least 100 completed traces from that agent have been processed.
The trace count under Traces can reach 100 before Trace Intelligence is ready because the analysis pipeline runs asynchronously. Processing can take several minutes after the threshold is reached. Traces that can't be analyzed don't contribute, so 100 is a minimum, not an exact UI trigger.
Trace Intelligence updates automatically as more traces arrive. Studio needs themes for at least two trace signal types before it can display the relationship flow.
Use representative traffic. A small set of repeated test prompts can produce unrepresentative results, such as one broad theme or mostly Noise.
Understand the analysisDirect link to Understand the analysis
Each analyzable completed trace produces four trace signals:
| Trace signal | Meaning |
|---|---|
| Goal | What the user is trying to achieve or have completed. |
| Outcome | The final completed, partial, blocked, failed, unresolved, or unclear state. |
| Behavior | Observable agent actions and patterns, including tool use, omissions, retries, failures, and recovery. |
| Sentiment | The user's emotional state or attitude. |
Themes are clusters generated from similar trace signals. Clustering happens independently for each trace signal type. One trace can belong to a separate theme in every dimension: Goal, Outcome, Behavior, and Sentiment.
Themes and relationshipsDirect link to Themes and relationships
The flow chart connects themes in adjacent trace signal columns:
- A node represents a theme. Its count is the number of distinct traces assigned to that theme in the selected snapshot.
- A ribbon connects traces assigned to themes in both adjacent columns. Its width represents the shared trace count.
- Hover over or focus a node or ribbon to isolate its relationships.
The flow shows association, not causation or execution order. For example, a ribbon between a Goal and an Outcome means that both themes occurred in the same traces. It doesn't show that the goal caused the outcome.
Distributions, Other, and NoiseDirect link to Distributions, Other, and Noise
The cards below the flow show each trace signal's theme distribution:
- Trace count: The number of distinct traces assigned to a theme in the selected snapshot.
- Stage share: The percentage of analyzed traces for that trace signal assigned to the theme.
Studio shows the most common themes for each trace signal type. It may combine smaller themes into Other to preserve totals without overcrowding the chart.
Noise contains summaries that didn't consistently match a recurring theme in the selected snapshot. It doesn't necessarily indicate an error or a low-quality interaction. Noise can include rare requests and emerging patterns. It can also contain ambiguous interactions or unrelated cases. A large Noise share can indicate highly varied traffic or insufficient data for stable themes.
SnapshotsDirect link to Snapshots
A snapshot is a moving analysis window over a set of traces. Snapshots can overlap, so don't add their trace counts together. Compare trace count and stage share together because traffic volume can change between windows.
A theme can persist, disappear, split, merge, or return across snapshots. Treat theme names and descriptions as generated summaries, not fixed taxonomies.
Use the Trace Intelligence pageDirect link to Use the Trace Intelligence page
- Use the Agent selector to switch between agents with available analysis. An agent doesn't appear until its first themes are ready.
- Select a theme in the flow to filter every column to traces containing that theme.
- Select View theme details to inspect its description, trace count, stage share, generated examples, and history.
- Select Clear filter to restore the complete flow.
You can also:
- Select a theme in a distribution card to open its details and generated example summaries.
- Select Noise in a distribution card to inspect its distribution and generated example summaries.
- Drag the distribution cards to reorder the trace signal columns and see a different relationship perspective.
- Use the timeline to select a snapshot, or select Play to watch themes change over time.
- Open a theme's history to see whether it persisted and how its coverage changed.
Filtering the flow by a theme is unavailable for snapshots with more than 2,000 traces. Choose another snapshot or clear the active filter to return to the full flow. Theme and Noise details remain available from the distribution cards.
TroubleshootingDirect link to Troubleshooting
Intelligence isn't in the sidebarDirect link to Intelligence isn't in the sidebar
Confirm that Mastra enrolled the correct project, that you use the beta-compatible Mastra version, and that you redeployed Studio. The private beta doesn't support local Studio.
An agent is missingDirect link to An agent is missing
Confirm that its completed traces are listed under Traces. The agent is listed only after its first themes are ready. If it recently reached 100 traces, allow time for asynchronous processing.
The relationship flow is unavailableDirect link to The relationship flow is unavailable
The flow requires themes for at least two trace signal types. Continue sending representative traffic and allow processing to finish.
Most summaries are NoiseDirect link to Most summaries are Noise
Collect more representative traffic and compare a later snapshot. Varied or rare interactions are harder to group, while repeated test prompts can produce an unrepresentative distribution.
Private-beta limitationsDirect link to Private-beta limitations
- Trace Intelligence is available only for enrolled projects in deployed Studio.
- Initial analysis requires at least 100 processed traces per agent. Some agents may require more.
- Results depend on the diversity and quality of captured traces.
- Trace signal summaries, theme labels, clustering, thresholds, and UI behavior can change during the beta.
When reporting feedback, include the organization ID, project ID, agent ID, selected snapshot, and the theme or Noise examples that illustrate the issue.