Sentry Server Monitoring Skill

Purpose

This skill enforces the project server-side Sentry monitoring conventions automatically during error tracking implementation. It ensures consistent patterns for context setting, breadcrumb categories, error capture, performance spans, and middleware integration.

Note: For client-side/front-end Sentry patterns, use the sentry-client skill instead.

Activation

This skill activates when working on server-side code:

• Creating or modifying server actions in src/lib/actions/
• Implementing error handling in facades (src/lib/facades/)
• Setting up performance monitoring spans in server code
• Adding breadcrumbs in server-side operations
• Working with middleware (src/middleware.ts, src/lib/middleware/)
• API routes (src/app/api/)
• Instrumentation files (src/instrumentation.ts)

Workflow

1. Detect server-side Sentry work (imports from @sentry/nextjs in server files)
2. Load references/Sentry-Server-Conventions.md
3. Generate/modify code following all conventions
4. Scan for violations of Sentry patterns
5. Auto-fix all violations (no permission needed)
6. Report fixes applied

Key Patterns

Server Actions

• Set context at the start with Sentry.setContext(SENTRY_CONTEXTS.*, {...})
• Add breadcrumbs for successful operations
• Log non-critical failures (e.g., cache invalidation) with level: 'warning'

Facades

• Add breadcrumbs for non-blocking operations (Cloudinary cleanup)
• Capture non-critical exceptions without failing the operation

Middleware

• Use Sentry.withScope and Sentry.startSpan for performance tracking
• Set tags and context within the scope

Instrumentation

• Export onRequestError = Sentry.captureRequestError for RSC error capture

Constants (Always Use)

Constant	Import Path	Purpose
SENTRY_CONTEXTS	@/lib/constants/sentry	Context names for setContext
SENTRY_BREADCRUMB_CATEGORIES	@/lib/constants/sentry	Breadcrumb category values
SENTRY_LEVELS	@/lib/constants/sentry	Breadcrumb level values
SENTRY_TAGS	@/lib/constants/sentry	Tag names for setTag
SENTRY_OPERATIONS	@/lib/constants/sentry	Operation names for spans

Helper Utilities (Recommended)

Import from @/lib/utils/sentry-server/breadcrumbs.server:

For Server Actions

Function	Purpose
withActionErrorHandling()	Wrap action with automatic breadcrumbs + error handling
withActionBreadcrumbs()	Wrap action with breadcrumbs only (no error handling)
trackActionEntry()	Track action operation start
trackActionSuccess()	Track action success with optional result data
trackActionWarning()	Track action warning for partial failures
trackCacheInvalidation()	Track cache invalidation with automatic warning on failure
setActionContext()	Set Sentry context with type-safe keys

For Facades

Function	Purpose
withFacadeBreadcrumbs()	Wrap facade method with automatic breadcrumbs
trackFacadeEntry()	Track facade operation start
trackFacadeSuccess()	Track facade success with optional result data
trackFacadeWarning()	Track facade warning for partial failures
trackFacadeError()	Track facade error
facadeBreadcrumb()	Add a simple breadcrumb for facade operations
captureFacadeWarning()	Capture non-critical exception with warning level and tags

See references/Sentry-Server-Conventions.md for complete documentation with examples.

Usage Pattern Reference

Use Case	Primary Method	Level
Action start	Sentry.setContext	N/A
Successful operation	Sentry.addBreadcrumb	INFO
Non-critical failure	Sentry.captureException	warning
Critical failure	Let error propagate	error
Performance tracking	Sentry.startSpan	N/A

File Patterns

This skill applies to:

• src/lib/actions/**/*.ts
• src/lib/facades/**/*.ts
• src/lib/middleware/**/*.ts
• src/middleware.ts
• src/app/api/**/*.ts
• src/instrumentation.ts
• sentry.server.config.ts
• sentry.edge.config.ts

References

• references/Sentry-Server-Conventions.md - Complete server-side Sentry monitoring conventions