trace-summary

Compact human-readable summary of a JSONL agent trace — costs, tokens, errors, tools, duration.

Zero dependencies. Python 3.10+. MIT.

Install

pip install trace-summary

Usage

from trace_summary import summarize_file

s = summarize_file("logs/run.jsonl")
print(s)

Events:        142
Errors:        3
Cost:          $0.0847
Tokens:        48,200 (in=32,100 out=16,100)
Duration:      183.4s
Lanes:         supervisor, worker-1, worker-2
Event kinds:   tool_call=89, llm_call=42, log=11
Tool calls:    web_search×45, read_file×28, arxiv_search×16

From a list of dicts

from trace_summary import summarize_trace

events = load_my_events()
s = summarize_trace(events)
print(f"${s.total_cost_usd:.4f} across {s.event_count} events")

What it reads

The library auto-detects common field names used across different agent frameworks:

Field type	Recognized keys
Cost	cost_usd, cost, price_usd, usd
Tokens in	tokens_in, input_tokens, prompt_tokens
Tokens out	tokens_out, output_tokens, completion_tokens
Timestamp	timestamp, ts, time, created_at, at
Tool name	tool, tool_name, name, step
Error	error, err, exception
Event kind	kind, type, event_type
Lane	lane

CLI

trace-summary run.jsonl

API

summarize_file(path, *, tool_kinds=None) -> TraceSummary

summarize_trace(events, *, tool_kinds=None) -> TraceSummary

TraceSummary

@dataclass
class TraceSummary:
    event_count: int
    error_count: int
    total_cost_usd: float
    total_tokens_in: int
    total_tokens_out: int
    first_ts: float | None
    last_ts: float | None
    duration_seconds: float | None
    tool_counts: dict[str, int]
    kind_counts: dict[str, int]
    lanes: set[str]

    @property
    def total_tokens(self) -> int: ...
    def render(self, *, color=False) -> str: ...

License

MIT