sentry-server
在服务器操作、外观、中间件和API路由中实现错误跟踪、性能监控和面包屑日志记录时,强制执行Head Shakers服务器端Sentry监控约定。此技能确保上下文设置、面包屑类别、错误捕获和性能跨度的一致模式。
📖 中文导读:在服务器操作、外观、中间件和API路由中实现错误跟踪、性能监控和面包屑日志记录时,强制执行Head Shakers服务器端Sentry监控约定。此技能确保上下文设置、面包屑类别、错误捕获和性能跨度的一致模式。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: sentry-server description: Enforces project server-side Sentry monitoring conventions when implementing error tracking, performance monitoring, and breadcrumb logging in server actions, facades, middleware, and API routes. This skill ensures consistent patterns for context setting, breadcrumb categories, error capture, and performance spans.
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/nextjsin 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.withScopeandSentry.startSpanfor performance tracking - Set tags and context within the scope
Instrumentation
- Export
onRequestError = Sentry.captureRequestErrorfor 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/**/*.tssrc/lib/facades/**/*.tssrc/lib/middleware/**/*.tssrc/middleware.tssrc/app/api/**/*.tssrc/instrumentation.tssentry.server.config.tssentry.edge.config.ts
References
references/Sentry-Server-Conventions.md- Complete server-side Sentry monitoring conventions