---
title: Trace
description: 'A captured sequence of model calls, tool calls, events, timings, state changes, and outputs from an execution.'
canonical_url: 'https://darkfactory.dev/glossary/trace'
markdown_url: 'https://darkfactory.dev/glossary/trace.md'
collection: glossary
date_published: '2026-08-03T00:00:00-04:00'
date_modified: '2026-08-26T00:00:00-04:00'
---

# Trace


## Definition

A trace is a captured sequence of model calls, tool calls, events, timings, state changes, and outputs from an execution. In an agent system, it shows the path the run actually took through prompts, tools, permissions, retries, and decisions.

Source code describes possible behavior; the trace provides evidence about one execution. That evidence supports debugging, evaluation, cost analysis, incident response, and reconstruction of why an external effect occurred.

A useful trace carries stable run and span identifiers, component versions, causal relationships, errors, and links to produced artifacts. It also needs redaction, access control, and retention rules because prompts and tool results can contain secrets, personal data, or proprietary material.

## Distinguish it from nearby terms

A trajectory is the behavior sequence. A trace is the captured record of it. Lineage connects execution evidence into reconstructable provenance across artifacts and runs. Telemetry is the broader stream of operational measurements.

## Check your understanding

A trace records the final answer and latency but omits tool inputs, approval events, and state changes. It can measure response time, but it cannot explain who authorized the action or which data left the system.

## Also called

execution trace

## Related terms

- [Execution graph](https://darkfactory.dev/glossary/execution-graph)
- [Execution lineage](https://darkfactory.dev/glossary/execution-lineage)
- [Controlled self-improvement](https://darkfactory.dev/glossary/controlled-self-improvement)

## Related factory areas

- [Runtime operations, observability, incidents & healing](https://darkfactory.dev/factory/runtime-operations)

## Evidence and further reading

- [Shepherd: A Runtime Substrate Empowering Meta-Agents with a Formalized Execution Trace](https://arxiv.org/abs/2605.10913)
- [Execution Lineage for Reproducible AI-Native Work](https://arxiv.org/abs/2605.06365)
- [The Art of Loop Engineering: How to Build Agents That Improve Over Time](https://www.youtube.com/watch?v=jPPiZ22DY3g)