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

Detect server-side Sentry work (imports from @sentry/nextjs in server files)
Load references/Sentry-Server-Conventions.md
Generate/modify code following all conventions
Scan for violations of Sentry patterns
Auto-fix all violations (no permission needed)
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