nullius-eval 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- _nullius_app/.env.example +55 -0
- _nullius_app/app.py +96 -0
- _nullius_app/requirements.txt +1 -0
- _nullius_app/static/brand/README.md +20 -0
- _nullius_app/static/brand/docker.svg +1 -0
- _nullius_app/static/brand/favicon.svg +1 -0
- _nullius_app/static/brand/huggingface.svg +37 -0
- _nullius_app/static/brand/mark-dark.svg +1 -0
- _nullius_app/static/brand/marks.svg +34 -0
- _nullius_app/static/brand/tokens.json +51 -0
- _nullius_app/static/brand/typesafe.png +0 -0
- _nullius_app/static/brand/wordmark-dark.svg +1 -0
- _nullius_app/static/builder/command-builder-core.js +763 -0
- _nullius_app/static/builder/command-builder.css +248 -0
- _nullius_app/static/builder/command-builder.js +997 -0
- _nullius_app/static/builder/model-picker.js +113 -0
- _nullius_app/static/catalogue/add.js +46 -0
- _nullius_app/static/catalogue/agents/README.md +19 -0
- _nullius_app/static/catalogue/agents/goose.svg +1 -0
- _nullius_app/static/catalogue/agents/jiuwenswarm.svg +33 -0
- _nullius_app/static/catalogue/agents/marks.json +8 -0
- _nullius_app/static/catalogue/agents/mini-swe-agent.svg +7 -0
- _nullius_app/static/catalogue/agents/opencode.svg +7 -0
- _nullius_app/static/catalogue/catalogue.css +436 -0
- _nullius_app/static/catalogue/catalogue.js +87 -0
- _nullius_app/static/catalogue/marks.svg +29 -0
- _nullius_app/static/catalogue/new.js +78 -0
- _nullius_app/static/catalogue/versions.js +27 -0
- _nullius_app/static/compare/comparison.css +117 -0
- _nullius_app/static/controls.js +117 -0
- _nullius_app/static/disclosures.js +70 -0
- _nullius_app/static/fonts/0569c822cab6c510.ttf +0 -0
- _nullius_app/static/fonts/DMSans-Medium.woff2 +0 -0
- _nullius_app/static/fonts/DMSans-Regular.woff2 +0 -0
- _nullius_app/static/fonts/IBMPlexMono-Medium.woff2 +0 -0
- _nullius_app/static/fonts/IBMPlexMono-Regular.woff2 +0 -0
- _nullius_app/static/fonts/InstrumentSerif-Italic.woff2 +0 -0
- _nullius_app/static/fonts/InstrumentSerif-Regular.woff2 +0 -0
- _nullius_app/static/fonts/README.md +11 -0
- _nullius_app/static/fonts/c1e7453ea26a1d1e.ttf +0 -0
- _nullius_app/static/fonts/dmsans-OFL.txt +93 -0
- _nullius_app/static/fonts/ibmplexmono-OFL.txt +93 -0
- _nullius_app/static/fonts/instrumentserif-OFL.txt +93 -0
- _nullius_app/static/fonts.css +49 -0
- _nullius_app/static/notifications.js +49 -0
- _nullius_app/static/onboarding.css +78 -0
- _nullius_app/static/onboarding.js +158 -0
- _nullius_app/static/runs/board.css +358 -0
- _nullius_app/static/runs/board.js +127 -0
- _nullius_app/static/runs/launches.css +88 -0
- _nullius_app/static/runs/live-board.css +186 -0
- _nullius_app/static/runs/live-board.js +394 -0
- _nullius_app/static/runs/path-suggestions.js +119 -0
- _nullius_app/static/runs/start.css +38 -0
- _nullius_app/static/settings/autosave.js +162 -0
- _nullius_app/static/settings/custom-keys.js +100 -0
- _nullius_app/static/settings/data-providers.js +88 -0
- _nullius_app/static/settings/judges.js +61 -0
- _nullius_app/static/settings/modal.css +32 -0
- _nullius_app/static/settings/modal.js +91 -0
- _nullius_app/static/settings/navigation.js +55 -0
- _nullius_app/static/settings/prices.js +68 -0
- _nullius_app/static/settings/providers.js +134 -0
- _nullius_app/static/settings/sandbox.js +20 -0
- _nullius_app/static/settings/settings.css +288 -0
- _nullius_app/static/style.css +1752 -0
- _nullius_app/static/traces/conversation.css +49 -0
- _nullius_app/static/traces/conversation.js +215 -0
- _nullius_app/templates/agents/entry.html +145 -0
- _nullius_app/templates/agents/kits.html +55 -0
- _nullius_app/templates/agents/standard.html +58 -0
- _nullius_app/templates/base.html +479 -0
- _nullius_app/templates/builder/new_run.html +55 -0
- _nullius_app/templates/catalogue/add_dialog.html +32 -0
- _nullius_app/templates/catalogue/benchmark.html +270 -0
- _nullius_app/templates/catalogue/benchmarks.html +91 -0
- _nullius_app/templates/catalogue/new.html +141 -0
- _nullius_app/templates/catalogue/use_bundle.html +11 -0
- _nullius_app/templates/compare/_detail.html +37 -0
- _nullius_app/templates/compare/compare.html +298 -0
- _nullius_app/templates/compare/compare_picker.html +51 -0
- _nullius_app/templates/compare/compare_task.html +329 -0
- _nullius_app/templates/runs/_execution.html +131 -0
- _nullius_app/templates/runs/_runtime.html +5 -0
- _nullius_app/templates/runs/ascii-mark.html +485 -0
- _nullius_app/templates/runs/feasibility.html +127 -0
- _nullius_app/templates/runs/index.html +609 -0
- _nullius_app/templates/runs/job.html +460 -0
- _nullius_app/templates/runs/preparing.html +14 -0
- _nullius_app/templates/runs/reconcile.html +124 -0
- _nullius_app/templates/runs/setup.html +272 -0
- _nullius_app/templates/runs/start.html +51 -0
- _nullius_app/templates/settings/custom_keys.html +82 -0
- _nullius_app/templates/settings/data_providers.html +27 -0
- _nullius_app/templates/settings/settings.html +564 -0
- _nullius_app/templates/traces/_charts.html +165 -0
- _nullius_app/templates/traces/_conversation.html +37 -0
- _nullius_app/templates/traces/_judgement.html +72 -0
- _nullius_app/templates/traces/artifact.html +15 -0
- _nullius_app/templates/traces/trial.html +838 -0
- _nullius_app/templates/workspaces/workspaces.html +54 -0
- _nullius_app/web/__init__.py +1 -0
- _nullius_app/web/agents.py +230 -0
- _nullius_app/web/builder.py +406 -0
- _nullius_app/web/catalogue.py +370 -0
- _nullius_app/web/compare.py +489 -0
- _nullius_app/web/core.py +17 -0
- _nullius_app/web/execute.py +223 -0
- _nullius_app/web/feasibility.py +60 -0
- _nullius_app/web/filters.py +231 -0
- _nullius_app/web/judge.py +623 -0
- _nullius_app/web/judge_tasks.py +33 -0
- _nullius_app/web/onboarding.py +20 -0
- _nullius_app/web/reconcile.py +47 -0
- _nullius_app/web/runs.py +464 -0
- _nullius_app/web/settings.py +324 -0
- _nullius_app/web/shared.py +507 -0
- _nullius_app/web/traces.py +306 -0
- _nullius_app/web/workspaces.py +84 -0
- nullius/__init__.py +32 -0
- nullius/__main__.py +5 -0
- nullius/catalogue/__init__.py +0 -0
- nullius/catalogue/agents/codex/agent.json +222 -0
- nullius/catalogue/agents/codex/config.toml +25 -0
- nullius/catalogue/agents/goose/agent.json +131 -0
- nullius/catalogue/agents/goose/config.yaml +20 -0
- nullius/catalogue/agents/jiuwenswarm/agent.json +197 -0
- nullius/catalogue/agents/jiuwenswarm/agent.py +355 -0
- nullius/catalogue/agents/mini-swe-agent/agent.json +68 -0
- nullius/catalogue/agents/mini-swe-agent/run.py +37 -0
- nullius/catalogue/agents/opencode/agent.json +135 -0
- nullius/catalogue/agents/opencode/opencode.json +32 -0
- nullius/catalogue/agents/reference/agent.json +89 -0
- nullius/catalogue/agents/reference/agent.py +209 -0
- nullius/catalogue/agents/terminus-2/agent.json +64 -0
- nullius/catalogue/agents/terminus-2/run.py +139 -0
- nullius/catalogue/benchmarks/gaia/benchmark.json +72 -0
- nullius/catalogue/benchmarks/gaia/data-source.json +29 -0
- nullius/catalogue/benchmarks/gaia/driver.py +188 -0
- nullius/catalogue/benchmarks/gaia/env/data.Dockerfile +1 -0
- nullius/catalogue/benchmarks/gaia/standard.json +278 -0
- nullius/catalogue/benchmarks/gaia/upstream-settings.json +275 -0
- nullius/catalogue/benchmarks/gsm8k/benchmark.json +34 -0
- nullius/catalogue/benchmarks/gsm8k/driver.py +101 -0
- nullius/catalogue/benchmarks/gsm8k/standard.json +124 -0
- nullius/catalogue/benchmarks/gsm8k/upstream-settings.json +86 -0
- nullius/catalogue/benchmarks/humaneval/benchmark.json +36 -0
- nullius/catalogue/benchmarks/humaneval/driver.py +243 -0
- nullius/catalogue/benchmarks/humaneval/standard.json +115 -0
- nullius/catalogue/benchmarks/humaneval/upstream-settings.json +72 -0
- nullius/catalogue/benchmarks/locomo/benchmark.json +43 -0
- nullius/catalogue/benchmarks/locomo/driver.py +270 -0
- nullius/catalogue/benchmarks/locomo/standard.json +265 -0
- nullius/catalogue/benchmarks/locomo/upstream-settings.json +112 -0
- nullius/catalogue/benchmarks/longmemeval/benchmark.json +65 -0
- nullius/catalogue/benchmarks/longmemeval/driver.py +379 -0
- nullius/catalogue/benchmarks/longmemeval/standard.json +733 -0
- nullius/catalogue/benchmarks/longmemeval/upstream-settings.json +76 -0
- nullius/catalogue/benchmarks/swe-bench-verified/benchmark.json +87 -0
- nullius/catalogue/benchmarks/swe-bench-verified/driver.py +116 -0
- nullius/catalogue/benchmarks/swe-bench-verified/images.json +502 -0
- nullius/catalogue/benchmarks/swe-bench-verified/standard.json +108 -0
- nullius/catalogue/benchmarks/swe-bench-verified/upstream-settings.json +32 -0
- nullius/catalogue/benchmarks/tau3-bench/benchmark.json +49 -0
- nullius/catalogue/benchmarks/tau3-bench/driver.py +608 -0
- nullius/catalogue/benchmarks/tau3-bench/mcp_server.py +114 -0
- nullius/catalogue/benchmarks/tau3-bench/search_relay.py +19 -0
- nullius/catalogue/benchmarks/tau3-bench/standard.json +547 -0
- nullius/catalogue/benchmarks/tau3-bench/upstream-settings.json +639 -0
- nullius/catalogue/benchmarks/terminal-bench/benchmark.json +69 -0
- nullius/catalogue/benchmarks/terminal-bench/driver.py +267 -0
- nullius/catalogue/benchmarks/terminal-bench/standard.json +166 -0
- nullius/catalogue/benchmarks/terminal-bench/upstream-settings.json +36 -0
- nullius/catalogue/capabilities/keyword-memory/capability.json +33 -0
- nullius/catalogue/capabilities/keyword-memory/capability.py +55 -0
- nullius/catalogue/capabilities/mem0/capability.json +135 -0
- nullius/catalogue/capabilities/mem0/capability.py +173 -0
- nullius/catalogue/catalog.py +426 -0
- nullius/catalogue/citation.py +116 -0
- nullius/catalogue/harbor_entry.py +367 -0
- nullius/catalogue/sources.py +107 -0
- nullius/catalogue/storage.py +125 -0
- nullius/cli.py +85 -0
- nullius/compare/__init__.py +0 -0
- nullius/compare/cli.py +265 -0
- nullius/compare/comparison.py +184 -0
- nullius/execution.py +1653 -0
- nullius/gitrefs.py +128 -0
- nullius/harbor/__init__.py +0 -0
- nullius/harbor/feed.py +228 -0
- nullius/harbor/source.py +582 -0
- nullius/hosts.py +368 -0
- nullius/importers/__init__.py +140 -0
- nullius/importers/atif.py +387 -0
- nullius/importers/cli.py +135 -0
- nullius/importers/otel.py +274 -0
- nullius/judge/__init__.py +14 -0
- nullius/judge/batch.py +122 -0
- nullius/judge/client.py +433 -0
- nullius/judge/floors.json +86 -0
- nullius/judge/lanes.py +89 -0
- nullius/judge/questions.py +309 -0
- nullius/judge/reconcile.py +176 -0
- nullius/judge/state.py +224 -0
- nullius/judge/store.py +167 -0
- nullius/migrate.py +268 -0
- nullius/onboarding.py +116 -0
- nullius/paths.py +89 -0
- nullius/prerequisites.py +129 -0
- nullius/prices.py +283 -0
- nullius/progress.py +294 -0
- nullius/providers.py +335 -0
- nullius/recipes/__init__.py +0 -0
- nullius/recipes/launch.py +78 -0
- nullius/redact.py +72 -0
- nullius/runs/__init__.py +0 -0
- nullius/runs/artifacts.py +67 -0
- nullius/runs/classify.py +216 -0
- nullius/runs/cli.py +316 -0
- nullius/runs/feasibility.py +442 -0
- nullius/runs/launches.py +149 -0
- nullius/runs/live.py +715 -0
- nullius/runs/parse.py +1016 -0
- nullius/runs/verifier.py +241 -0
- nullius/sandbox.py +109 -0
- nullius/secrets.py +218 -0
- nullius/settings.py +544 -0
- nullius/standard/__init__.py +15 -0
- nullius/standard/acp.py +305 -0
- nullius/standard/cancellation.py +19 -0
- nullius/standard/cli.py +703 -0
- nullius/standard/conform.py +149 -0
- nullius/standard/container.py +1870 -0
- nullius/standard/definitions.py +1651 -0
- nullius/standard/egress.py +192 -0
- nullius/standard/fidelity.py +256 -0
- nullius/standard/forward.py +139 -0
- nullius/standard/hostreq.py +105 -0
- nullius/standard/howto.py +220 -0
- nullius/standard/install.py +428 -0
- nullius/standard/job.py +551 -0
- nullius/standard/jsonl.py +129 -0
- nullius/standard/kits/agent-conversation-v1/driver.py +27 -0
- nullius/standard/kits/agent-conversation-v1/standard.json +26 -0
- nullius/standard/kits/agent-search-v1/driver.py +171 -0
- nullius/standard/kits/agent-search-v1/standard.json +99 -0
- nullius/standard/kits/agent-task-v1/driver.py +25 -0
- nullius/standard/kits/agent-task-v1/standard.json +100 -0
- nullius/standard/kits/agent-tools-v1/driver.py +206 -0
- nullius/standard/kits/agent-tools-v1/mcp_kit.py +209 -0
- nullius/standard/kits/agent-tools-v1/standard.json +119 -0
- nullius/standard/kits/agent-workspace-v1/driver.py +65 -0
- nullius/standard/kits/agent-workspace-v1/standard.json +95 -0
- nullius/standard/kits/cap-memory-v1/driver.py +39 -0
- nullius/standard/kits/cap-memory-v1/standard.json +91 -0
- nullius/standard/ledger.py +326 -0
- nullius/standard/match.py +66 -0
- nullius/standard/mcp_bridge.py +62 -0
- nullius/standard/mcp_machine.py +193 -0
- nullius/standard/merge.py +239 -0
- nullius/standard/names.py +37 -0
- nullius/standard/network_requirements.py +44 -0
- nullius/standard/pace.py +53 -0
- nullius/standard/payload.py +278 -0
- nullius/standard/pins.py +130 -0
- nullius/standard/ports.py +70 -0
- nullius/standard/prove.py +373 -0
- nullius/standard/recipe.py +746 -0
- nullius/standard/relay.py +785 -0
- nullius/standard/run.py +1781 -0
- nullius/standard/setup_container.py +208 -0
- nullius/standard/shard.py +71 -0
- nullius/standard/web_services.py +30 -0
- nullius/traces/__init__.py +0 -0
- nullius/traces/behavior.py +131 -0
- nullius/traces/charts.py +898 -0
- nullius/traces/conversation.py +159 -0
- nullius/traces/otel.py +608 -0
- nullius/traces/trace.py +1477 -0
- nullius/traces/trajectory.py +586 -0
- nullius/workspace.py +417 -0
- nullius/workspace_cli.py +119 -0
- nullius_eval-0.1.0.dist-info/METADATA +93 -0
- nullius_eval-0.1.0.dist-info/RECORD +291 -0
- nullius_eval-0.1.0.dist-info/WHEEL +5 -0
- nullius_eval-0.1.0.dist-info/entry_points.txt +2 -0
- nullius_eval-0.1.0.dist-info/licenses/LICENSE +202 -0
- nullius_eval-0.1.0.dist-info/licenses/app/static/fonts/dmsans-OFL.txt +93 -0
- nullius_eval-0.1.0.dist-info/licenses/app/static/fonts/ibmplexmono-OFL.txt +93 -0
- nullius_eval-0.1.0.dist-info/licenses/app/static/fonts/instrumentserif-OFL.txt +93 -0
- nullius_eval-0.1.0.dist-info/top_level.txt +2 -0
nullius/traces/trace.py
ADDED
|
@@ -0,0 +1,1477 @@
|
|
|
1
|
+
"""Load an agent trace (``agent/trace.json``) into rows for a waterfall.
|
|
2
|
+
|
|
3
|
+
A sidecar to the trajectory, not a replacement: where ``trajectory.json`` carries
|
|
4
|
+
one timestamp per step with no duration, a trace carries measured start *and*
|
|
5
|
+
end per LLM call, tool call and subagent, with causal parentage. It is the first
|
|
6
|
+
artefact in this tree that can say where the wall clock actually went.
|
|
7
|
+
|
|
8
|
+
Two rules shape everything here.
|
|
9
|
+
|
|
10
|
+
**One global time axis.** Bars are positioned against the whole trace, never
|
|
11
|
+
against their parent. Log-derived children routinely start *before* their OTel
|
|
12
|
+
parents, because the two come from different clocks; laying out relative to the
|
|
13
|
+
parent would force a clamp, and the clamp would hide exactly the discrepancy the
|
|
14
|
+
format exists to expose. A *zoom* (``Filter.zoom``) is not a per-parent layout:
|
|
15
|
+
it is one explicit window — a subtree's own extent — that the reader asks for,
|
|
16
|
+
and everything outside it is left out of the waterfall rather than re-scaled.
|
|
17
|
+
|
|
18
|
+
**Totals are the producer's job.** ``totals`` is displayed verbatim and never
|
|
19
|
+
recomputed from the tree — see :class:`Totals`. A filtered view is the one case
|
|
20
|
+
that needs its own arithmetic, because hiding a span has to move its time
|
|
21
|
+
somewhere and the producer cannot be asked again; that lives in
|
|
22
|
+
:class:`Breakdown`, is labelled as derived wherever it is shown, and never
|
|
23
|
+
overwrites what the file said.
|
|
24
|
+
|
|
25
|
+
Two normalisations happen on the way in, in that order, and they are the only
|
|
26
|
+
two. First, a call the exporter measured is given the log spans for the reply it
|
|
27
|
+
produced, which the producer writes as a second copy of the same call when it has
|
|
28
|
+
no request id to join them on. See :func:`fold_llm_requests`; it moves rows and
|
|
29
|
+
no numbers. Then a span that is a *namespace* for its children rather than an
|
|
30
|
+
event of its own is re-kinded ``group`` and reads ``Bash [group]``: Harbor's
|
|
31
|
+
Claude Code instrumentation opens a ``claude_code.tool`` span carrying
|
|
32
|
+
``tool_name: "Bash"`` and puts the permission wait and the actual ``Bash``
|
|
33
|
+
execution inside it. Counting the wrapper as work would double-count the call.
|
|
34
|
+
See :func:`is_group` for what qualifies and, more importantly, for the near
|
|
35
|
+
misses that deliberately do not.
|
|
36
|
+
|
|
37
|
+
The order is load-bearing. An ``llm_request`` holding a single ``reasoning`` or
|
|
38
|
+
``output`` block of byte-identical extent is the same
|
|
39
|
+
duplication :func:`fold_llm_requests` resolves, and it resolves it better: the
|
|
40
|
+
wrapper and its one block collapse into a single span carrying both the
|
|
41
|
+
request's tokens and the block's text, where re-kinding leaves two rows and
|
|
42
|
+
charges one of them nothing. Folding first leaves ``is_group`` only the wrappers
|
|
43
|
+
fold could not match to a call, which is the case it is still needed for.
|
|
44
|
+
|
|
45
|
+
Everything is redacted at load, so templates hold display text only. Stdlib
|
|
46
|
+
only, and no Flask: ``python3 -m unittest discover -s app/tests -t app`` needs no
|
|
47
|
+
install at all.
|
|
48
|
+
"""
|
|
49
|
+
|
|
50
|
+
from __future__ import annotations
|
|
51
|
+
|
|
52
|
+
import bisect
|
|
53
|
+
import json
|
|
54
|
+
import math
|
|
55
|
+
from dataclasses import dataclass, field
|
|
56
|
+
|
|
57
|
+
from nullius.redact import redact
|
|
58
|
+
|
|
59
|
+
NS_PER_MS = 1_000_000
|
|
60
|
+
|
|
61
|
+
# A residual under this reads as float noise from the producer's own arithmetic,
|
|
62
|
+
# not as real unattributed time. Rendering it produces a zero-width segment with
|
|
63
|
+
# a legend entry saying "0ms".
|
|
64
|
+
UNACCOUNTED_EPSILON_NS = NS_PER_MS
|
|
65
|
+
|
|
66
|
+
# An exporter can emit thousands of spans for a trivial task. Every row is
|
|
67
|
+
# rendered server-side with its own detail pane, so the page has to be bounded.
|
|
68
|
+
MAX_ROWS = 2000
|
|
69
|
+
|
|
70
|
+
# Nesting past this is a malformed producer, not a deep agent. JSON cannot
|
|
71
|
+
# express a cycle, so `load` can never hit it — but `parse` takes a dict, and
|
|
72
|
+
# either way a runaway tree would exhaust the stack while building the spans,
|
|
73
|
+
# long before any of the guards downstream got a look.
|
|
74
|
+
MAX_DEPTH = 64
|
|
75
|
+
|
|
76
|
+
# Legend order. Not the enum's order — this groups the model's own production
|
|
77
|
+
# (llm/reasoning/output) together, then work, then structure.
|
|
78
|
+
KIND_ORDER = (
|
|
79
|
+
"llm_request", "reasoning", "output", "tool", "subagent",
|
|
80
|
+
"session", "user_message", "compaction", "group",
|
|
81
|
+
)
|
|
82
|
+
|
|
83
|
+
# What a namespace span becomes. A kind of its own rather than a flag, because
|
|
84
|
+
# every consumer already switches on `kind` — the swatch, the legend, the chart
|
|
85
|
+
# split, and `_KIND_CATEGORY` below, which by omitting it charges a group no time.
|
|
86
|
+
GROUP_KIND = "group"
|
|
87
|
+
|
|
88
|
+
# Said in the label, because the label is the only thing most of the page shows.
|
|
89
|
+
# Appended rather than substituted: "Bash [group]" and "Bash" sort together and
|
|
90
|
+
# read as the same call seen at two levels, which is what they are.
|
|
91
|
+
GROUP_SUFFIX = " [group]"
|
|
92
|
+
|
|
93
|
+
# How far a namespace span's children may fall short of covering it and still
|
|
94
|
+
# count as accounting for all of it.
|
|
95
|
+
#
|
|
96
|
+
# They never tile it exactly. Harbor stamps the wrapper to the millisecond and
|
|
97
|
+
# its children to the nanosecond, so each of the two boundaries is up to 1ms out,
|
|
98
|
+
# and children routinely overrun the parent they sit in — the same clock
|
|
99
|
+
# disagreement the global axis exists to show. Allow both boundaries' rounding.
|
|
100
|
+
GROUP_SLACK_NS = 2 * NS_PER_MS
|
|
101
|
+
|
|
102
|
+
# Kinds that already say they bracket their children. They are exempt from the
|
|
103
|
+
# normalisation below, which exists to stop a span *claiming to be work* when it
|
|
104
|
+
# is a container — a kind that never made the claim needs no correcting, and
|
|
105
|
+
# `_KIND_CATEGORY` already charges these nothing.
|
|
106
|
+
_BRACKET_KINDS = ("session", "subagent", GROUP_KIND)
|
|
107
|
+
|
|
108
|
+
# Breakdown segments, in a fixed left-to-right order. The order carries no
|
|
109
|
+
# meaning — these are categories, not a timeline — but a stable one keeps the
|
|
110
|
+
# strip from reshuffling between trials.
|
|
111
|
+
_SEGMENTS = (
|
|
112
|
+
("llm", "LLM", "llm_ns"),
|
|
113
|
+
("tool", "Tool", "tool_ns"),
|
|
114
|
+
("reasoning", "Reasoning", "reasoning_ns"),
|
|
115
|
+
("idle", "Idle", "idle_ns"),
|
|
116
|
+
)
|
|
117
|
+
|
|
118
|
+
# The residual is a segment like any other once it reaches a strip, and both
|
|
119
|
+
# `segments_of` and `Breakdown.compared_to` need to name and order it.
|
|
120
|
+
_UNACCOUNTED = ("unaccounted", "Unaccounted")
|
|
121
|
+
_SEGMENT_LABELS = {key: label for key, label, _ in _SEGMENTS} | {_UNACCOUNTED[0]: _UNACCOUNTED[1]}
|
|
122
|
+
_SEGMENT_ORDER = [key for key, _, _ in _SEGMENTS] + [_UNACCOUNTED[0]]
|
|
123
|
+
|
|
124
|
+
# What a span's own time counts toward when a breakdown has to be recomputed for
|
|
125
|
+
# a filtered view. The structural kinds are absent on purpose: `session`,
|
|
126
|
+
# `subagent` and `group` bracket their children, so charging them would claim the
|
|
127
|
+
# children's work as their own, and `output` is text produced inside a call that
|
|
128
|
+
# is already counted as `llm`.
|
|
129
|
+
_KIND_CATEGORY = {"llm_request": "llm", "reasoning": "reasoning", "tool": "tool"}
|
|
130
|
+
|
|
131
|
+
# Priority for `partition`. A tool that only waits for a human beats real work,
|
|
132
|
+
# and both beat the LLM call they happened inside of.
|
|
133
|
+
_PRIORITY = ("idle", "tool", "reasoning", "llm")
|
|
134
|
+
|
|
135
|
+
# A tool whose whole job is to wait for the human. Harbor opens a span with this
|
|
136
|
+
# name; another producer may set an attribute instead. Either way the time
|
|
137
|
+
# is not the agent working, so it lands in `idle` rather than `tool`.
|
|
138
|
+
_BLOCKED_NAME = "claude_code.tool.blocked_on_user"
|
|
139
|
+
_BLOCKED_ATTR = "blocked_on_user"
|
|
140
|
+
|
|
141
|
+
# The OTel span for one API call, and the log-derived span for one *record* of
|
|
142
|
+
# the reply. Harbor merges the two itself when the exporter reports a request id
|
|
143
|
+
# (recorded in `harbor.merged_from`); when the provider returns none
|
|
144
|
+
# it cannot, and the same call is left drawn twice — once under the interaction,
|
|
145
|
+
# once under the parallel `session` subtree. `fold_llm_requests` finishes the job.
|
|
146
|
+
_OTEL_LLM_NAME = "claude_code.llm_request"
|
|
147
|
+
_LOG_LLM_NAME = "llm_request"
|
|
148
|
+
|
|
149
|
+
# What a call can be shown to have produced. A tool_use block is left untyped by
|
|
150
|
+
# the producer, and says nothing about what the call was for.
|
|
151
|
+
_BLOCK_KINDS = ("reasoning", "output")
|
|
152
|
+
|
|
153
|
+
# Provenance for a span this reader assembled, alongside the producer's own
|
|
154
|
+
# `harbor.merged_from`. The `app.` prefix is the whole point: it marks what was
|
|
155
|
+
# added here from what was measured there.
|
|
156
|
+
_MERGED_FROM = "app.merged_from"
|
|
157
|
+
_MERGED_KEYS = ("harbor.merged_from", _MERGED_FROM)
|
|
158
|
+
|
|
159
|
+
# Content fields, in reading order. `arguments` is a mapping; the rest are text.
|
|
160
|
+
_CONTENT_FIELDS = (
|
|
161
|
+
("input", "Input"),
|
|
162
|
+
("reasoning", "Reasoning"),
|
|
163
|
+
("output", "Output"),
|
|
164
|
+
("arguments", "Arguments"),
|
|
165
|
+
("result", "Result"),
|
|
166
|
+
)
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
def segments_of(source) -> list:
|
|
170
|
+
"""[{key, label, ns, pct}] for a stacked strip, zero-length categories dropped.
|
|
171
|
+
|
|
172
|
+
Shared by :class:`Totals` and :class:`Breakdown` so the reported strip and a
|
|
173
|
+
recomputed one are laid out and labelled identically — the only difference
|
|
174
|
+
between them should be the numbers, never the presentation.
|
|
175
|
+
|
|
176
|
+
Percentages are of the wall clock, so categories that do not close read as
|
|
177
|
+
short of 100% instead of being silently rescaled to fill it; ``unaccounted``
|
|
178
|
+
is what closes them. With no wall clock to divide by they fall back to the
|
|
179
|
+
segments' own sum, which is the only honest denominator left.
|
|
180
|
+
"""
|
|
181
|
+
out = [
|
|
182
|
+
{"key": key, "label": label, "ns": int(getattr(source, attr))}
|
|
183
|
+
for key, label, attr in _SEGMENTS
|
|
184
|
+
if getattr(source, attr)
|
|
185
|
+
]
|
|
186
|
+
if source.unaccounted_ns:
|
|
187
|
+
out.append({"key": _UNACCOUNTED[0], "label": _UNACCOUNTED[1], "ns": source.unaccounted_ns})
|
|
188
|
+
denominator = source.wall_ns or sum(seg["ns"] for seg in out)
|
|
189
|
+
for seg in out:
|
|
190
|
+
seg["pct"] = seg["ns"] / denominator * 100 if denominator else 0.0
|
|
191
|
+
return out
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
@dataclass(frozen=True)
|
|
195
|
+
class Extent:
|
|
196
|
+
"""The window the axis covers, derived from the spans themselves.
|
|
197
|
+
|
|
198
|
+
Never from the host wall clock: spans are stamped inside the container and
|
|
199
|
+
``totals.wall_ns`` on the host, so mixing them puts bars in the wrong place.
|
|
200
|
+
"""
|
|
201
|
+
|
|
202
|
+
start_ns: int = 0
|
|
203
|
+
end_ns: int = 1
|
|
204
|
+
span_ns: int = 1 # floored at 1 — an all-instant trace would divide by zero
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
@dataclass
|
|
208
|
+
class Tick:
|
|
209
|
+
pct: float
|
|
210
|
+
ns: int # offset from the extent start, not an epoch value
|
|
211
|
+
|
|
212
|
+
|
|
213
|
+
@dataclass
|
|
214
|
+
class Totals:
|
|
215
|
+
"""Run-level time, exactly as the producer reported it.
|
|
216
|
+
|
|
217
|
+
**Never recomputed from the tree.** Summing nested spans double-counts
|
|
218
|
+
their shared time. The producer already resolved that (it skips tools nested
|
|
219
|
+
inside tools, and subtracts tool time nested inside LLM spans). The only
|
|
220
|
+
arithmetic this class does is the residual, which is a display concern.
|
|
221
|
+
"""
|
|
222
|
+
|
|
223
|
+
wall_ns: int | None = None
|
|
224
|
+
llm_ns: int | None = None
|
|
225
|
+
tool_ns: int | None = None
|
|
226
|
+
reasoning_ns: int | None = None
|
|
227
|
+
idle_ns: int | None = None
|
|
228
|
+
span_count: int | None = None
|
|
229
|
+
measured_span_count: int | None = None
|
|
230
|
+
|
|
231
|
+
@property
|
|
232
|
+
def unaccounted_ns(self) -> int:
|
|
233
|
+
"""Wall clock the categories don't account for.
|
|
234
|
+
|
|
235
|
+
The categories are not expected to close: the session span brackets more
|
|
236
|
+
than its instrumented children, so a stacked bar that just leaves a gap
|
|
237
|
+
reads as a rendering bug. Name the gap instead. Clamped at both ends —
|
|
238
|
+
under an epsilon it is noise, and a negative would corrupt the geometry
|
|
239
|
+
silently (the same reasoning as `Trial.dur_other`).
|
|
240
|
+
"""
|
|
241
|
+
if not self.wall_ns:
|
|
242
|
+
return 0
|
|
243
|
+
rest = sum(v or 0 for v in (self.llm_ns, self.tool_ns, self.reasoning_ns, self.idle_ns))
|
|
244
|
+
residual = self.wall_ns - rest
|
|
245
|
+
return int(residual) if residual >= UNACCOUNTED_EPSILON_NS else 0
|
|
246
|
+
|
|
247
|
+
@property
|
|
248
|
+
def segments(self) -> list:
|
|
249
|
+
"""[{key, label, ns, pct}] for the breakdown strip."""
|
|
250
|
+
return segments_of(self)
|
|
251
|
+
|
|
252
|
+
|
|
253
|
+
@dataclass
|
|
254
|
+
class Breakdown:
|
|
255
|
+
"""Category time recomputed from a set of spans — for a filtered view only.
|
|
256
|
+
|
|
257
|
+
The producer's ``totals`` stays authoritative and is never replaced by this
|
|
258
|
+
(see :class:`Totals`). It exists because hiding spans has to take their time
|
|
259
|
+
out of the picture, and the producer cannot be asked a second time.
|
|
260
|
+
|
|
261
|
+
It is deliberately *not* the same arithmetic, and it does not reproduce the
|
|
262
|
+
same numbers. Harbor's ``llm_ns`` is the plain sum of its LLM spans, while
|
|
263
|
+
this partitions the timeline so an instant covered by both a tool call and
|
|
264
|
+
the LLM call that asked for it is charged once, to the tool. The two are
|
|
265
|
+
shown as separate strips because they measure different things.
|
|
266
|
+
|
|
267
|
+
``wall_ns`` is carried over from the source unchanged: hiding a span does not
|
|
268
|
+
make the run shorter, it makes more of the run unattributed. That is what
|
|
269
|
+
``unaccounted_ns`` then absorbs, and it is the honest place for it to land.
|
|
270
|
+
"""
|
|
271
|
+
|
|
272
|
+
wall_ns: int = 0
|
|
273
|
+
llm_ns: int = 0
|
|
274
|
+
tool_ns: int = 0
|
|
275
|
+
reasoning_ns: int = 0
|
|
276
|
+
idle_ns: int = 0
|
|
277
|
+
span_count: int = 0
|
|
278
|
+
measured_span_count: int = 0
|
|
279
|
+
tokens: dict = field(default_factory=dict)
|
|
280
|
+
|
|
281
|
+
@property
|
|
282
|
+
def attributed_ns(self) -> int:
|
|
283
|
+
"""Wall clock the categories account for. Disjoint, so a plain sum."""
|
|
284
|
+
return self.llm_ns + self.tool_ns + self.reasoning_ns + self.idle_ns
|
|
285
|
+
|
|
286
|
+
@property
|
|
287
|
+
def unaccounted_ns(self) -> int:
|
|
288
|
+
residual = (self.wall_ns or 0) - self.attributed_ns
|
|
289
|
+
return int(residual) if residual >= UNACCOUNTED_EPSILON_NS else 0
|
|
290
|
+
|
|
291
|
+
@property
|
|
292
|
+
def segments(self) -> list:
|
|
293
|
+
return segments_of(self)
|
|
294
|
+
|
|
295
|
+
def compared_to(self, other: "Breakdown") -> list:
|
|
296
|
+
"""`segments`, each carrying `delta_ns` against *other*.
|
|
297
|
+
|
|
298
|
+
The comparison a filtered view actually needs. Both sides come from this
|
|
299
|
+
same partition, so every delta is the filter's doing and nothing else —
|
|
300
|
+
whereas the difference against the producer's reported strip mixes the
|
|
301
|
+
filter up with two different ways of accounting for the same run, and on
|
|
302
|
+
a log-derived trace those disagree by minutes, not milliseconds.
|
|
303
|
+
|
|
304
|
+
A category the filter emptied keeps its entry at 0ns: dropping it would
|
|
305
|
+
hide the largest thing the filter did.
|
|
306
|
+
"""
|
|
307
|
+
was = {seg["key"]: seg["ns"] for seg in other.segments}
|
|
308
|
+
out = self.segments
|
|
309
|
+
here = {seg["key"] for seg in out}
|
|
310
|
+
out.extend(
|
|
311
|
+
{"key": key, "label": _SEGMENT_LABELS[key], "ns": 0, "pct": 0.0}
|
|
312
|
+
for key in was
|
|
313
|
+
if key not in here
|
|
314
|
+
)
|
|
315
|
+
out.sort(key=lambda seg: _SEGMENT_ORDER.index(seg["key"]))
|
|
316
|
+
for seg in out:
|
|
317
|
+
seg["delta_ns"] = seg["ns"] - was.get(seg["key"], 0)
|
|
318
|
+
return out
|
|
319
|
+
|
|
320
|
+
def as_totals(self) -> dict:
|
|
321
|
+
"""The ``totals`` block to write into a saved filtered trace."""
|
|
322
|
+
return {
|
|
323
|
+
"wall_ns": self.wall_ns,
|
|
324
|
+
"llm_ns": self.llm_ns,
|
|
325
|
+
"tool_ns": self.tool_ns,
|
|
326
|
+
"reasoning_ns": self.reasoning_ns,
|
|
327
|
+
"idle_ns": self.idle_ns,
|
|
328
|
+
"span_count": self.span_count,
|
|
329
|
+
"measured_span_count": self.measured_span_count,
|
|
330
|
+
"tokens": dict(self.tokens),
|
|
331
|
+
}
|
|
332
|
+
|
|
333
|
+
|
|
334
|
+
def clean(values) -> tuple:
|
|
335
|
+
"""Deduplicated, sorted, blank-free — so one view has exactly one URL."""
|
|
336
|
+
return tuple(sorted({str(v) for v in values if str(v).strip()}))
|
|
337
|
+
|
|
338
|
+
|
|
339
|
+
def toggled(values: tuple, value: str) -> tuple:
|
|
340
|
+
value = str(value)
|
|
341
|
+
return tuple(v for v in values if v != value) if value in values else values + (value,)
|
|
342
|
+
|
|
343
|
+
|
|
344
|
+
@dataclass(frozen=True)
|
|
345
|
+
class Filter:
|
|
346
|
+
"""What a view is leaving out: span labels, and individual spans by id.
|
|
347
|
+
|
|
348
|
+
Two axes, because they answer different questions — "never mind Bash" is a
|
|
349
|
+
label, "not *that* call" is one span. Both take the span's subtree with them;
|
|
350
|
+
see :func:`prune`.
|
|
351
|
+
|
|
352
|
+
Immutable and canonical: every mutation returns a new Filter with its values
|
|
353
|
+
sorted and deduplicated, so the same view always produces the same query
|
|
354
|
+
string, the same saved file and the same provenance block.
|
|
355
|
+
|
|
356
|
+
``zoom`` rides along but is not a filter. It names the span whose subtree the
|
|
357
|
+
waterfall's axis is re-based on (``?zoom=<span id>``), and it hides nothing:
|
|
358
|
+
`active`, `hides` and :func:`filtered_document` are blind to it, and the
|
|
359
|
+
breakdown, the coverage strip and the charts stay over the whole filtered
|
|
360
|
+
view. It lives here because every control on the trial page links through
|
|
361
|
+
`query`, and a link that dropped it would silently un-zoom the reader.
|
|
362
|
+
"""
|
|
363
|
+
|
|
364
|
+
names: tuple = ()
|
|
365
|
+
span_ids: tuple = ()
|
|
366
|
+
zoom: str = ""
|
|
367
|
+
|
|
368
|
+
@classmethod
|
|
369
|
+
def of(cls, names=(), span_ids=(), zoom=None) -> "Filter":
|
|
370
|
+
return cls(names=clean(names), span_ids=clean(span_ids), zoom=str(zoom or "").strip())
|
|
371
|
+
|
|
372
|
+
@property
|
|
373
|
+
def active(self) -> bool:
|
|
374
|
+
return bool(self.names or self.span_ids)
|
|
375
|
+
|
|
376
|
+
@property
|
|
377
|
+
def query(self) -> dict:
|
|
378
|
+
"""Arguments for ``url_for``, so any filtered view is a plain link."""
|
|
379
|
+
out = {"hide": list(self.names), "hide_span": list(self.span_ids)}
|
|
380
|
+
if self.zoom:
|
|
381
|
+
out["zoom"] = self.zoom
|
|
382
|
+
return out
|
|
383
|
+
|
|
384
|
+
def hides(self, raw: dict) -> bool:
|
|
385
|
+
"""Is this raw span filtered out?
|
|
386
|
+
|
|
387
|
+
Matched on the *displayed* label rather than the instrumentation name, so
|
|
388
|
+
what the chips offer, what the URL carries and what the waterfall row
|
|
389
|
+
shows are all one string — and, since that label is already redacted, no
|
|
390
|
+
raw job text ends up in a query string.
|
|
391
|
+
"""
|
|
392
|
+
return (
|
|
393
|
+
raw_label(raw) in self.names
|
|
394
|
+
or str(raw.get("span_id") or "") in self.span_ids
|
|
395
|
+
)
|
|
396
|
+
|
|
397
|
+
def toggled_name(self, name: str) -> "Filter":
|
|
398
|
+
return Filter.of(toggled(self.names, name), self.span_ids, self.zoom)
|
|
399
|
+
|
|
400
|
+
def toggled_span(self, span_id: str) -> "Filter":
|
|
401
|
+
return Filter.of(self.names, toggled(self.span_ids, span_id), self.zoom)
|
|
402
|
+
|
|
403
|
+
def cleared(self) -> "Filter":
|
|
404
|
+
"""Nothing hidden. The zoom is a separate view and keeps its own reset."""
|
|
405
|
+
return Filter(zoom=self.zoom)
|
|
406
|
+
|
|
407
|
+
def zoomed_to(self, span_id: str) -> "Filter":
|
|
408
|
+
return Filter.of(self.names, self.span_ids, span_id)
|
|
409
|
+
|
|
410
|
+
def unzoomed(self) -> "Filter":
|
|
411
|
+
return Filter.of(self.names, self.span_ids)
|
|
412
|
+
|
|
413
|
+
|
|
414
|
+
@dataclass
|
|
415
|
+
class Facet:
|
|
416
|
+
"""One filterable label, with how many spans carry it."""
|
|
417
|
+
|
|
418
|
+
name: str
|
|
419
|
+
kind: str = "" # the commonest kind under this label, for the swatch
|
|
420
|
+
count: int = 0
|
|
421
|
+
hidden: bool = False
|
|
422
|
+
|
|
423
|
+
|
|
424
|
+
@dataclass
|
|
425
|
+
class Span:
|
|
426
|
+
span_id: str = ""
|
|
427
|
+
parent_span_id: str = "" # "" on roots — the key is absent, not null
|
|
428
|
+
name: str = "" # the instrumentation name
|
|
429
|
+
label: str = "" # what to display; often the tool name instead
|
|
430
|
+
kind: str = ""
|
|
431
|
+
start_ns: int = 0
|
|
432
|
+
end_ns: int | None = None
|
|
433
|
+
duration_ns: int | None = None # None means no known end — a marker, not a zero
|
|
434
|
+
timing_quality: str = "unknown"
|
|
435
|
+
source: str = ""
|
|
436
|
+
attributes: list = field(default_factory=list) # [(key, value_str)]
|
|
437
|
+
tokens: dict = field(default_factory=dict)
|
|
438
|
+
content: list = field(default_factory=list) # [(label, text)]
|
|
439
|
+
children: list = field(default_factory=list)
|
|
440
|
+
|
|
441
|
+
@property
|
|
442
|
+
def merged(self) -> bool:
|
|
443
|
+
"""Assembled from more than one source (OTLP span + agent log).
|
|
444
|
+
|
|
445
|
+
Either the producer said so, or `fold_llm_requests` did it here — the
|
|
446
|
+
badge means the same thing to a reader, so both keys light it.
|
|
447
|
+
"""
|
|
448
|
+
return any(k in _MERGED_KEYS for k, _ in self.attributes)
|
|
449
|
+
|
|
450
|
+
|
|
451
|
+
@dataclass
|
|
452
|
+
class Row:
|
|
453
|
+
"""One rendered waterfall row: a span placed on the global axis."""
|
|
454
|
+
|
|
455
|
+
span: Span
|
|
456
|
+
depth: int = 0
|
|
457
|
+
has_children: bool = False
|
|
458
|
+
offset_ns: int = 0 # exact int; only the percentages become floats
|
|
459
|
+
left_pct: float = 0.0
|
|
460
|
+
width_pct: float = 0.0
|
|
461
|
+
is_instant: bool = False
|
|
462
|
+
|
|
463
|
+
|
|
464
|
+
@dataclass
|
|
465
|
+
class Trace:
|
|
466
|
+
run_id: str = ""
|
|
467
|
+
roots: list = field(default_factory=list)
|
|
468
|
+
totals: Totals = field(default_factory=Totals)
|
|
469
|
+
extent: Extent = field(default_factory=Extent)
|
|
470
|
+
axis: Extent = field(default_factory=Extent) # what the bars are placed on: `extent`, or the zoomed subtree's
|
|
471
|
+
rows: list = field(default_factory=list)
|
|
472
|
+
ticks: list = field(default_factory=list)
|
|
473
|
+
truncated: int = 0 # spans beyond MAX_ROWS, not rendered
|
|
474
|
+
shown: int = 0 # spans in the filtered view, whatever the zoom leaves in the waterfall
|
|
475
|
+
zoomed: "Span | None" = None # the span the waterfall is re-based on
|
|
476
|
+
zoom_lost: str = "" # a `zoom` that names no span in this view — shown whole, with a note
|
|
477
|
+
error: str = "" # set if the file could not be read
|
|
478
|
+
filter: Filter = field(default_factory=Filter)
|
|
479
|
+
facets: list = field(default_factory=list) # [Facet], from the unfiltered tree
|
|
480
|
+
hidden_spans: list = field(default_factory=list) # [(span_id, label)] hidden by id
|
|
481
|
+
hidden_count: int = 0 # spans the filter removed, subtrees included
|
|
482
|
+
view: Breakdown = field(default_factory=Breakdown) # totals over what is left
|
|
483
|
+
baseline: Breakdown = field(default_factory=Breakdown) # ... and over all of them
|
|
484
|
+
|
|
485
|
+
@property
|
|
486
|
+
def has_spans(self) -> bool:
|
|
487
|
+
return bool(self.rows)
|
|
488
|
+
|
|
489
|
+
@property
|
|
490
|
+
def visible(self) -> bool:
|
|
491
|
+
"""Should the trace panel render at all.
|
|
492
|
+
|
|
493
|
+
Not just `has_spans`: a filter can legitimately hide every span, and a
|
|
494
|
+
panel that vanished would take its own Clear control with it.
|
|
495
|
+
"""
|
|
496
|
+
return self.has_spans or self.filter.active
|
|
497
|
+
|
|
498
|
+
@property
|
|
499
|
+
def zero_measured(self) -> bool:
|
|
500
|
+
"""Nothing was measured: every duration below is inferred.
|
|
501
|
+
|
|
502
|
+
The signal that instrumentation captured nothing and the producer fell
|
|
503
|
+
back to parsing the agent's own logs. Inferred timings are approximate
|
|
504
|
+
and simply wrong under parallel tool calls, so the UI has to say so.
|
|
505
|
+
"""
|
|
506
|
+
return bool(self.totals.span_count) and self.totals.measured_span_count == 0
|
|
507
|
+
|
|
508
|
+
@property
|
|
509
|
+
def instrumented_ns(self) -> int:
|
|
510
|
+
"""How much wall clock the spans actually cover.
|
|
511
|
+
|
|
512
|
+
Off `extent`, never `axis`: a zoom re-bases the waterfall, and the
|
|
513
|
+
coverage strip describes the capture, not the view.
|
|
514
|
+
"""
|
|
515
|
+
return self.extent.span_ns if self.has_spans else 0
|
|
516
|
+
|
|
517
|
+
@property
|
|
518
|
+
def zoom_offset_ns(self) -> int:
|
|
519
|
+
"""Where the zoomed window starts, as an offset into the capture."""
|
|
520
|
+
return self.axis.start_ns - self.extent.start_ns if self.zoomed else 0
|
|
521
|
+
|
|
522
|
+
@property
|
|
523
|
+
def coverage_pct(self) -> float:
|
|
524
|
+
"""Share of the run the waterfall can see, 0 when unknowable.
|
|
525
|
+
|
|
526
|
+
The axis is derived from the spans, so a run where 1% was instrumented
|
|
527
|
+
renders bars across the full width and looks completely captured. This
|
|
528
|
+
is the number that says otherwise. It compares *durations* only — it
|
|
529
|
+
never places a container-stamped instant on the host's clock.
|
|
530
|
+
"""
|
|
531
|
+
wall = self.totals.wall_ns
|
|
532
|
+
if not wall or not self.has_spans:
|
|
533
|
+
return 0.0
|
|
534
|
+
return min(100.0, self.instrumented_ns / wall * 100)
|
|
535
|
+
|
|
536
|
+
@property
|
|
537
|
+
def kinds_present(self) -> list:
|
|
538
|
+
seen = {r.span.kind for r in self.rows}
|
|
539
|
+
known = [k for k in KIND_ORDER if k in seen]
|
|
540
|
+
return known + sorted(seen - set(KIND_ORDER))
|
|
541
|
+
|
|
542
|
+
@property
|
|
543
|
+
def qualities_present(self) -> list:
|
|
544
|
+
seen = {r.span.timing_quality for r in self.rows}
|
|
545
|
+
return [q for q in ("measured", "inferred", "unknown") if q in seen]
|
|
546
|
+
|
|
547
|
+
|
|
548
|
+
def block_types_of(raw: dict) -> tuple:
|
|
549
|
+
"""What kinds of block a request can be shown to have produced.
|
|
550
|
+
|
|
551
|
+
Two producers say it two ways and both are read: Harbor emits a child span
|
|
552
|
+
per block (`reasoning`, `output`), while another may keep the
|
|
553
|
+
text on the call itself. Empty when nothing says — a call whose only block
|
|
554
|
+
was a `tool_use` is not "an output call", it is just a call.
|
|
555
|
+
"""
|
|
556
|
+
content = raw.get("content") or {}
|
|
557
|
+
seen = {kind for kind in _BLOCK_KINDS if content.get(kind)}
|
|
558
|
+
for child in raw.get("children") or []:
|
|
559
|
+
if isinstance(child, dict) and str(child.get("kind") or "") in _BLOCK_KINDS:
|
|
560
|
+
seen.add(str(child.get("kind")))
|
|
561
|
+
return tuple(kind for kind in _BLOCK_KINDS if kind in seen)
|
|
562
|
+
|
|
563
|
+
|
|
564
|
+
def label_of(name: str, attributes: dict, kind: str = "", blocks: tuple = ()) -> str:
|
|
565
|
+
"""What to show for a span.
|
|
566
|
+
|
|
567
|
+
Merged spans overwrite `name` with the log-derived tool name ("Write");
|
|
568
|
+
unmerged ones keep the instrumentation name ("claude_code.tool") and put the
|
|
569
|
+
tool name only in an attribute. Prefer the attribute, so both render as the
|
|
570
|
+
tool. The raw name stays on the span for the detail pane.
|
|
571
|
+
|
|
572
|
+
An LLM call reads the same way. `claude_code.llm_request` is the exporter's
|
|
573
|
+
name for the same thing the agent log calls `llm_request`, so it is shown
|
|
574
|
+
under the log's name; and when the call produced exactly one *kind* of block
|
|
575
|
+
it is shown under that instead — `reasoning`, or `output`. Two kinds is not
|
|
576
|
+
one type, so a call that both thought and answered stays `llm_request`.
|
|
577
|
+
|
|
578
|
+
Both of those rules make a bracketing span and the call inside it share a
|
|
579
|
+
label, which is why `mark_groups` re-kinds the outer one before this ever
|
|
580
|
+
sees it: given `group`, the label says so. The suffix is added here rather
|
|
581
|
+
than written onto the span so that one function decides what a span is
|
|
582
|
+
called, and the raw name and `tool_name` reach the detail pane untouched.
|
|
583
|
+
"""
|
|
584
|
+
tool = (attributes or {}).get("tool_name")
|
|
585
|
+
if isinstance(tool, str) and tool.strip():
|
|
586
|
+
label = tool.strip()
|
|
587
|
+
elif name in (_OTEL_LLM_NAME, _LOG_LLM_NAME):
|
|
588
|
+
label = blocks[0] if len(blocks) == 1 else _LOG_LLM_NAME
|
|
589
|
+
else:
|
|
590
|
+
label = name
|
|
591
|
+
return label + GROUP_SUFFIX if kind == GROUP_KIND else label
|
|
592
|
+
|
|
593
|
+
|
|
594
|
+
def _int_or_none(value) -> int | None:
|
|
595
|
+
return value if isinstance(value, int) and not isinstance(value, bool) else None
|
|
596
|
+
|
|
597
|
+
|
|
598
|
+
def _content_of(raw: dict) -> list:
|
|
599
|
+
out = []
|
|
600
|
+
for key, label in _CONTENT_FIELDS:
|
|
601
|
+
value = raw.get(key)
|
|
602
|
+
if value is None or value == "" or value == {} or value == []:
|
|
603
|
+
continue
|
|
604
|
+
if isinstance(value, (dict, list)):
|
|
605
|
+
value = json.dumps(value, ensure_ascii=False, indent=2)
|
|
606
|
+
out.append((label, redact(str(value))))
|
|
607
|
+
return out
|
|
608
|
+
|
|
609
|
+
|
|
610
|
+
def _span(raw: dict, depth: int = 0) -> Span:
|
|
611
|
+
# `.get(k) or {}` rather than `.get(k, {})` throughout: the producer writes
|
|
612
|
+
# with exclude_none, so optional fields are absent — but a null would slip
|
|
613
|
+
# straight past a default argument and reach the template as None.
|
|
614
|
+
attributes = raw.get("attributes") or {}
|
|
615
|
+
end_ns = _int_or_none(raw.get("end_ns"))
|
|
616
|
+
start_ns = _int_or_none(raw.get("start_ns")) or 0
|
|
617
|
+
duration_ns = _int_or_none(raw.get("duration_ns"))
|
|
618
|
+
if duration_ns is None and end_ns is not None:
|
|
619
|
+
duration_ns = end_ns - start_ns
|
|
620
|
+
|
|
621
|
+
name = redact(str(raw.get("name") or ""))
|
|
622
|
+
kind = str(raw.get("kind") or "")
|
|
623
|
+
return Span(
|
|
624
|
+
span_id=str(raw.get("span_id") or ""),
|
|
625
|
+
parent_span_id=str(raw.get("parent_span_id") or ""),
|
|
626
|
+
name=name,
|
|
627
|
+
label=redact(
|
|
628
|
+
label_of(str(raw.get("name") or ""), attributes, kind, block_types_of(raw))
|
|
629
|
+
),
|
|
630
|
+
kind=kind,
|
|
631
|
+
start_ns=start_ns,
|
|
632
|
+
end_ns=end_ns,
|
|
633
|
+
duration_ns=duration_ns,
|
|
634
|
+
timing_quality=str(raw.get("timing_quality") or "unknown"),
|
|
635
|
+
source=str(raw.get("source") or ""),
|
|
636
|
+
# Keys are instrumentation enums (gen_ai.request.model), not job text, so
|
|
637
|
+
# they are not redacted; every value is.
|
|
638
|
+
attributes=sorted((str(k), redact(str(v))) for k, v in attributes.items()),
|
|
639
|
+
tokens={k: v for k, v in (raw.get("tokens") or {}).items() if v is not None},
|
|
640
|
+
content=_content_of(raw.get("content") or {}),
|
|
641
|
+
children=(
|
|
642
|
+
[_span(c, depth + 1) for c in raw.get("children") or []]
|
|
643
|
+
if depth < MAX_DEPTH
|
|
644
|
+
else []
|
|
645
|
+
),
|
|
646
|
+
)
|
|
647
|
+
|
|
648
|
+
|
|
649
|
+
def all_spans(roots: list):
|
|
650
|
+
"""Depth-first walk. Guards against a parent cycle rather than hanging."""
|
|
651
|
+
seen = set()
|
|
652
|
+
|
|
653
|
+
def walk(span):
|
|
654
|
+
if span.span_id and span.span_id in seen:
|
|
655
|
+
return
|
|
656
|
+
seen.add(span.span_id)
|
|
657
|
+
yield span
|
|
658
|
+
for child in span.children:
|
|
659
|
+
yield from walk(child)
|
|
660
|
+
|
|
661
|
+
for root in roots:
|
|
662
|
+
yield from walk(root)
|
|
663
|
+
|
|
664
|
+
|
|
665
|
+
def extent_of(roots: list) -> Extent:
|
|
666
|
+
spans = list(all_spans(roots))
|
|
667
|
+
if not spans:
|
|
668
|
+
return Extent()
|
|
669
|
+
start = min(s.start_ns for s in spans)
|
|
670
|
+
end = max((s.end_ns if s.end_ns is not None else s.start_ns) for s in spans)
|
|
671
|
+
# Floored at 1: a trace whose spans are all instants has end == start, and
|
|
672
|
+
# every percentage would come out NaN or Infinity.
|
|
673
|
+
return Extent(start_ns=start, end_ns=end, span_ns=max(end - start, 1))
|
|
674
|
+
|
|
675
|
+
|
|
676
|
+
def find_span(roots: list, span_id: str):
|
|
677
|
+
"""The span called *span_id* in this tree, or None. Same walk as `all_spans`."""
|
|
678
|
+
if not span_id:
|
|
679
|
+
return None
|
|
680
|
+
return next((s for s in all_spans(roots) if s.span_id == span_id), None)
|
|
681
|
+
|
|
682
|
+
|
|
683
|
+
def raw_spans_of(spans: list, depth: int = 0):
|
|
684
|
+
"""Depth-first walk of raw span dicts, straight from the document.
|
|
685
|
+
|
|
686
|
+
The filter and everything that saves a file work on raw dicts rather than on
|
|
687
|
+
parsed :class:`Span`s: a saved trace has to keep every field the producer
|
|
688
|
+
wrote — including the content this reader redacts — and a round trip through
|
|
689
|
+
the parser would quietly drop whatever it does not render.
|
|
690
|
+
"""
|
|
691
|
+
for raw in spans:
|
|
692
|
+
if not isinstance(raw, dict):
|
|
693
|
+
continue
|
|
694
|
+
yield raw
|
|
695
|
+
if depth < MAX_DEPTH:
|
|
696
|
+
yield from raw_spans_of(raw.get("children") or [], depth + 1)
|
|
697
|
+
|
|
698
|
+
|
|
699
|
+
def raw_label(raw: dict) -> str:
|
|
700
|
+
"""The label a raw span will be displayed under. Redacted, like the parsed one.
|
|
701
|
+
|
|
702
|
+
Reads `kind` off the span, so it agrees with :func:`_span` only once
|
|
703
|
+
:func:`mark_groups` has run. Everything that filters or counts by label goes
|
|
704
|
+
through the normalised document for that reason.
|
|
705
|
+
"""
|
|
706
|
+
return redact(label_of(
|
|
707
|
+
str(raw.get("name") or ""), raw.get("attributes") or {},
|
|
708
|
+
str(raw.get("kind") or ""), block_types_of(raw),
|
|
709
|
+
))
|
|
710
|
+
|
|
711
|
+
|
|
712
|
+
def _bare_label(raw: dict) -> str:
|
|
713
|
+
"""A raw span's label as if it were not a group. Its identity, not its role."""
|
|
714
|
+
return label_of(
|
|
715
|
+
str(raw.get("name") or ""), raw.get("attributes") or {}, blocks=block_types_of(raw)
|
|
716
|
+
)
|
|
717
|
+
|
|
718
|
+
|
|
719
|
+
def _self_ns(raw: dict) -> int | None:
|
|
720
|
+
"""Time inside *raw* that none of its children covers, or None if unknowable.
|
|
721
|
+
|
|
722
|
+
Overlapping children are merged and clipped to the parent first: a tool call
|
|
723
|
+
nested in the LLM call that asked for it would otherwise be counted twice and
|
|
724
|
+
make a span with real self-time look fully covered.
|
|
725
|
+
"""
|
|
726
|
+
start = _int_or_none(raw.get("start_ns"))
|
|
727
|
+
end = _int_or_none(raw.get("end_ns"))
|
|
728
|
+
if start is None or end is None or end <= start:
|
|
729
|
+
return None
|
|
730
|
+
inside = []
|
|
731
|
+
for child in raw.get("children") or []:
|
|
732
|
+
if not isinstance(child, dict):
|
|
733
|
+
continue
|
|
734
|
+
low = _int_or_none(child.get("start_ns"))
|
|
735
|
+
high = _int_or_none(child.get("end_ns"))
|
|
736
|
+
if low is None or high is None:
|
|
737
|
+
continue
|
|
738
|
+
low, high = max(low, start), min(high, end)
|
|
739
|
+
if high > low:
|
|
740
|
+
inside.append((low, high))
|
|
741
|
+
return (end - start) - sum(high - low for low, high in merge_intervals(inside))
|
|
742
|
+
|
|
743
|
+
|
|
744
|
+
def _same_extent(raw: dict, child: dict) -> bool:
|
|
745
|
+
"""Do these two spans start and end together, to within `GROUP_SLACK_NS`?
|
|
746
|
+
|
|
747
|
+
Both ends, and that is the point. Coverage alone is satisfied by a child that
|
|
748
|
+
overruns its parent — a background subagent hung under the launch that
|
|
749
|
+
returned in 47ms runs for minutes. Clipped
|
|
750
|
+
to the parent it covers all of it, but the launch is a real 47ms event.
|
|
751
|
+
"""
|
|
752
|
+
for key in ("start_ns", "end_ns"):
|
|
753
|
+
mine, theirs = _int_or_none(raw.get(key)), _int_or_none(child.get(key))
|
|
754
|
+
if mine is None or theirs is None or abs(mine - theirs) > GROUP_SLACK_NS:
|
|
755
|
+
return False
|
|
756
|
+
return True
|
|
757
|
+
|
|
758
|
+
|
|
759
|
+
def is_group(raw: dict) -> bool:
|
|
760
|
+
"""Is this span a namespace for its children rather than an event itself?
|
|
761
|
+
|
|
762
|
+
**Its children have to account for all of it**, to within `GROUP_SLACK_NS`.
|
|
763
|
+
A span that also spent time of its own is doing something, whatever it is
|
|
764
|
+
named. That is necessary but nowhere near sufficient, so one of two further
|
|
765
|
+
signals has to say the span adds no distinction to what it contains:
|
|
766
|
+
|
|
767
|
+
* **it shares its label with a child** — Harbor's `claude_code.tool` carries
|
|
768
|
+
`tool_name: "Bash"` and holds the span that actually ran Bash, so one call
|
|
769
|
+
would otherwise be counted twice under one name; or
|
|
770
|
+
* **it has a single child of the same extent** — the same bar drawn twice.
|
|
771
|
+
An `llm_request` may hold one `reasoning` or `output` block whose start
|
|
772
|
+
and end are *byte-identical* to its own,
|
|
773
|
+
because the producer splits a response into blocks and a one-block response
|
|
774
|
+
is the request again. `fold_llm_requests` runs first and collapses that
|
|
775
|
+
pair outright wherever it can match the request to the call it answered,
|
|
776
|
+
which is the better answer — one span keeping both clocks and both sets of
|
|
777
|
+
text. What reaches here is the remainder it could not match.
|
|
778
|
+
|
|
779
|
+
Everything else with children stays what it is, and the near misses are worth
|
|
780
|
+
knowing because each one looks like this from a distance. OpenCode's
|
|
781
|
+
`ai.streamText` also brackets the stream call it is named for, but can spend
|
|
782
|
+
time on its own transport; it is still a call. `claude_code.interaction`
|
|
783
|
+
is covered by the calls inside it, and `session`/`subagent` are exempt
|
|
784
|
+
outright: a kind that already announces itself as a bracket is not claiming
|
|
785
|
+
to be work, and `_KIND_CATEGORY` already charges it nothing. A group is
|
|
786
|
+
specifically a span pretending to be the event nested inside it.
|
|
787
|
+
|
|
788
|
+
A call `fold_llm_requests` gave children to is exempt for a sharper reason:
|
|
789
|
+
it would match, always, and the match would be this reader's own doing. The
|
|
790
|
+
fold moves the reply's blocks under the call and then labels the call after
|
|
791
|
+
what it produced, so the parent shares a label with a child by construction
|
|
792
|
+
and the blocks span the call because they are the reply to it. Nothing was
|
|
793
|
+
pretending to be anything — and the call is the one span in that subtree with
|
|
794
|
+
a measured clock, so re-kinding it would charge the only real measurement to
|
|
795
|
+
nothing and leave the inferred blocks holding the time.
|
|
796
|
+
"""
|
|
797
|
+
if str(raw.get("kind") or "") in _BRACKET_KINDS:
|
|
798
|
+
return False
|
|
799
|
+
if _MERGED_FROM in (raw.get("attributes") or {}):
|
|
800
|
+
return False
|
|
801
|
+
children = [c for c in raw.get("children") or [] if isinstance(c, dict)]
|
|
802
|
+
if not children:
|
|
803
|
+
return False
|
|
804
|
+
self_ns = _self_ns(raw)
|
|
805
|
+
if self_ns is None or self_ns > GROUP_SLACK_NS:
|
|
806
|
+
return False
|
|
807
|
+
if len(children) == 1 and _same_extent(raw, children[0]):
|
|
808
|
+
return True
|
|
809
|
+
# Compared without the suffix on either side. `mark_groups` works children
|
|
810
|
+
# first, so an inner span may already be a group by the time the outer one is
|
|
811
|
+
# asked; matching on the displayed label would then miss a doubly-wrapped
|
|
812
|
+
# call and leave the outer one claiming to be the tool.
|
|
813
|
+
label = _bare_label(raw)
|
|
814
|
+
return any(_bare_label(c) == label for c in children)
|
|
815
|
+
|
|
816
|
+
|
|
817
|
+
def mark_groups(spans: list, depth: int = 0) -> list:
|
|
818
|
+
"""*spans* with every namespace span re-kinded `group`, children first.
|
|
819
|
+
|
|
820
|
+
Runs once, before anything filters or counts, so that the label a chip
|
|
821
|
+
offers, the label in the query string and the label on the row are the same
|
|
822
|
+
string — decided per span, never per surviving child. Filtering the `Bash`
|
|
823
|
+
inside a group therefore leaves the group a group, still named for what it
|
|
824
|
+
used to contain, which is the only answer that keeps a filter from renaming
|
|
825
|
+
the rows it was not asked about.
|
|
826
|
+
|
|
827
|
+
Copy-on-write like :func:`prune`: a subtree with no groups in it is passed
|
|
828
|
+
through by reference, so the caller's document is never mutated.
|
|
829
|
+
"""
|
|
830
|
+
out: list = []
|
|
831
|
+
changed = False
|
|
832
|
+
for raw in spans:
|
|
833
|
+
if not isinstance(raw, dict):
|
|
834
|
+
changed = True
|
|
835
|
+
continue
|
|
836
|
+
children = raw.get("children") or []
|
|
837
|
+
if children and depth < MAX_DEPTH:
|
|
838
|
+
marked = mark_groups(children, depth + 1)
|
|
839
|
+
if marked is not children:
|
|
840
|
+
raw, changed = dict(raw, children=marked), True
|
|
841
|
+
if is_group(raw):
|
|
842
|
+
raw, changed = dict(raw, kind=GROUP_KIND), True
|
|
843
|
+
out.append(raw)
|
|
844
|
+
return out if changed else spans
|
|
845
|
+
|
|
846
|
+
|
|
847
|
+
def category_of(raw: dict) -> str | None:
|
|
848
|
+
"""Which breakdown category a span's own time belongs to, or None.
|
|
849
|
+
|
|
850
|
+
None means the span contributes no time of its own — see `_KIND_CATEGORY`.
|
|
851
|
+
"""
|
|
852
|
+
kind = str(raw.get("kind") or "")
|
|
853
|
+
if kind == "tool" and (
|
|
854
|
+
str(raw.get("name") or "") == _BLOCKED_NAME
|
|
855
|
+
or (raw.get("attributes") or {}).get(_BLOCKED_ATTR)
|
|
856
|
+
):
|
|
857
|
+
return "idle"
|
|
858
|
+
return _KIND_CATEGORY.get(kind)
|
|
859
|
+
|
|
860
|
+
|
|
861
|
+
def raw_extent(spans: list) -> Extent:
|
|
862
|
+
"""The axis window, taken from the raw document.
|
|
863
|
+
|
|
864
|
+
Called with the *unfiltered* spans on purpose: hiding one must not slide the
|
|
865
|
+
remaining bars sideways, or a filter would look like it changed timings it
|
|
866
|
+
was only asked to leave out. What it removes shows up as empty axis instead.
|
|
867
|
+
Matches `extent_of` span for span, including its treatment of a span with no
|
|
868
|
+
usable start (0, like `_span`) or no end (its own start).
|
|
869
|
+
"""
|
|
870
|
+
starts, ends = [], []
|
|
871
|
+
for raw in raw_spans_of(spans):
|
|
872
|
+
start = _int_or_none(raw.get("start_ns")) or 0
|
|
873
|
+
end = _int_or_none(raw.get("end_ns"))
|
|
874
|
+
starts.append(start)
|
|
875
|
+
ends.append(start if end is None else end)
|
|
876
|
+
if not starts:
|
|
877
|
+
return Extent()
|
|
878
|
+
low, high = min(starts), max(ends)
|
|
879
|
+
return Extent(start_ns=low, end_ns=high, span_ns=max(high - low, 1))
|
|
880
|
+
|
|
881
|
+
|
|
882
|
+
def inventory(spans: list, filt: "Filter | None" = None) -> list:
|
|
883
|
+
"""Every distinct span label in the document, with how many spans carry it.
|
|
884
|
+
|
|
885
|
+
Built from the *unfiltered* tree: a hidden label still needs its chip, or
|
|
886
|
+
there would be no way left to bring it back.
|
|
887
|
+
"""
|
|
888
|
+
filt = filt or Filter()
|
|
889
|
+
counts: dict = {}
|
|
890
|
+
kinds: dict = {}
|
|
891
|
+
for raw in raw_spans_of(spans):
|
|
892
|
+
name = raw_label(raw)
|
|
893
|
+
counts[name] = counts.get(name, 0) + 1
|
|
894
|
+
seen = kinds.setdefault(name, {})
|
|
895
|
+
kind = str(raw.get("kind") or "")
|
|
896
|
+
seen[kind] = seen.get(kind, 0) + 1
|
|
897
|
+
out = [
|
|
898
|
+
Facet(
|
|
899
|
+
name=name,
|
|
900
|
+
# One label can span kinds (a merged parent and its child both read
|
|
901
|
+
# "Write"); the commonest wins, since it only picks the swatch.
|
|
902
|
+
kind=max(kinds[name].items(), key=lambda kv: (kv[1], kv[0]))[0],
|
|
903
|
+
count=count,
|
|
904
|
+
hidden=name in filt.names,
|
|
905
|
+
)
|
|
906
|
+
for name, count in counts.items()
|
|
907
|
+
]
|
|
908
|
+
# Commonest first, then alphabetical — a stable order, and the labels worth
|
|
909
|
+
# filtering are the ones there are a lot of.
|
|
910
|
+
out.sort(key=lambda f: (-f.count, f.name))
|
|
911
|
+
return out
|
|
912
|
+
|
|
913
|
+
|
|
914
|
+
def labels_by_id(spans: list) -> dict:
|
|
915
|
+
"""span_id → label, over the whole unfiltered document.
|
|
916
|
+
|
|
917
|
+
So a span hidden by id can still be named in the UI that offers to unhide it.
|
|
918
|
+
"""
|
|
919
|
+
return {
|
|
920
|
+
str(raw.get("span_id") or ""): raw_label(raw)
|
|
921
|
+
for raw in raw_spans_of(spans)
|
|
922
|
+
if raw.get("span_id")
|
|
923
|
+
}
|
|
924
|
+
|
|
925
|
+
|
|
926
|
+
def _window(raw: dict) -> tuple:
|
|
927
|
+
"""(start, end) in ns, an unknown end read as the start — same as `_span`."""
|
|
928
|
+
start = _int_or_none(raw.get("start_ns")) or 0
|
|
929
|
+
end = _int_or_none(raw.get("end_ns"))
|
|
930
|
+
return start, start if end is None else end
|
|
931
|
+
|
|
932
|
+
|
|
933
|
+
def _tokens_key(raw: dict) -> tuple:
|
|
934
|
+
"""A call's usage, as something comparable. Empty when none was reported."""
|
|
935
|
+
return tuple(
|
|
936
|
+
sorted(
|
|
937
|
+
(str(k), v)
|
|
938
|
+
for k, v in (raw.get("tokens") or {}).items()
|
|
939
|
+
if _int_or_none(v) is not None
|
|
940
|
+
)
|
|
941
|
+
)
|
|
942
|
+
|
|
943
|
+
|
|
944
|
+
def _request_groups(wrappers: list) -> list:
|
|
945
|
+
"""Log request spans grouped by the reply they came from.
|
|
946
|
+
|
|
947
|
+
One API call arrives as several records — a thinking block, each tool_use,
|
|
948
|
+
the final text — and the producer opens a span per record. They carry one
|
|
949
|
+
`message.id` between them, which is exactly the grouping wanted; a producer
|
|
950
|
+
that omits it leaves every record its own group, which folds them one by one
|
|
951
|
+
and is no worse than not folding at all.
|
|
952
|
+
"""
|
|
953
|
+
groups: dict = {}
|
|
954
|
+
order: list = []
|
|
955
|
+
for raw in wrappers:
|
|
956
|
+
key = (raw.get("attributes") or {}).get("message.id")
|
|
957
|
+
key = str(key) if key else "ungrouped:" + str(raw.get("span_id") or id(raw))
|
|
958
|
+
if key not in groups:
|
|
959
|
+
groups[key] = []
|
|
960
|
+
order.append(key)
|
|
961
|
+
groups[key].append(raw)
|
|
962
|
+
return [groups[key] for key in order]
|
|
963
|
+
|
|
964
|
+
|
|
965
|
+
def _match_requests(containers: list, groups: list) -> dict:
|
|
966
|
+
"""container span_id → the log request spans belonging to it.
|
|
967
|
+
|
|
968
|
+
Harbor joins these on the request id the exporter reported. This runs where
|
|
969
|
+
the provider returned none, so the join is on what is left: identical usage,
|
|
970
|
+
and overlapping windows. Usage is a hard constraint when both sides report
|
|
971
|
+
it and the overlap only ranks the candidates, which is what keeps two calls
|
|
972
|
+
that happen to overlap from swapping their blocks.
|
|
973
|
+
|
|
974
|
+
A wrong match moves a row under the wrong call; it cannot change a number,
|
|
975
|
+
because folding re-parents spans and never touches a clock.
|
|
976
|
+
"""
|
|
977
|
+
taken: set = set()
|
|
978
|
+
out: dict = {}
|
|
979
|
+
for container in sorted(containers, key=lambda raw: _window(raw)[0]):
|
|
980
|
+
c_start, c_end = _window(container)
|
|
981
|
+
c_tokens = _tokens_key(container)
|
|
982
|
+
best = None
|
|
983
|
+
for index, group in enumerate(groups):
|
|
984
|
+
if index in taken:
|
|
985
|
+
continue
|
|
986
|
+
g_start = min(_window(raw)[0] for raw in group)
|
|
987
|
+
g_end = max(_window(raw)[1] for raw in group)
|
|
988
|
+
if g_start >= c_end or c_start >= g_end:
|
|
989
|
+
continue
|
|
990
|
+
g_tokens = next((t for t in map(_tokens_key, group) if t), ())
|
|
991
|
+
if c_tokens and g_tokens and c_tokens != g_tokens:
|
|
992
|
+
continue
|
|
993
|
+
distance = abs(g_start - c_start)
|
|
994
|
+
if best is None or distance < best[0]:
|
|
995
|
+
best = (distance, index, group)
|
|
996
|
+
if best is not None:
|
|
997
|
+
taken.add(best[1])
|
|
998
|
+
out[str(container.get("span_id") or "")] = best[2]
|
|
999
|
+
return out
|
|
1000
|
+
|
|
1001
|
+
|
|
1002
|
+
def _collect_requests(
|
|
1003
|
+
spans: list, parent: str, containers: list, wrappers: list, depth: int = 0
|
|
1004
|
+
) -> None:
|
|
1005
|
+
"""The calls to fold into, and the log request spans still to fold.
|
|
1006
|
+
|
|
1007
|
+
A request already sitting under a call has been folded — by this function on
|
|
1008
|
+
an earlier read, or by Harbor itself — and must not be folded again: a saved
|
|
1009
|
+
view can be filtered again, which re-reads a document this has already seen,
|
|
1010
|
+
and a second pass would rewrite the provenance of the first.
|
|
1011
|
+
"""
|
|
1012
|
+
for raw in spans:
|
|
1013
|
+
if not isinstance(raw, dict):
|
|
1014
|
+
continue
|
|
1015
|
+
name = str(raw.get("name") or "")
|
|
1016
|
+
if name == _OTEL_LLM_NAME:
|
|
1017
|
+
containers.append(raw)
|
|
1018
|
+
elif (
|
|
1019
|
+
name == _LOG_LLM_NAME
|
|
1020
|
+
and str(raw.get("source") or "") == "log"
|
|
1021
|
+
and parent != _OTEL_LLM_NAME
|
|
1022
|
+
):
|
|
1023
|
+
wrappers.append(raw)
|
|
1024
|
+
if depth < MAX_DEPTH:
|
|
1025
|
+
_collect_requests(raw.get("children") or [], name, containers, wrappers, depth + 1)
|
|
1026
|
+
|
|
1027
|
+
|
|
1028
|
+
def _folded_child(raw: dict, parent: dict) -> dict:
|
|
1029
|
+
"""One log request span, rewritten to sit under the call it belongs to.
|
|
1030
|
+
|
|
1031
|
+
A record that produced a single typed block *is* that block — the two share
|
|
1032
|
+
a window exactly — so the two spans collapse into one rather than drawing the
|
|
1033
|
+
same instants twice more. The block keeps its identity and content; the
|
|
1034
|
+
request hands over its attributes and its tokens.
|
|
1035
|
+
|
|
1036
|
+
Handing the tokens over matters more than it looks. The producer's own
|
|
1037
|
+
`totals.tokens` is the sum over every span it wrote, duplicated usage
|
|
1038
|
+
included: dropping a record's copy here would leave the recomputed breakdown
|
|
1039
|
+
disagreeing with the reported totals by a factor of three, and this reader
|
|
1040
|
+
would appear to have invented the defect.
|
|
1041
|
+
"""
|
|
1042
|
+
children = [c for c in raw.get("children") or [] if isinstance(c, dict)]
|
|
1043
|
+
typed = [c for c in children if str(c.get("kind") or "") in _BLOCK_KINDS]
|
|
1044
|
+
out = dict(raw)
|
|
1045
|
+
if len(children) == 1 and len(typed) == 1 and _window(typed[0]) == _window(raw):
|
|
1046
|
+
block = typed[0]
|
|
1047
|
+
attributes = {**(raw.get("attributes") or {}), **(block.get("attributes") or {})}
|
|
1048
|
+
attributes[_MERGED_FROM] = str(raw.get("span_id") or "")
|
|
1049
|
+
out = dict(block, attributes=attributes)
|
|
1050
|
+
if raw.get("tokens") and not block.get("tokens"):
|
|
1051
|
+
out["tokens"] = raw["tokens"]
|
|
1052
|
+
out["parent_span_id"] = str(parent.get("span_id") or "")
|
|
1053
|
+
return out
|
|
1054
|
+
|
|
1055
|
+
|
|
1056
|
+
def fold_llm_requests(spans: list) -> list:
|
|
1057
|
+
"""Each measured LLM call given the log spans for the reply it produced.
|
|
1058
|
+
|
|
1059
|
+
Without this the same call is drawn twice — as `claude_code.llm_request`
|
|
1060
|
+
under the interaction, and again as `llm_request` under the log's own
|
|
1061
|
+
`session` subtree — with the second copy carrying the reasoning and output
|
|
1062
|
+
text and the first carrying the only measured clock. Folding puts the blocks
|
|
1063
|
+
under the call, which is the shape Harbor itself writes when the exporter
|
|
1064
|
+
gives it a request id to join on.
|
|
1065
|
+
|
|
1066
|
+
Nothing is invented and nothing is dropped. Every span survives with its own
|
|
1067
|
+
start, end and tokens; a request span that collapsed into its one block is
|
|
1068
|
+
that block, carrying what the request knew. The rows move, the clocks do not,
|
|
1069
|
+
and the producer's `totals` is untouched, as ever.
|
|
1070
|
+
|
|
1071
|
+
Copy-on-write, like `prune`: a document with nothing to fold is returned by
|
|
1072
|
+
reference.
|
|
1073
|
+
"""
|
|
1074
|
+
containers, wrappers = [], []
|
|
1075
|
+
_collect_requests(spans, "", containers, wrappers)
|
|
1076
|
+
if not containers or not wrappers:
|
|
1077
|
+
return spans
|
|
1078
|
+
|
|
1079
|
+
folded = _match_requests(containers, _request_groups(wrappers))
|
|
1080
|
+
if not folded:
|
|
1081
|
+
return spans
|
|
1082
|
+
by_id = {str(c.get("span_id") or ""): c for c in containers}
|
|
1083
|
+
by_container = {
|
|
1084
|
+
parent_id: [_folded_child(raw, by_id[parent_id]) for raw in group]
|
|
1085
|
+
for parent_id, group in folded.items()
|
|
1086
|
+
}
|
|
1087
|
+
moved = {id(raw) for group in folded.values() for raw in group}
|
|
1088
|
+
return _fold_tree(spans, by_container, moved)[0]
|
|
1089
|
+
|
|
1090
|
+
|
|
1091
|
+
def _fold_tree(spans: list, by_container: dict, moved: set, depth: int = 0) -> tuple:
|
|
1092
|
+
"""(spans, changed) — the tree with the matched request spans relocated.
|
|
1093
|
+
|
|
1094
|
+
Identity, not span id, is what marks a span as moved: ids are opaque strings
|
|
1095
|
+
from two producers here, and a collision would otherwise delete a span rather
|
|
1096
|
+
than move it.
|
|
1097
|
+
"""
|
|
1098
|
+
out: list = []
|
|
1099
|
+
changed = False
|
|
1100
|
+
for raw in spans:
|
|
1101
|
+
if not isinstance(raw, dict):
|
|
1102
|
+
continue
|
|
1103
|
+
if id(raw) in moved:
|
|
1104
|
+
changed = True
|
|
1105
|
+
continue
|
|
1106
|
+
children = raw.get("children") or []
|
|
1107
|
+
if children and depth < MAX_DEPTH:
|
|
1108
|
+
children, dropped = _fold_tree(children, by_container, moved, depth + 1)
|
|
1109
|
+
else:
|
|
1110
|
+
dropped = False
|
|
1111
|
+
blocks = by_container.get(str(raw.get("span_id") or ""))
|
|
1112
|
+
if blocks:
|
|
1113
|
+
children = sorted(children + blocks, key=lambda s: _window(s)[0])
|
|
1114
|
+
attributes = dict(raw.get("attributes") or {})
|
|
1115
|
+
attributes[_MERGED_FROM] = ", ".join(
|
|
1116
|
+
str((b.get("attributes") or {}).get(_MERGED_FROM) or b.get("span_id") or "")
|
|
1117
|
+
for b in blocks
|
|
1118
|
+
)
|
|
1119
|
+
raw = dict(raw, children=children, attributes=attributes)
|
|
1120
|
+
elif dropped:
|
|
1121
|
+
raw = dict(raw, children=children)
|
|
1122
|
+
changed = changed or dropped or bool(blocks)
|
|
1123
|
+
out.append(raw)
|
|
1124
|
+
return out, changed
|
|
1125
|
+
|
|
1126
|
+
|
|
1127
|
+
def prune(spans: list, filt: "Filter | None" = None, depth: int = 0) -> tuple:
|
|
1128
|
+
"""(kept, removed) — hidden spans dropped, with their subtrees.
|
|
1129
|
+
|
|
1130
|
+
A hidden span takes its children with it. Keeping them would leave a tool's
|
|
1131
|
+
inner spans floating with no call around them, and hiding a call is a request
|
|
1132
|
+
to take its whole cost out of the picture — including the cost of what it did.
|
|
1133
|
+
|
|
1134
|
+
Copy-on-write: a subtree nothing was removed from is passed through by
|
|
1135
|
+
reference, so the caller's document is never mutated and saving a filtered
|
|
1136
|
+
view cannot corrupt the original.
|
|
1137
|
+
"""
|
|
1138
|
+
filt = filt or Filter()
|
|
1139
|
+
kept: list = []
|
|
1140
|
+
removed = 0
|
|
1141
|
+
for raw in spans:
|
|
1142
|
+
if not isinstance(raw, dict):
|
|
1143
|
+
continue
|
|
1144
|
+
if filt.hides(raw):
|
|
1145
|
+
removed += 1 + sum(1 for _ in raw_spans_of(raw.get("children") or []))
|
|
1146
|
+
continue
|
|
1147
|
+
children = raw.get("children") or []
|
|
1148
|
+
if children and depth < MAX_DEPTH:
|
|
1149
|
+
children, dropped = prune(children, filt, depth + 1)
|
|
1150
|
+
if dropped:
|
|
1151
|
+
removed += dropped
|
|
1152
|
+
raw = dict(raw, children=children)
|
|
1153
|
+
kept.append(raw)
|
|
1154
|
+
return kept, removed
|
|
1155
|
+
|
|
1156
|
+
|
|
1157
|
+
def merge_intervals(intervals: list) -> list:
|
|
1158
|
+
"""Overlapping [start, end) runs collapsed into disjoint ones."""
|
|
1159
|
+
out: list = []
|
|
1160
|
+
for start, end in sorted(intervals):
|
|
1161
|
+
if out and start <= out[-1][1]:
|
|
1162
|
+
out[-1] = (out[-1][0], max(out[-1][1], end))
|
|
1163
|
+
else:
|
|
1164
|
+
out.append((start, end))
|
|
1165
|
+
return out
|
|
1166
|
+
|
|
1167
|
+
|
|
1168
|
+
def partition(by_category: dict, priority: tuple = _PRIORITY) -> dict:
|
|
1169
|
+
"""Split the timeline so every instant is charged to exactly one category.
|
|
1170
|
+
|
|
1171
|
+
Summing durations exceeds the wall clock as soon as spans nest or overlap,
|
|
1172
|
+
and both happen here: a tool call sits inside the LLM call that asked for it,
|
|
1173
|
+
and background subagents run alongside the main thread. Each elementary
|
|
1174
|
+
segment goes to the highest-priority category covering it, which keeps the
|
|
1175
|
+
categories disjoint by construction and the stacked strip honest.
|
|
1176
|
+
"""
|
|
1177
|
+
merged = {cat: merge_intervals(by_category.get(cat) or []) for cat in priority}
|
|
1178
|
+
starts = {cat: [start for start, _ in ivs] for cat, ivs in merged.items()}
|
|
1179
|
+
edges = sorted({point for ivs in merged.values() for iv in ivs for point in iv})
|
|
1180
|
+
totals = {cat: 0 for cat in priority}
|
|
1181
|
+
|
|
1182
|
+
def covers(cat: str, low: int) -> bool:
|
|
1183
|
+
ivs = merged[cat]
|
|
1184
|
+
i = bisect.bisect_right(starts[cat], low) - 1
|
|
1185
|
+
return i >= 0 and ivs[i][1] > low
|
|
1186
|
+
|
|
1187
|
+
for low, high in zip(edges, edges[1:]):
|
|
1188
|
+
for cat in priority:
|
|
1189
|
+
if covers(cat, low):
|
|
1190
|
+
totals[cat] += high - low
|
|
1191
|
+
break
|
|
1192
|
+
return totals
|
|
1193
|
+
|
|
1194
|
+
|
|
1195
|
+
def breakdown(spans: list, wall_ns: int = 0) -> Breakdown:
|
|
1196
|
+
"""Recompute category time, span counts and tokens over *spans*.
|
|
1197
|
+
|
|
1198
|
+
See :class:`Breakdown` for why this is not the producer's arithmetic and must
|
|
1199
|
+
not be presented as it. Spans with no usable end contribute no time — an
|
|
1200
|
+
unknown clock is not a zero one — but they are still counted and their tokens
|
|
1201
|
+
still add up.
|
|
1202
|
+
"""
|
|
1203
|
+
by_category: dict = {}
|
|
1204
|
+
tokens: dict = {}
|
|
1205
|
+
count = 0
|
|
1206
|
+
measured = 0
|
|
1207
|
+
for raw in raw_spans_of(spans):
|
|
1208
|
+
count += 1
|
|
1209
|
+
if str(raw.get("timing_quality") or "") == "measured":
|
|
1210
|
+
measured += 1
|
|
1211
|
+
for key, value in (raw.get("tokens") or {}).items():
|
|
1212
|
+
if _int_or_none(value) is not None:
|
|
1213
|
+
tokens[key] = tokens.get(key, 0) + value
|
|
1214
|
+
category = category_of(raw)
|
|
1215
|
+
start = _int_or_none(raw.get("start_ns"))
|
|
1216
|
+
end = _int_or_none(raw.get("end_ns"))
|
|
1217
|
+
if category and start is not None and end is not None and end > start:
|
|
1218
|
+
by_category.setdefault(category, []).append((start, end))
|
|
1219
|
+
split = partition(by_category)
|
|
1220
|
+
return Breakdown(
|
|
1221
|
+
wall_ns=int(wall_ns or 0),
|
|
1222
|
+
llm_ns=split.get("llm", 0),
|
|
1223
|
+
tool_ns=split.get("tool", 0),
|
|
1224
|
+
reasoning_ns=split.get("reasoning", 0),
|
|
1225
|
+
idle_ns=split.get("idle", 0),
|
|
1226
|
+
span_count=count,
|
|
1227
|
+
measured_span_count=measured,
|
|
1228
|
+
tokens=tokens,
|
|
1229
|
+
)
|
|
1230
|
+
|
|
1231
|
+
|
|
1232
|
+
# Stamped into a saved view as both its producer and the hand that filtered it.
|
|
1233
|
+
FILTER_PRODUCER = "app/nullius/trace.py (filtered view)"
|
|
1234
|
+
|
|
1235
|
+
|
|
1236
|
+
def filtered_document(data: dict, filt: "Filter | None" = None) -> dict:
|
|
1237
|
+
"""*data* with the hidden spans gone and ``totals`` recomputed over the rest.
|
|
1238
|
+
|
|
1239
|
+
What gets written to disk, and the reason :func:`prune` works on raw dicts.
|
|
1240
|
+
Three things are load-bearing about the result:
|
|
1241
|
+
|
|
1242
|
+
* it is still a ``harbor-trace-v1`` document, so this app can open it;
|
|
1243
|
+
* ``wall_ns`` is the source's, so removed time surfaces as ``unaccounted``
|
|
1244
|
+
rather than vanishing into a shorter run;
|
|
1245
|
+
* the producer's own ``totals`` survives verbatim under ``filtered``, since a
|
|
1246
|
+
derived number that has overwritten the measured one is unfalsifiable.
|
|
1247
|
+
|
|
1248
|
+
Filtering a view that was itself saved from a filtered view works, and the
|
|
1249
|
+
chain is kept under ``filtered.previous`` rather than overwritten — otherwise
|
|
1250
|
+
the second save would present derived totals as if they were measured.
|
|
1251
|
+
"""
|
|
1252
|
+
filt = filt or Filter()
|
|
1253
|
+
# The same two normalisations `parse` does, in the same order, and each for
|
|
1254
|
+
# its own reason. Folding first because hiding a call takes its subtree with
|
|
1255
|
+
# it and folding is what puts the reply's blocks in that subtree, so an
|
|
1256
|
+
# unfolded save would drop a different set of spans than the page showed;
|
|
1257
|
+
# `mark_groups` because `hide` carries the displayed label, and "Bash [group]"
|
|
1258
|
+
# only matches a span that has been re-kinded. Both are written out with the
|
|
1259
|
+
# spans — the document already names this tree as its producer, and a saved
|
|
1260
|
+
# view that reopened as a different shape than the one saved would be worse
|
|
1261
|
+
# than a changed enum.
|
|
1262
|
+
kept, removed = prune(mark_groups(fold_llm_requests(data.get("spans") or [])), filt)
|
|
1263
|
+
source_totals = data.get("totals") or {}
|
|
1264
|
+
view = breakdown(kept, _int_or_none(source_totals.get("wall_ns")) or 0)
|
|
1265
|
+
out = dict(data)
|
|
1266
|
+
out["spans"] = kept
|
|
1267
|
+
out["totals"] = view.as_totals()
|
|
1268
|
+
# This file was written here, whatever wrote the spans — `producer` naming a
|
|
1269
|
+
# script that never saw these totals is exactly the kind of plausible-looking
|
|
1270
|
+
# provenance that makes a derived artefact unfalsifiable. The original moves
|
|
1271
|
+
# into the block below rather than being dropped.
|
|
1272
|
+
out["producer"] = FILTER_PRODUCER
|
|
1273
|
+
out["filtered"] = {
|
|
1274
|
+
"by": FILTER_PRODUCER,
|
|
1275
|
+
"source_producer": str(data.get("producer") or ""),
|
|
1276
|
+
"hide": list(filt.names),
|
|
1277
|
+
"hide_span": list(filt.span_ids),
|
|
1278
|
+
"spans_removed": removed,
|
|
1279
|
+
"note": (
|
|
1280
|
+
"totals recomputed from the spans left, by charging every instant to one "
|
|
1281
|
+
"category at priority idle > tool > reasoning > llm; wall_ns is the source's, "
|
|
1282
|
+
"so the removed time reads as unaccounted; log request spans matched to the "
|
|
1283
|
+
"measured call they belong to were folded under it first (app.merged_from), "
|
|
1284
|
+
"and spans that only bracket a same-named child are re-kinded 'group' and "
|
|
1285
|
+
"charged no time"
|
|
1286
|
+
),
|
|
1287
|
+
"source_totals": source_totals,
|
|
1288
|
+
}
|
|
1289
|
+
previous = data.get("filtered")
|
|
1290
|
+
if isinstance(previous, dict):
|
|
1291
|
+
out["filtered"]["previous"] = previous
|
|
1292
|
+
return out
|
|
1293
|
+
|
|
1294
|
+
|
|
1295
|
+
def _clamp(value: float, low: float = 0.0, high: float = 100.0) -> float:
|
|
1296
|
+
return max(low, min(high, value))
|
|
1297
|
+
|
|
1298
|
+
|
|
1299
|
+
def place(span: Span, extent: Extent) -> tuple:
|
|
1300
|
+
"""(left_pct, width_pct) on the global axis.
|
|
1301
|
+
|
|
1302
|
+
All arithmetic is Python int until this line, so the nanosecond magnitudes
|
|
1303
|
+
that overflow a JS double are exact here — no BigInt problem to work around.
|
|
1304
|
+
"""
|
|
1305
|
+
left = _clamp((span.start_ns - extent.start_ns) / extent.span_ns * 100)
|
|
1306
|
+
duration = span.duration_ns or 0
|
|
1307
|
+
width = _clamp(duration / extent.span_ns * 100, 0.0, 100.0 - left)
|
|
1308
|
+
return left, width
|
|
1309
|
+
|
|
1310
|
+
|
|
1311
|
+
def is_instant(span: Span) -> bool:
|
|
1312
|
+
"""No usable duration: one known instant, or an explicitly unknown clock."""
|
|
1313
|
+
return span.timing_quality == "unknown" or not (span.duration_ns and span.duration_ns > 0)
|
|
1314
|
+
|
|
1315
|
+
|
|
1316
|
+
def flatten(roots: list, collapsed=frozenset(), extent: Extent | None = None) -> tuple:
|
|
1317
|
+
"""Depth-first rows, skipping the children of collapsed spans.
|
|
1318
|
+
|
|
1319
|
+
Returns (rows, truncated). Collapse is honoured here so it is testable, but
|
|
1320
|
+
the template renders every row and lets the browser hide descendants — which
|
|
1321
|
+
is what makes expanding a deep-linked span a no-round-trip operation.
|
|
1322
|
+
|
|
1323
|
+
*extent* is the window the rows are placed on and their offsets counted
|
|
1324
|
+
from. A zoomed view passes the subtree's own window here (`extent_of` over
|
|
1325
|
+
the one span), so every offset it shows is from the zoomed span's start —
|
|
1326
|
+
the same origin its axis ticks use.
|
|
1327
|
+
"""
|
|
1328
|
+
if extent is None:
|
|
1329
|
+
extent = extent_of(roots)
|
|
1330
|
+
|
|
1331
|
+
rows: list = []
|
|
1332
|
+
truncated = 0
|
|
1333
|
+
seen: set = set()
|
|
1334
|
+
|
|
1335
|
+
def walk(span, depth):
|
|
1336
|
+
nonlocal truncated
|
|
1337
|
+
if span.span_id and span.span_id in seen:
|
|
1338
|
+
return
|
|
1339
|
+
seen.add(span.span_id)
|
|
1340
|
+
if len(rows) >= MAX_ROWS:
|
|
1341
|
+
# Count what is being dropped, so the page can say so rather than
|
|
1342
|
+
# silently ending mid-tree.
|
|
1343
|
+
truncated += 1 + sum(1 for _ in all_spans(span.children))
|
|
1344
|
+
return
|
|
1345
|
+
left, width = place(span, extent)
|
|
1346
|
+
rows.append(
|
|
1347
|
+
Row(
|
|
1348
|
+
span=span,
|
|
1349
|
+
depth=depth,
|
|
1350
|
+
has_children=bool(span.children),
|
|
1351
|
+
offset_ns=span.start_ns - extent.start_ns,
|
|
1352
|
+
left_pct=left,
|
|
1353
|
+
width_pct=width,
|
|
1354
|
+
is_instant=is_instant(span),
|
|
1355
|
+
)
|
|
1356
|
+
)
|
|
1357
|
+
if span.children and span.span_id not in collapsed:
|
|
1358
|
+
for child in span.children:
|
|
1359
|
+
walk(child, depth + 1)
|
|
1360
|
+
|
|
1361
|
+
for root in roots:
|
|
1362
|
+
walk(root, 0)
|
|
1363
|
+
return rows, truncated
|
|
1364
|
+
|
|
1365
|
+
|
|
1366
|
+
def ticks_for(extent: Extent, n: int = 5) -> list:
|
|
1367
|
+
"""Axis ticks on a 1/2/5×10^k step, labelled as offsets from the start."""
|
|
1368
|
+
span = extent.span_ns
|
|
1369
|
+
if span <= 1:
|
|
1370
|
+
return [Tick(pct=0.0, ns=0)]
|
|
1371
|
+
rough = span / max(n, 1)
|
|
1372
|
+
magnitude = 10 ** int(math.floor(math.log10(rough)))
|
|
1373
|
+
step = next(
|
|
1374
|
+
(m * magnitude for m in (1, 2, 5, 10) if m * magnitude >= rough),
|
|
1375
|
+
10 * magnitude,
|
|
1376
|
+
)
|
|
1377
|
+
ticks = []
|
|
1378
|
+
value = 0
|
|
1379
|
+
while value <= span and len(ticks) <= n * 3:
|
|
1380
|
+
ticks.append(Tick(pct=value / span * 100, ns=int(value)))
|
|
1381
|
+
value += step
|
|
1382
|
+
return ticks
|
|
1383
|
+
|
|
1384
|
+
|
|
1385
|
+
def _totals(raw: dict) -> Totals:
|
|
1386
|
+
if not raw:
|
|
1387
|
+
return Totals()
|
|
1388
|
+
return Totals(
|
|
1389
|
+
wall_ns=_int_or_none(raw.get("wall_ns")),
|
|
1390
|
+
llm_ns=_int_or_none(raw.get("llm_ns")),
|
|
1391
|
+
tool_ns=_int_or_none(raw.get("tool_ns")),
|
|
1392
|
+
reasoning_ns=_int_or_none(raw.get("reasoning_ns")),
|
|
1393
|
+
idle_ns=_int_or_none(raw.get("idle_ns")),
|
|
1394
|
+
span_count=_int_or_none(raw.get("span_count")),
|
|
1395
|
+
measured_span_count=_int_or_none(raw.get("measured_span_count")),
|
|
1396
|
+
)
|
|
1397
|
+
|
|
1398
|
+
|
|
1399
|
+
def parse(data: dict, filt: "Filter | None" = None) -> Trace:
|
|
1400
|
+
"""Build a Trace from already-decoded JSON. Pure — what the tests drive.
|
|
1401
|
+
|
|
1402
|
+
*filt* hides spans from the view (see :class:`Filter`). Everything the filter
|
|
1403
|
+
controls needs the unfiltered document too, and for different reasons: the
|
|
1404
|
+
chips have to offer labels that are currently hidden, the axis has to stay
|
|
1405
|
+
where it was so the surviving bars do not move, and the producer's `totals`
|
|
1406
|
+
is reported whatever is on screen.
|
|
1407
|
+
"""
|
|
1408
|
+
if not isinstance(data, dict):
|
|
1409
|
+
return Trace(error="trace.json is not an object")
|
|
1410
|
+
|
|
1411
|
+
filt = filt or Filter()
|
|
1412
|
+
# Normalised before anything reads it, so `raw` is the unfiltered document as
|
|
1413
|
+
# the page will name it — the chips, the axis, the filter and the baseline
|
|
1414
|
+
# breakdown all come off this list, and a span has to be folded and named the
|
|
1415
|
+
# same way in every one of them. Same order, and the same list, as
|
|
1416
|
+
# `filtered_document` writes out.
|
|
1417
|
+
raw = mark_groups(fold_llm_requests(data.get("spans") or []))
|
|
1418
|
+
kept, hidden = prune(raw, filt)
|
|
1419
|
+
roots = [_span(s) for s in kept]
|
|
1420
|
+
extent = raw_extent(raw)
|
|
1421
|
+
# The zoom is a second, explicit window on top of the filter — never a
|
|
1422
|
+
# re-scaling of the filtered view. It is looked up in the *pruned* tree, so a
|
|
1423
|
+
# zoom on a span the filter hides falls back to the whole trace with a note,
|
|
1424
|
+
# and the axis it re-bases on is the subtree's own extent (`extent_of` over
|
|
1425
|
+
# the one span, the same walk the global axis uses — no second layout).
|
|
1426
|
+
# Spans outside the subtree are left out of the rows, not squeezed in.
|
|
1427
|
+
axis, zoomed, zoom_lost = extent, None, ""
|
|
1428
|
+
if filt.zoom:
|
|
1429
|
+
zoomed = find_span(roots, filt.zoom)
|
|
1430
|
+
if zoomed is None:
|
|
1431
|
+
zoom_lost = filt.zoom
|
|
1432
|
+
else:
|
|
1433
|
+
axis = extent_of([zoomed])
|
|
1434
|
+
rows, truncated = flatten([zoomed] if zoomed else roots, extent=axis)
|
|
1435
|
+
totals = _totals(data.get("totals") or {})
|
|
1436
|
+
names = labels_by_id(raw) if filt.span_ids else {}
|
|
1437
|
+
|
|
1438
|
+
return Trace(
|
|
1439
|
+
# Real files emit `trial_name`; the format doc calls it `run_id`. Take
|
|
1440
|
+
# either, prefer what the producer actually writes.
|
|
1441
|
+
run_id=str(data.get("trial_name") or data.get("run_id") or ""),
|
|
1442
|
+
roots=roots,
|
|
1443
|
+
totals=totals,
|
|
1444
|
+
extent=extent,
|
|
1445
|
+
axis=axis,
|
|
1446
|
+
rows=rows,
|
|
1447
|
+
ticks=ticks_for(axis) if rows else [],
|
|
1448
|
+
truncated=truncated,
|
|
1449
|
+
shown=sum(1 for _ in all_spans(roots)),
|
|
1450
|
+
zoomed=zoomed,
|
|
1451
|
+
zoom_lost=zoom_lost,
|
|
1452
|
+
filter=filt,
|
|
1453
|
+
facets=inventory(raw, filt),
|
|
1454
|
+
hidden_spans=[(sid, names.get(sid, sid)) for sid in filt.span_ids],
|
|
1455
|
+
hidden_count=hidden,
|
|
1456
|
+
# The wall clock is the run's, not the view's — see `Breakdown`. With no
|
|
1457
|
+
# `totals` block to take it from, the instrumented window is the best
|
|
1458
|
+
# denominator available, and it is the one the axis already uses.
|
|
1459
|
+
view=breakdown(kept, totals.wall_ns or extent.span_ns),
|
|
1460
|
+
# The same arithmetic over the unfiltered tree, so the view can show what
|
|
1461
|
+
# the filter changed without the producer's own accounting in the way.
|
|
1462
|
+
baseline=breakdown(raw, totals.wall_ns or extent.span_ns),
|
|
1463
|
+
)
|
|
1464
|
+
|
|
1465
|
+
|
|
1466
|
+
def load(path: str, filt: "Filter | None" = None) -> Trace:
|
|
1467
|
+
"""Read *path*, or return a Trace carrying the error.
|
|
1468
|
+
|
|
1469
|
+
A trace is an observability sidecar: a missing or broken one must never take
|
|
1470
|
+
the trial page down with it.
|
|
1471
|
+
"""
|
|
1472
|
+
try:
|
|
1473
|
+
with open(path, encoding="utf-8") as fh:
|
|
1474
|
+
data = json.load(fh)
|
|
1475
|
+
except (OSError, json.JSONDecodeError) as exc:
|
|
1476
|
+
return Trace(error=str(exc))
|
|
1477
|
+
return parse(data, filt)
|