playbooks

home / skills / jeremylongshore / claude-code-plugins-plus-skills / sentry-known-pitfalls

sentry-known-pitfalls skill

/plugins/saas-packs/sentry-pack/skills/sentry-known-pitfalls

This skill helps you identify and fix common Sentry pitfalls by auditing initialization, DSN handling, and alert configurations.

npx playbooks add skill jeremylongshore/claude-code-plugins-plus-skills --skill sentry-known-pitfalls

Review the files below or copy the command above to add this skill to your agents.

Files (8)
SKILL.md
1.7 KB
---
name: sentry-known-pitfalls
description: |
  Execute common Sentry pitfalls and how to avoid them.
  Use when troubleshooting Sentry issues, reviewing configurations,
  or preventing common mistakes.
  Trigger with phrases like "sentry mistakes", "sentry pitfalls",
  "sentry common issues", "sentry anti-patterns".
allowed-tools: Read, Write, Edit, Grep
version: 1.0.0
license: MIT
author: Jeremy Longshore <[email protected]>
---

# Sentry Known Pitfalls

## Prerequisites

- Existing Sentry implementation to review
- Access to SDK configuration
- Understanding of current error patterns
- Codebase access for fixes

## Instructions

1. Verify SDK initialization happens before app starts
2. Check for single initialization point (no multiple init calls)
3. Use framework-specific SDK package for your framework
4. Ensure Error objects are captured (not strings)
5. Verify beforeSend returns event or null explicitly
6. Check DSN is in environment variables (not hardcoded)
7. Review sample rates for production appropriateness
8. Verify all transactions call finish() in try/finally
9. Check source map URL prefix matches actual URLs
10. Review alert configuration for threshold-based rules (avoid alert fatigue)

## Output
- Pitfalls identified in current setup
- Fixes applied for each issue
- Configuration validated
- Best practices checklist completed

## Error Handling

See `{baseDir}/references/errors.md` for comprehensive error handling.

## Examples

See `{baseDir}/references/examples.md` for detailed examples.

## Resources
- [Sentry Best Practices](https://docs.sentry.io/product/issues/best-practices/)
- [Troubleshooting Guide](https://docs.sentry.io/platforms/javascript/troubleshooting/)

Overview

This skill executes a focused review of common Sentry pitfalls and provides concrete fixes to avoid them. It helps teams spot misconfigurations, SDK initialization issues, alerting noise, and source map problems. Use it to validate Sentry setups and produce a prioritized remediation checklist.

How this skill works

The skill inspects SDK initialization points, environment configuration, and framework-specific packaging choices. It scans for anti-patterns like multiple inits, stringified errors, improper beforeSend handling, incorrect DSN usage, sampling misconfiguration, unfinished transactions, and mismatched source map URL prefixes. For each issue found it suggests a minimal, code-level fix and verifies configuration changes.

When to use it

  • During a Sentry onboarding or integration review to catch early mistakes
  • When troubleshooting missing or noisy error reports in production
  • Before releasing a major change that affects front-end bundling or source maps
  • When audit shows high alert fatigue or too many low-value incidents
  • As part of a post-incident review to ensure root-cause fixes are resilient

Best practices

  • Initialize the SDK once at app startup and centralize the initialization code
  • Use the framework-specific Sentry package for instrumentation and integrations
  • Capture Error objects (throwables) rather than plain strings to preserve stack traces
  • Keep DSN and sensitive flags in environment variables, not in source code
  • Explicitly return the event or null in beforeSend and test the behavior
  • Ensure transactions call finish() in a finally block so traces complete

Example use cases

  • Detect duplicate SDK init calls after a library update caused double reporting
  • Find a missing source map URL prefix that prevented symbolicated stack traces
  • Tune sample rates and alert thresholds to reduce noise without losing coverage
  • Replace string error captures with proper Error objects to restore stack context
  • Confirm DSN was leaked into a public repo and rotate credentials

FAQ

What should I do if I see duplicate events after a deploy?

Check for multiple SDK initializations, duplicate transports, and framework hot-reload hooks; centralize init and add guards to prevent re-initialization.

How do I verify source maps are correctly configured?

Confirm uploaded source map URLs match the deployed asset prefix and verify a sample event is symbolicated in Sentry.

When is it appropriate to change sample rates?

Adjust sample rates based on error volume and business impact: lower rates for high-volume noisy endpoints and keep 100% for critical flows.