sentry-instrumentation-guide
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.
- Installs
- 1.2K
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/getsentry/sentry-for-ai --skill sentry-instrumentation-guide- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads sentry-instrumentation-guide automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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
| Signal | The question it answers | Docs |
|---|---|---|
| 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 know | Reach for |
|---|---|
| Something crashed, show the stack trace | Error |
| 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_counton the span to read one request,recommendations.servedas 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.
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_logandbefore_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>-sdkskill (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.
FAQ
What does the sentry-instrumentation-guide skill do?
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.
How do I install sentry-instrumentation-guide?
Run npx skills add https://github.com/getsentry/sentry-for-ai --skill sentry-instrumentation-guide in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/sentry-instrumentation-guide/ (personal) or .claude/skills/sentry-instrumentation-guide/ (project).
Which AI agents can use sentry-instrumentation-guide?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is sentry-instrumentation-guide safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains sentry-instrumentation-guide?
It is published by getsentry in getsentry/sentry-for-ai. It has 1,181 recorded installs.
More from getsentry/sentry-for-ai
sentry-fix-issues
getsentry/sentry-for-ai
Find and fix issues from Sentry using MCP. Use when asked to fix Sentry errors, debug production issues, investigate exceptions, or resolve bugs reported in Sentry. Methodically analyzes stack traces, breadcrumbs, traces, and context to identify root causes.
sentry-react-native-sdk
getsentry/sentry-for-ai
Full Sentry SDK setup for React Native and Expo. Use when asked to "add Sentry to React Native", "install @sentry/react-native", "setup Sentry in Expo", or configure error monitoring, tracing, profiling, session replay, or logging for React Native applications. Supports Expo managed, Expo bare, and vanilla React Native.
sentry-create-alert
getsentry/sentry-for-ai
Create Sentry alerts using the workflow engine API. Use when asked to create alerts, set up notifications, configure issue priority alerts, or build workflow automations. Supports email, Slack, PagerDuty, Discord, and other notification actions.
sentry-nextjs-sdk
getsentry/sentry-for-ai
Full Sentry SDK setup for Next.js. Use when asked to "add Sentry to Next.js", "install @sentry/nextjs", or configure error monitoring, tracing, session replay, logging, profiling, AI monitoring, or crons for Next.js applications. Supports Next.js 13+ with App Router and Pages Router.
sentry-sdk-setup
getsentry/sentry-for-ai
Set up Sentry in any language or framework. Detects the user's platform and loads the right SDK skill. Use when asked to add Sentry, install an SDK, or set up error monitoring in a project.
sentry-workflow
getsentry/sentry-for-ai
Keep Sentry SDKs up to date. Use when asked to upgrade the Sentry SDK across major versions, migrate SDK versions, or fix deprecated APIs.
Popular devops & cloud skills
microsoft-foundry
microsoft/azure-skills
Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent create, managed harness agent create, GitHub Copilot harness agent, create agent, update agent, add tool to agent, invoke agent, agent insights, evaluate agent, batch eval, continuous eval, continuous monitoring, agent CI/CD, optimize prompt, improve prompt, optimize agent instructions, Agent Optimizer scaffold, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure
azure-diagnostics
microsoft/azure-skills
Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, container app 503 or target port mismatch, troubleshoot functions, function telemetry missing or stopped after a config/connection-string change, troubleshoot AKS, VM RDP, Linux SSH, VM black screen, can't connect to VM, reset VM password, NSG or firewall blocking, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, lock renewal during long-running processing, service bus dead letter.
azure-prepare
microsoft/azure-skills
Prepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wants to use azd as the deployment tool, or the project already has an azure.yaml file. DO NOT USE FOR: non-azd deployments, Python App Service code-only deploys (use python-appservice-deploy), or cross-cloud migration (use azure-cloud-migrate). WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure.
azure-ai
microsoft/azure-skills
Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.
azure-deploy
microsoft/azure-skills
Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: "run azd up", "run azd deploy", "execute deployment", "push to production", "push to cloud", "go live", "ship it", "bicep deploy", "terraform apply", "publish to Azure", "launch on Azure". DO NOT USE WHEN: "create and deploy", "build and deploy", "create a new app", "set up infrastructure", "create and deploy to Azure using Terraform" — use azure-prepare for these.
azure-validate
microsoft/azure-skills
Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment, verify RBAC roles, check role assignments, review managed identity permissions, what-if analysis, validate Container Apps deployment.