← ClaudeAtlas

sentry-instrumentationlisted

Rules and examples for adding Sentry instrumentation the right way — metrics and tracing. Covers how to name a counter, gauge, or duration metric; which attributes are group-by tags (closed lists) versus debug context (ids); how to track failures with a small fixed list of error types instead of raw exception strings; how to add metrics around HTTP routes, external API calls, workflow steps, retry loops, and fallback paths without copy-pasting emit calls everywhere; and how to instrument AI agent conversations with `gen_ai.*` spans (invoke_agent / chat / execute_tool, conversation ids, token accounting) for Sentry's Conversations view. Ships a CI check that blocks bad metrics before merge. Use this when someone asks to "instrument" code, "add a metric", "track duration", "count failures", "emit a counter/gauge/distribution", "add a span", "observe" a workflow step, add a route, external API client, retry loop, or fallback path, or "instrument an AI agent / LLM call / tool call", "track conversations", or "tra
tortastudios/sentry-instrumentation · ★ 24 · AI & Automation · score 81
Install: claude install-skill tortastudios/sentry-instrumentation
# Sentry Instrumentation Two surfaces: **system metrics** (counter / gauge / distribution, duration, failure, resource) and **tracing** (currently the `gen_ai.*` spans for AI agent conversations — see rule 7). Product-analytics events (clicks, funnels, flag exposure) belong in your product-analytics tool — never in Sentry. Python under `examples/python/` is the canonical reference; other languages port the same shapes under idiomatic names. Do not invoke for product-analytics changes. Stop and use the right tool. ## Decision rules 1. **New metric?** Read `references/signal-model.md` and pick a classmethod constructor (`MetricDef.counter|latency|gauge|resource|failure_counter`). Register in the project's metric registry. **Never** call an emission helper with a raw string or a dynamically-assembled name. 2. **Attributes?** Two kinds, both declared on the `MetricDef` (see `references/tagging-and-cardinality.md`). **Group-by tags** (`tags=`) — what dashboards and alerts group on — are closed sets: enumerate the values or route through a bucket function. **Debug context** (`context=`) — ids like `account_id`, `project_id`, `order_id` used to find who was affected — are declared by key and free-valued; Sentry stores full metric events, so they are queryable. Never put an id in `tags=`. Never put free-form text, exception strings, emails or raw URLs on a metric in either role. Don't add `trace_id` — every metric already carries it. 3. **Inside a loop?** Use `AggregatingCounter`