# Honeycomb Tracing

Finds traces in Honeycomb, diagnoses latency and adds missing spans.

- Repository: https://github.com/paperclipai/paperclip (109885 stars)
- Category: DevOps
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add paperclipai/paperclip --skill honeycomb-tracing -g -a claude-code -y`
Codex: `npx skills add paperclipai/paperclip --skill honeycomb-tracing -g -a codex -y`
Cursor: `npx skills add paperclipai/paperclip --skill honeycomb-tracing -g -a cursor -y`
Gemini CLI: `npx skills add paperclipai/paperclip --skill honeycomb-tracing -g -a gemini-cli -y`

## Description

Trace Paperclip runs, requests, and full CI suites in Honeycomb. Use to find traces, diagnose latency, design readable and foldable waterfalls, configure opt-in OpenTelemetry, or add missing spans.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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](references/runtime.md) 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](references/ci.md) |
| How should a trace be organized so a person can understand it? | Human-readable waterfall guidance below and [trace design](references/trace-design.md) |
| Where should a new span go? | Instrumentation guidance below and [Observability contract](../../../doc/observability.md) |

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

The rest: https://github.com/paperclipai/paperclip/blob/HEAD/.agents/skills/honeycomb-tracing/SKILL.md