using-sentry_skill

Overview

This skill shows how to integrate Sentry to capture exceptions, attach user and custom context, create performance spans, and emit structured logs and breadcrumbs. It provides practical TypeScript patterns for server and client Next.js code to improve observability and shorten debugging loops. The recipes focus on production-ready use: graceful error capture, meaningful traces, and clean user context handling.

How this skill works

The skill demonstrates manual exception capture with Sentry.captureException, setting persistent user/context using Sentry.setUser and tags/extra payloads, and adding breadcrumbs to record relevant user or system events. It also shows how to create synchronous and asynchronous performance spans via Sentry.startSpan and how to emit structured logs using Sentry.logger. Together these primitives feed Sentry’s Issues, Performance, and Logs views for faster root-cause analysis.

When to use it

• Track handled errors that should still be visible to Sentry instead of being silently swallowed
• Attach user identity and request-specific context for richer error and session correlation
• Instrument slow or critical operations with spans for performance monitoring
• Log structured events and warnings for operational visibility in the Logs view
• Add breadcrumbs for user actions to reproduce steps leading to an error

Best practices

• Capture errors deliberately where you handle them to avoid missing actionable failures
• Attach minimal, relevant context (user id, order id, feature flag) to avoid PII exposure
• Create spans around meaningful business operations, not every trivial function call
• Use Sentry.logger for structured, searchable logs instead of console.log in production
• Clear user context (Sentry.setUser(null)) on sign-out to prevent cross-session leakage

Example use cases

• Wrap checkout flow API calls with spans and add orderId in extra so slow payments are correlated to Sentry Performance
• Capture and tag known third-party failures to detect recurring integration issues
• Add breadcrumbs for auth events (login, MFA) so support teams can trace account-state problems
• Log payment warnings and errors with structured fields (orderId, amount, reason) to connect Logs and Issues
• Set user context at session start so errors automatically include user id and email for faster triage