Honeycomb Tracing

Produce an inspectable waterfall tied to the actual run or CI attempt, explain which intervals dominate elapsed time, and identify the smallest useful next experiment. Respect diagnosis-only requests; tracing does not itself authorize replaying tasks, changing credentials, or deploying instrumentation.

Choose the data path

Question	Start here
Why is a task slow before, during, or after model execution?	Application workflow below; runtime setup if spans are absent
Why does an issue page load slowly?	Request spans plus browser timing, described below
Which CI jobs or test files delay the whole suite?	CI profiling
How should a trace be organized so a person can understand it?	Human-readable waterfall guidance below and trace design
Where should a new span go?	Instrumentation guidance below and Observability contract

Repository-relative paths and commands assume the checkout root. The maintained contracts are doc/observability.md and doc/ci-profiling.md; recheck them and the owning code when a deployed version differs.

Keep the repository's three paths distinct:

• Observability: operator-configured OpenTelemetry export to Honeycomb or another OTLP destination. With no endpoint, this tracing stays off.
• Telemetry: first-party events under packages/shared/src/telemetry/, sent to Paperclip by default unless opted out. Adding these requires the generated contract, Telemetry README, and privacy-review workflow in AGENTS.md.
• Run log: local heartbeat_run_events and measured performance events. Useful for correlation, but a local event is not proof of Honeycomb export.

Observability changes within the closed span-attribute allowlist do not need the Telemetry privacy review. Preserve the endpoint gate and no-operation behavior.

Find the application's trace