playbooks

home / skills / jeremylongshore / claude-code-plugins-plus-skills / sentry-advanced-troubleshooting

sentry-advanced-troubleshooting skill

/plugins/saas-packs/sentry-pack/skills/sentry-advanced-troubleshooting

This skill helps debug complex Sentry issues by guiding advanced troubleshooting steps, including source maps, events, and performance validation.

npx playbooks add skill jeremylongshore/claude-code-plugins-plus-skills --skill sentry-advanced-troubleshooting

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

Files (9)
SKILL.md
1.8 KB
---
name: "sentry-advanced-troubleshooting"
description: |
  Execute advanced Sentry troubleshooting techniques.
  Use when debugging complex SDK issues, missing events,
  source map problems, or performance anomalies.
  Trigger with phrases like "sentry not working", "debug sentry",
  "sentry events missing", "fix sentry issues".
  
allowed-tools: "Read, Write, Edit, Grep, Bash(cmd:*)"
version: 1.0.0
license: MIT
author: "Jeremy Longshore <[email protected]>"
---

# Sentry Advanced Troubleshooting

## Prerequisites

- Debug mode enabled in SDK
- Access to application logs
- Sentry dashboard access
- Sentry CLI installed for source map debugging

## Instructions

1. Enable debug mode in SDK configuration to see verbose logging
2. Verify SDK initialization by checking if client exists after init
3. Test network connectivity to Sentry ingest endpoint
4. Check sampling configuration to ensure events are not being dropped
5. Temporarily disable beforeSend filtering during debugging
6. Use sentry-cli sourcemaps explain to diagnose source map issues
7. Verify transaction creation and finish calls for performance data
8. Check breadcrumb capture with beforeBreadcrumb debugging
9. Resolve SDK conflicts by ensuring single initialization
10. Run diagnostic script to generate comprehensive health report

## Output
- Root cause identified for SDK issues
- Source map problems resolved
- Event capture verified working
- Performance monitoring validated

## Error Handling

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

## Examples

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

## Resources
- [Sentry Troubleshooting](https://docs.sentry.io/platforms/javascript/troubleshooting/)
- [Source Maps Troubleshooting](https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting/)

Overview

This skill executes advanced Sentry troubleshooting techniques to diagnose and fix complex SDK issues, missing events, source map problems, and performance anomalies. It guides you through targeted checks and diagnostics so you can identify root causes and verify fixes. Use it interactively with triggers like "sentry not working" or "sentry events missing."

How this skill works

The skill walks through a checklist-style diagnostic flow: enable SDK debug logging, validate initialization, test network connectivity to Sentry ingest endpoints, and inspect sampling and filtering rules. It includes steps for source map analysis using sentry-cli, verifies transaction and breadcrumb capture for performance monitoring, and helps detect SDK conflicts and misconfigurations. A final diagnostic report summarizes findings and recommended fixes.

When to use it

  • When events are not appearing in Sentry despite errors being thrown
  • When JavaScript/CSS source maps are not resolving to original code
  • When performance transactions or traces are missing or incomplete
  • When you suspect SDK initialization conflicts or duplicate instances
  • When beforeSend or sampling rules may be dropping data

Best practices

  • Enable SDK debug mode only in development or temporary debugging sessions
  • Confirm a single SDK initialization and consistent DSN configuration
  • Temporarily disable beforeSend and custom filters to isolate drops
  • Use sentry-cli sourcemaps explain to validate uploaded source maps
  • Verify network connectivity to the correct ingest endpoint and firewall rules

Example use cases

  • Troubleshoot missing JavaScript events after a deploy that included minified bundles
  • Diagnose why performance transactions are not finishing or not reported
  • Resolve source map mismatch errors reported by Sentry and map stack frames to original code
  • Run a health-check script to produce a concise report of SDK, network, and config issues
  • Detect and remove duplicate SDK initializations that cause unexpected behavior

FAQ

What do I check first when events are missing?

Enable SDK debug logs, confirm initialization and DSN, test network connectivity to the ingest endpoint, and verify sampling and beforeSend filters.

How do I validate source maps?

Use sentry-cli sourcemaps explain against the uploaded artifacts and confirm the URLs, release, and bundle mapping match your deployed files.