Official agent skill

Sentry Instrumentation Guide

by getsentry in getsentry/sentry-for-ai

Decide which Sentry signal to reach for when instrumenting code — error, span, span attribute, log, or metric.

OfficialApache-2.0Auto-check passed

Install Sentry Instrumentation Guide

skills CLI
$ npx skills add getsentry/sentry-for-ai --skill sentry-instrumentation-guide -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install getsentry/sentry-for-ai sentry-instrumentation-guide --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/getsentry/sentry-for-ai.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills-legacy/sentry-instrumentation-guide .claude/skills/sentry-instrumentation-guide && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
sentry-instrumentation-guide
GitHub stars
268
Token cost
~2k tokens
SKILL.md length
1,063 words
Files
3 (incl. references)
Skills in repo
32
Repo updated
First seen
Licence
Apache-2.0

At a glance

Decide which Sentry signal to reach for when instrumenting code — error, span, span attribute, log, or metric.

  • Adding instrumentation and unsure whether something should be a log vs a span vs a metric
  • SKILL.md covers Invoke This Skill When, The Four Signals, One Question…, The Decision Table and Resolving the Overlaps, plus 3 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
  • Deciding what to instrument where

What it does

Sentry Instrumentation Guide is an agent skill from getsentry/sentry-for-ai, published by the product's own GitHub organization. Decide which Sentry signal to reach for when instrumenting code — error, span, span attribute, log, or metric. Use when adding instrumentation and unsure whether something should be a log vs a span vs a metric, when deciding "what to instrument where", when reviewing instrumentation for gaps, or when a coding agent needs a rule for choosing between errors, traces, logs, and metrics. This skill decides WHAT to emit; the sentry--sdk skills handle HOW to set each pillar up.

Its SKILL.md is about 2k tokens, which your agent loads only when the skill is triggered. The skill folder holds 3 other files, including reference files (for example `references/choosing-signals.md` and `references/instrumentation-examples.md`).

It works with Sentry. The repository describes itself as: Teach your AI coding assistant how to use Sentry - setup, debugging, alerts, and more. The licence is Apache-2.0.

When your agent uses it

  • Adding instrumentation and unsure whether something should be a log vs a span vs a metric
  • Deciding what to instrument where
  • Reviewing instrumentation for gaps
  • A coding agent needs a rule for choosing between errors

Example prompts

  • “what to instrument where”
  • “/sentry-instrumentation-guide”

Requirements

  • Pre-approved tools (allowed-tools): Read, Grep, Glob

What it can do on your machine

Read from SKILL.md and the folder at commit d8fd106. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • Read
    • Grep
    • Glob

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • docs.sentry.io

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Sentry Instrumentation Guide loads about 2k tokens when it runs, and up to ~6.2k if it reads all its reference files. Until then it costs about 126 tokens; SKILL.md has 1,063 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~126
When it runs · the whole SKILL.md, loaded when a task matches
~2k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~6.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from getsentry/sentry-for-ai at commit d8fd106, republished under its Apache-2.0 licence (© getsentry). 1,063 words, ~2,000 tokens.

Download SKILL.mdSave it as .claude/skills/sentry-instrumentation-guide/SKILL.md (or your agent's skills folder). This skill also uses 2 other files; get the full folder from GitHub.
name
sentry-instrumentation-guide
description
Decide which Sentry signal to reach for when instrumenting code — error, span, span attribute, log, or metric. Use when adding instrumentation and unsure whether something should be a log vs a span vs a metric, when deciding "what to instrument where", when reviewing instrumentation for gaps, or when a coding agent needs a rule for choosing between errors, traces, logs, and metrics. This skill decides WHAT to emit; the sentry-*-sdk skills handle HOW to set each pillar up.
allowed-tools
Read, Grep, Glob
license
Apache-2.0
category
feature-setup
parent
sentry-feature-setup
disable-model-invocation
true

All Skills > Feature Setup > Instrumentation Guide

Sentry Instrumentation Guide: When to Reach for What

Errors, traces, logs, and metrics are the four kinds of telemetry most apps run on, and they overlap enough that the choice is rarely obvious. You can stuff context into a span attribute instead of logging it. You can count log lines instead of emitting a metric. You can add a duration to a log and call it a span.

But each signal exists because it answers a different question and feeds a different workflow once it lands. Reaching for the wrong one means the data is technically there but useless for the job you actually have later. This skill is the decision framework: given a value or an event in front of you, which signal should carry it, and why.

It decides what to emit. For how to turn each pillar on for a given stack, hand off to the sentry-*-sdk skills and sentry-setup-ai-monitoring.

Invoke This Skill When

  • You're instrumenting a piece of code and unsure whether something should be a log, a span, a span attribute, or a metric
  • You're deciding "what to instrument where" across a service or request handler
  • You're reviewing existing instrumentation for gaps (e.g. an error feed that's empty while users report problems)
  • A coding agent needs a consistent rule for choosing between errors, traces, logs, and metrics

Important: The SDK APIs and code samples here are illustrative. Verify exact signatures and minimum versions against docs.sentry.io and the relevant sentry-*-sdk skill before implementing.

The Four Signals, One Question Each

SignalThe question it answersDocs
Errors"What just broke?" — a stack trace and exception type, grouped into a deduplicated Issue that gets assigned and tracked to resolution. If your code threw, it's an error.Issues
Traces"Did the request flow the way it was supposed to?" — a waterfall of timed spans. Mostly auto-instrumented.Trace Explorer
Logs"What was true at this point in the code, and why?" — the system's state at one moment as a structured event: config, flags, inputs/outputs, the decision that was made.Logs
Metrics"How's this trending over time?" — counters, gauges, distributions you can slice by attribute and chart, alert on, or compare across a deploy.Metrics

A useful mental split: a log is one request's story (the needle), a metric is the aggregate (whether the haystack is normal), a trace is where the time went, and an error is the thing that needs a stack trace and an owner.

The Decision Table

Use this as a gut check:

What you want to knowReach for
Something crashed, show the stack traceError
How long did this take? Which step is slow?Traces / Spans
Did the request flow through the steps I expected?Traces / Spans
What was the state when the code made this decision?Log
What did this function receive and return?Log
How often does X happen? Is the rate normal?Metric
Did something change after the deploy?Metric

Resolving the Overlaps

The same value can legitimately appear in more than one signal. These four tiebreakers cover almost every real case. (Full reasoning, gotchas, and the "why not just log everything / emit one wide event?" arguments live in references/choosing-signals.md.)

  • Span attribute or metric? Context about one request's flow that you want while reading that trace → span attribute (it rides on the span in the waterfall). A standalone value you want to chart, alert on, or slice over time across all requests → metric. The same number can warrant both: candidate_count on the span to read one request, recommendations.served as a metric to watch the rate.
  • Log or span? The span is the timed node in the flow (mostly auto-instrumented, you rarely write it). The log is the decision-point state inside that node (you always write it on purpose). Span answers where and how long; log answers what was true and why.
  • Log or metric? A log finds the one specific request that went wrong (the needle). A metric tells you how many requests went wrong (the haystack). Don't derive a rate by counting log lines — emit the metric directly.
  • Error or log? Needs a stack trace and should be tracked as an Issue → error. An unexpected-but-handled condition worth recording → log. Truly non-critical with a traceback → logger.warning(exc_info=True) keeps the trace in logs without creating noise in the error feed.
Show full SKILL.md (341 more words)Show less

Sampling vs Filtering — Match Retention to the Question

Each signal's retention falls out of the question it answers:

  • Traces are sampled. You don't need every request to understand where time goes, so keep a representative slice via traces_sample_rate (higher in dev, lower in production).
  • Errors are captured by default. No sampling to think about for the baseline.
  • Logs and metrics are NOT sampled. You keep every one and filter instead, with before_send_log and before_send_metric. This is the point: the whole reason for a log is to find the one rare request that went sideways, and you can't find what you sampled away.

(For the exact sampling and filtering config in your language, see the matching SDK skill's references/tracing.md and references/metrics.md.)

Because all four signals come from one SDK, they share a trace_id and correlate on their own — every log and metric is tied to its trace, so you can drill from a metric spike straight into the samples behind it.

What Deliberate Instrumentation Looks Like

Roughly 80% of spans are auto-instrumented by your framework and database integrations — you write almost none of them. The deliberate work is the other 20%: a span attribute or two to enrich the flow, a decision-point log, and a metric, placed at the spots where your code makes a choice worth questioning later.

references/instrumentation-examples.md walks through a single request handler instrumented end to end, in both Python and JavaScript/TypeScript, showing the span attribute, the log, and the metric side by side on the same decision.

Handing Off to Setup

This skill tells you what to emit. To actually wire a pillar up:

  • Install the SDK and turn on tracing, logs, and metrics → the matching sentry-<platform>-sdk skill (e.g. sentry-python-sdk, sentry-nextjs-sdk, sentry-node-sdk). Each has per-feature reference files for tracing, logging, metrics, and more.
  • Instrument LLM / agent calls → sentry-setup-ai-monitoring.

Logs and metrics are the two pillars most projects haven't turned on yet, and both are included on every plan. If they aren't enabled, route to the SDK skill first, then come back here to decide what to put where.

© getsentry, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 2 other files (references) in skills-legacy/sentry-instrumentation-guide of getsentry/sentry-for-ai.

  • SKILL.md
  • references/choosing-signals.md
  • references/instrumentation-examples.md

Open the folder on GitHubat commit d8fd106

Compare with similar skills

Sentry Instrumentation Guide next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Sentry Instrumentation Guide compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Sentry Instrumentation Guide this skillgetsentry/sentry-for-ai268—~2kAutomated safety check: PassApache-2.0
Code Design Rationale Investigatorcursor/plugins10k9 repos~2.6kAutomated safety check: PassNone
Node Backend Development Guidelinesdiet103/claude-code-infrastructure-showcase10k2 repos~2kAutomated safety check: PassMIT
Scraps Reviewgetsentry/sentry45k—~1.2kAutomated safety check: NotesCustom licence
Sentry v8 Error Trackingdiet103/claude-code-infrastructure-showcase10k2 repos~2.3kAutomated safety check: NotesMIT
Create Pull Request with Work Item IDmakeplane/plane60k—~824Automated safety check: PassAGPL-3.0

Similar skills

  • Official

    Digs into why code is shaped the way it is by checking git history, pull requests and connected tools in parallel, then reporting a cited read on the tradeoffs.

    10k GitHub starsUsed in 9 repos~2.6k tokens
    DevelopmentAuto-check passed
  • Node Backend Development Guidelines

    diet103/claude-code-infrastructure-showcase

    Sets layered architecture and coding rules for Node.js, Express and TypeScript microservices, covering routes, controllers, services, repositories, Prisma, Sentry and Zod.

    10k GitHub starsUsed in 2 repos~2k tokens
    Backend & APIsAuto-check passed
  • Scraps Review

    getsentry/sentry

    Official

    Filter large Sentry Scraps design-system migration PRs for review by separating mechanical import-path changes, generated baseline updates, snapshot mocks, and pure renames from substantive…

    45k GitHub stars~1.2k tokensUpdated today
    Frontend & DesignAuto-check: notes
  • Sentry v8 Error Tracking

    diet103/claude-code-infrastructure-showcase

    Enforces that every error in a service is captured to Sentry v8, with patterns for controllers, routes, cron jobs and database performance spans instead of console logging alone.

    10k GitHub starsUsed in 2 repos~2.3k tokens
    Backend & APIsAuto-check: notes
  • Opens a pull request for the current branch using the repo's template, a work item ID in the title and a description filled in from the actual diff.

    60k GitHub stars~824 tokensUpdated yesterday
    DevelopmentAuto-check passed
  • Analytics

    getsentry/sentry

    Official

    Instrument and discover analytics events in Sentry's frontend UI.

    45k GitHub stars~2.5k tokensUpdated today
    Frontend & DesignAuto-check passed

More from getsentry/sentry-for-ai

All 32 skills in this repo
  • Sentry Elixir SDK

    getsentry/sentry-for-ai

    Official

    Full Sentry SDK setup for Elixir. An agent skill from getsentry/sentry-for-ai.

    268 GitHub stars~3.5k tokensUpdated today
    Auto-check passed
  • Sentry Go SDK

    getsentry/sentry-for-ai

    Official

    Full Sentry SDK setup for Go. An agent skill from getsentry/sentry-for-ai.

    268 GitHub stars~3.2k tokensUpdated today
    Auto-check passed
  • Sentry Nextjs SDK

    getsentry/sentry-for-ai

    Official

    Full Sentry SDK setup for Next.js. An agent skill from getsentry/sentry-for-ai.

    268 GitHub stars~4.7k tokensUpdated today
    Auto-check: notes
  • Sentry Php SDK

    getsentry/sentry-for-ai

    Official

    Full Sentry SDK setup for PHP. An agent skill from getsentry/sentry-for-ai.

    268 GitHub stars~3.7k tokensUpdated today
    Auto-check: notes
  • Sentry Python SDK

    getsentry/sentry-for-ai

    Official

    Full Sentry SDK setup for Python. An agent skill from getsentry/sentry-for-ai.

    268 GitHub stars~4.1k tokensUpdated today
    Auto-check passed
  • Sentry React Router Framework SDK

    getsentry/sentry-for-ai

    Official

    Full Sentry SDK setup for React Router Framework mode. An agent skill from getsentry/sentry-for-ai.

    268 GitHub stars~3.8k tokensUpdated today
    Auto-check: notes

Works with

Questions about Sentry Instrumentation Guide

What does Sentry Instrumentation Guide do?

Decide which Sentry signal to reach for when instrumenting code — error, span, span attribute, log, or metric. Sentry Instrumentation Guide is an agent skill from getsentry/sentry-for-ai, published by the product's own GitHub organization. Decide which Sentry signal to reach for when instrumenting code — error, span, span attribute, log, or metric.

When should I use Sentry Instrumentation Guide?

Sentry Instrumentation Guide fits situations like: adding instrumentation and unsure whether something should be a log vs a span vs a metric; deciding what to instrument where; reviewing instrumentation for gaps; A coding agent needs a rule for choosing between errors.

How do I install Sentry Instrumentation Guide in Claude Code?

Run `npx skills add getsentry/sentry-for-ai --skill sentry-instrumentation-guide -a claude-code`. Or copy the skill folder (skills-legacy/sentry-instrumentation-guide in getsentry/sentry-for-ai) into .claude/skills/sentry-instrumentation-guide in your project. Claude Code loads it when a task matches its description.

How do I install Sentry Instrumentation Guide in Codex?

Run `npx skills add getsentry/sentry-for-ai --skill sentry-instrumentation-guide -a codex`. Or copy the skill folder (skills-legacy/sentry-instrumentation-guide in getsentry/sentry-for-ai) into .agents/skills/sentry-instrumentation-guide in your project. Codex loads it when a task matches its description.

Can I use Sentry Instrumentation Guide in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add getsentry/sentry-for-ai --skill sentry-instrumentation-guide -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/sentry-instrumentation-guide, .gemini/skills/sentry-instrumentation-guide, .github/skills/sentry-instrumentation-guide and .opencode/skills/sentry-instrumentation-guide in your project.

What does Sentry Instrumentation Guide need to run?

SKILL.md names no scripts, command-line tools or credentials: Sentry Instrumentation Guide is instructions for the agent only. Its frontmatter pre-approves these tools: Read, Grep, Glob.

Does Sentry Instrumentation Guide access the network?

SKILL.md names 1 domain. As links in the text: docs.sentry.io. This is read from the text; nothing was executed.

Is Sentry Instrumentation Guide safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Sentry Instrumentation Guide use?

Sentry Instrumentation Guide is published under the Apache-2.0 licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Sentry Instrumentation Guide use?

About 2k tokens (SKILL.md is roughly 8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 4.2k tokens, read only when the agent opens those files.

What are the alternatives to Sentry Instrumentation Guide?

Skills that share tags, products or a category with Sentry Instrumentation Guide: Code Design Rationale Investigator (cursor/plugins, 10k stars), Node Backend Development Guidelines (diet103/claude-code-infrastructure-showcase, 10k stars), Scraps Review (getsentry/sentry, 45k stars) and Sentry v8 Error Tracking (diet103/claude-code-infrastructure-showcase, 10k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Sentry Instrumentation Guide?

getsentry (a GitHub organization, an official publisher) maintains it in getsentry/sentry-for-ai, which has 268 GitHub stars. The repository holds 32 skills in this directory. The repository was last updated on October 7, 2026.

Source: getsentry/sentry-for-ai on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.