Understanding Agent Traces in Span
Last updated: June 3, 2026
The work artifact of the AI Era
An agent trace is a structured record of everything an AI coding agent did during a session. Each trace captures the sequence of actions the agent took: LLM calls, tool invocations (Bash commands, file edits, MCP server requests), subagent spawns, and the prompts and responses at every step. Traces also include metadata like token consumption, model used, session duration, and exit status. Think of it as a replay log that lets you see not just what the agent produced, but how it got there.
A pull request used to be the unit of engineering work. Today, the most consequential work happens upstream, inside the agent session: scoping the task, gathering context, steering the agent. The agent trace is what makes that upstream work visible. It captures the full interaction between an engineer and their AI tools, including prompts sent, MCP calls made, files edited, skills used, and the tokens spent.
Span pulls traces from Claude Code, Cursor, and other tools into one system of record, and when relevant connects each session back to the PR it produced.
That connection is a foundation of the suite. Downstream insight ties back to the work that produced it, so questions about AI adoption, quality, and more move from anecdote to evidence.
Agent Traces gives engineering leaders direct visibility into how their teams are actually using AI coding tools, so leaders can correlate AI-generated work with outcome metrics like PR cycle time and code quality to make data-driven decisions about AI tool effectiveness.
Getting Started
Approve the security doc provided. If it hasn’t been provided, please reach out your CSM.
Once approved, use these guides for installing your hooks:
For MacOS:
Download latest package: coding-hooks-1.10.7.pkg
Follow your MDM guide
[Optional] User self-install without MDM
For Windows: coming soon
For Linux: coming soon
If you have other MDM solutions not seen in this list, please reach out so we can support you.
Permissions
Leveraging our existing RBAC permissions, you can control who sees what on the trace list page. On this page, you can view trace metadata, associated PRs, evaluation scores, and the reasoning behind each eval score. The trace details and prompts are restricted to the author, regardless of permission settings.
To edit these settings, go to “People Groups” under Settings. From there, select a permissions group to edit its permissions. At the Teams level, the Agent Trace Summaries and Evals permission lets viewers see evals rolled up at the team level. At the People level, the Agent Trace Summary and Eval permission grants access to agent trace summaries and their correlated eval scores.
Trace details and prompts are not configurable and remain restricted to the author of the agent trace.
Leveraging Agent Traces inside of Span
Span uses agent traces as the foundation for visibility into how AI coding agents operate across your team.
AI Attribution
Because Span analyzes the trace alongside the diff, it can identify the lineage of code in each PR down to which specific lines an agent generated.
When a PR is created, traces are associated with the PR, and attribution is determined based on the chronology of file changes. You can see the results of this analysis in the PR catalog page.
The trace author can view a line-by-line diff showing attribution by file and by line.
Trace View
The Traces view is searchable, filterable record of AI-assisted work across your org. When a PR's behavior surprises you, when an engineer wants to learn from a session that went sideways, or when a reviewer needs to understand intent before approving, the underlying trace is one click away.
Sensitive data is redacted on ingest, and sessions are private by default. The prompts and full trace conversations are only visible to the engineer who authored the trace unless explicitly shared.
When you click into the sidebar, you will be able to see the metadata of the trace and the the breakdown of the evaluations for each trace with an explanation of the scores.
For the trace authors only, they can click on the an “Inspect Trace” Trace details to see the full conversation with accompanying citations.
Effectiveness Scorecard
Effectiveness scorecard gives you the leadership view. ****Span runs agent evals against your traces, asking structured questions of each session and synthesizing results across thousands of interactions. Eval scores roll up into trends you can slice by team, repo, or topic area.
This is where leaders answer questions like "is our prompt quality improving?" or "which teams are getting leverage from AI, and which are stuck?" When a score dips, you can drill into the specific traces driving the change.
From this scorecard view, you can see scores over time for the Overall Score or each theme individually. You can additionally, filter by team or timeframe to adjust the view of the charts and scores in the Breakdown table.
You can view the breakdown by team or by individual. This is the primary view for understanding how effective different teams or repos are within your organization.
When you click the Traces icon on the right, you can see a list of traces that contribute most to lowering the score. This can help you identify where improvements can be made.
Task Classification
Each agent trace undergoes a categorization, so you can view how your tools are most often used. We categorize these 11 categories:
Code understanding and exploration
Debugging
New Features
Design and planning
Writing Tests
Infrastructure and DevOps
Documentation
Front-end Development
Data Sciene
Other
Categorizes each agent trace by the type of work performed. This lets you break down agent usage by task type and understand where agents are being applied most. You will also be able to see a breakdown of model usage and Autonomy ratio. Autonomy ratio is the number of turns an agent can take without intervention and is a barometer of how agentic your tools are.
Need Help?
If you have questions about the AI Spend Report or need assistance:
Contact your Span account team
Reach out to support@span.app