Error Tracking

Enforce bulletproof Sentry error tracking across all your services

✨ The solution you've been looking for

Verified

Tested and verified by our team

8390 Stars

Add Sentry v8 error tracking and performance monitoring to your project services. Use this skill when adding error handling, creating new controllers, instrumenting cron jobs, or tracking database performance. ALL ERRORS MUST BE CAPTURED TO SENTRY - no exceptions.

error-tracking sentry monitoring performance debugging logging microservices observability

Repository

See It In Action

Interactive preview & real-world examples

Live Demo

AI Conversation Simulator

See how users interact with this skill

User Prompt

I'm creating a new user registration controller. Help me add proper Sentry error tracking following best practices.

Skill Processing

Analyzing request...

Agent Response

Complete controller implementation with BaseController inheritance, proper try-catch blocks, and Sentry error capture with meaningful context

Quick Start (3 Steps)

Get up and running in minutes

Install

claude-code skill install error-tracking

claude-code skill install error-tracking

Config

First Trigger

@error-tracking help

Commands

Command	Description	Required Args
@error-tracking adding-error-handling-to-new-controller	Implement proper error tracking when creating new API endpoints or controllers	None
@error-tracking instrumenting-cron-jobs	Add comprehensive error tracking and performance monitoring to background jobs	None
@error-tracking database-performance-monitoring	Track slow queries and detect N+1 query problems with automatic Sentry reporting	None

Typical Use Cases

Adding Error Handling to New Controller

Implement proper error tracking when creating new API endpoints or controllers

Instrumenting Cron Jobs

Add comprehensive error tracking and performance monitoring to background jobs

Database Performance Monitoring

Track slow queries and detect N+1 query problems with automatic Sentry reporting

Overview

your project Sentry Integration Skill

Purpose

This skill enforces comprehensive Sentry error tracking and performance monitoring across all your project services following Sentry v8 patterns.

When to Use This Skill

Adding error handling to any code
Creating new controllers or routes
Instrumenting cron jobs
Tracking database performance
Adding performance spans
Handling workflow errors

🚨 CRITICAL RULE

ALL ERRORS MUST BE CAPTURED TO SENTRY - No exceptions. Never use console.error alone.

Current Status

Form Service ✅ Complete

Sentry v8 fully integrated
All workflow errors tracked
SystemActionQueueProcessor instrumented
Test endpoints available

Email Service 🟡 In Progress

Phase 1-2 complete (6/22 tasks)
189 ErrorLogger.log() calls remaining

Sentry Integration Patterns

1. Controller Error Handling

 1// ✅ CORRECT - Use BaseController
 2import { BaseController } from '../controllers/BaseController';
 3
 4export class MyController extends BaseController {
 5    async myMethod() {
 6        try {
 7            // ... your code
 8        } catch (error) {
 9            this.handleError(error, 'myMethod'); // Automatically sends to Sentry
10        }
11    }
12}

2. Route Error Handling (Without BaseController)

 1import * as Sentry from '@sentry/node';
 2
 3router.get('/route', async (req, res) => {
 4    try {
 5        // ... your code
 6    } catch (error) {
 7        Sentry.captureException(error, {
 8            tags: { route: '/route', method: 'GET' },
 9            extra: { userId: req.user?.id }
10        });
11        res.status(500).json({ error: 'Internal server error' });
12    }
13});

3. Workflow Error Handling

 1import { WorkflowSentryHelper } from '../workflow/utils/sentryHelper';
 2
 3// ✅ CORRECT - Use WorkflowSentryHelper
 4WorkflowSentryHelper.captureWorkflowError(error, {
 5    workflowCode: 'DHS_CLOSEOUT',
 6    instanceId: 123,
 7    stepId: 456,
 8    userId: 'user-123',
 9    operation: 'stepCompletion',
10    metadata: { additionalInfo: 'value' }
11});

4. Cron Jobs (MANDATORY Pattern)

 1#!/usr/bin/env node
 2// FIRST LINE after shebang - CRITICAL!
 3import '../instrument';
 4import * as Sentry from '@sentry/node';
 5
 6async function main() {
 7    return await Sentry.startSpan({
 8        name: 'cron.job-name',
 9        op: 'cron',
10        attributes: {
11            'cron.job': 'job-name',
12            'cron.startTime': new Date().toISOString(),
13        }
14    }, async () => {
15        try {
16            // Your cron job logic
17        } catch (error) {
18            Sentry.captureException(error, {
19                tags: {
20                    'cron.job': 'job-name',
21                    'error.type': 'execution_error'
22                }
23            });
24            console.error('[Job] Error:', error);
25            process.exit(1);
26        }
27    });
28}
29
30main()
31    .then(() => {
32        console.log('[Job] Completed successfully');
33        process.exit(0);
34    })
35    .catch((error) => {
36        console.error('[Job] Fatal error:', error);
37        process.exit(1);
38    });

5. Database Performance Monitoring

 1import { DatabasePerformanceMonitor } from '../utils/databasePerformance';
 2
 3// ✅ CORRECT - Wrap database operations
 4const result = await DatabasePerformanceMonitor.withPerformanceTracking(
 5    'findMany',
 6    'UserProfile',
 7    async () => {
 8        return await PrismaService.main.userProfile.findMany({
 9            take: 5,
10        });
11    }
12);

6. Async Operations with Spans

 1import * as Sentry from '@sentry/node';
 2
 3const result = await Sentry.startSpan({
 4    name: 'operation.name',
 5    op: 'operation.type',
 6    attributes: {
 7        'custom.attribute': 'value'
 8    }
 9}, async () => {
10    // Your async operation
11    return await someAsyncOperation();
12});

Error Levels

Use appropriate severity levels:

fatal: System is unusable (database down, critical service failure)
error: Operation failed, needs immediate attention
warning: Recoverable issues, degraded performance
info: Informational messages, successful operations
debug: Detailed debugging information (dev only)

Required Context

 1import * as Sentry from '@sentry/node';
 2
 3Sentry.withScope((scope) => {
 4    // ALWAYS include these if available
 5    scope.setUser({ id: userId });
 6    scope.setTag('service', 'form'); // or 'email', 'users', etc.
 7    scope.setTag('environment', process.env.NODE_ENV);
 8
 9    // Add operation-specific context
10    scope.setContext('operation', {
11        type: 'workflow.start',
12        workflowCode: 'DHS_CLOSEOUT',
13        entityId: 123
14    });
15
16    Sentry.captureException(error);
17});

Service-Specific Integration

Form Service

Location: ./blog-api/src/instrument.ts

 1import * as Sentry from '@sentry/node';
 2import { nodeProfilingIntegration } from '@sentry/profiling-node';
 3
 4Sentry.init({
 5    dsn: process.env.SENTRY_DSN,
 6    environment: process.env.NODE_ENV || 'development',
 7    integrations: [
 8        nodeProfilingIntegration(),
 9    ],
10    tracesSampleRate: 0.1,
11    profilesSampleRate: 0.1,
12});

Key Helpers:

WorkflowSentryHelper - Workflow-specific errors
DatabasePerformanceMonitor - DB query tracking
BaseController - Controller error handling

Email Service

Location: ./notifications/src/instrument.ts

 1import * as Sentry from '@sentry/node';
 2import { nodeProfilingIntegration } from '@sentry/profiling-node';
 3
 4Sentry.init({
 5    dsn: process.env.SENTRY_DSN,
 6    environment: process.env.NODE_ENV || 'development',
 7    integrations: [
 8        nodeProfilingIntegration(),
 9    ],
10    tracesSampleRate: 0.1,
11    profilesSampleRate: 0.1,
12});

Key Helpers:

EmailSentryHelper - Email-specific errors
BaseController - Controller error handling

Configuration (config.ini)

 1[sentry]
 2dsn = your-sentry-dsn
 3environment = development
 4tracesSampleRate = 0.1
 5profilesSampleRate = 0.1
 6
 7[databaseMonitoring]
 8enableDbTracing = true
 9slowQueryThreshold = 100
10logDbQueries = false
11dbErrorCapture = true
12enableN1Detection = true

Testing Sentry Integration

Form Service Test Endpoints

 1# Test basic error capture
 2curl http://localhost:3002/blog-api/api/sentry/test-error
 3
 4# Test workflow error
 5curl http://localhost:3002/blog-api/api/sentry/test-workflow-error
 6
 7# Test database performance
 8curl http://localhost:3002/blog-api/api/sentry/test-database-performance
 9
10# Test error boundary
11curl http://localhost:3002/blog-api/api/sentry/test-error-boundary

Email Service Test Endpoints

1# Test basic error capture
2curl http://localhost:3003/notifications/api/sentry/test-error
3
4# Test email-specific error
5curl http://localhost:3003/notifications/api/sentry/test-email-error
6
7# Test performance tracking
8curl http://localhost:3003/notifications/api/sentry/test-performance

Performance Monitoring

Requirements

All API endpoints must have transaction tracking
Database queries > 100ms are automatically flagged
N+1 queries are detected and reported
Cron jobs must track execution time

Transaction Tracking

 1import * as Sentry from '@sentry/node';
 2
 3// Automatic transaction tracking for Express routes
 4app.use(Sentry.Handlers.requestHandler());
 5app.use(Sentry.Handlers.tracingHandler());
 6
 7// Manual transaction for custom operations
 8const transaction = Sentry.startTransaction({
 9    op: 'operation.type',
10    name: 'Operation Name',
11});
12
13try {
14    // Your operation
15} finally {
16    transaction.finish();
17}

Common Mistakes to Avoid

❌ NEVER use console.error without Sentry ❌ NEVER swallow errors silently ❌ NEVER expose sensitive data in error context ❌ NEVER use generic error messages without context ❌ NEVER skip error handling in async operations ❌ NEVER forget to import instrument.ts as first line in cron jobs

Implementation Checklist

When adding Sentry to new code:

Imported Sentry or appropriate helper
All try/catch blocks capture to Sentry
Added meaningful context to errors
Used appropriate error level
No sensitive data in error messages
Added performance tracking for slow operations
Tested error handling paths
For cron jobs: instrument.ts imported first

Key Files

Form Service

/blog-api/src/instrument.ts - Sentry initialization
/blog-api/src/workflow/utils/sentryHelper.ts - Workflow errors
/blog-api/src/utils/databasePerformance.ts - DB monitoring
/blog-api/src/controllers/BaseController.ts - Controller base

Email Service

/notifications/src/instrument.ts - Sentry initialization
/notifications/src/utils/EmailSentryHelper.ts - Email errors
/notifications/src/controllers/BaseController.ts - Controller base

Configuration

/blog-api/config.ini - Form service config
/notifications/config.ini - Email service config
/sentry.ini - Shared Sentry config

Documentation

Full implementation: /dev/active/email-sentry-integration/
Form service docs: /blog-api/docs/sentry-integration.md
Email service docs: /notifications/docs/sentry-integration.md

Use database-verification before database operations
Use workflow-builder for workflow error context
Use database-scripts for database error handling

What Users Are Saying

Real feedback from the community

Environment Matrix

Dependencies

@sentry/node v8+

@sentry/profiling-node

Node.js 16+

Express.js (for automatic request tracking)

Prisma (for database monitoring features)

Framework Support

Express.js ✓ (recommended) Prisma ✓ (recommended) Custom cron jobs ✓ Workflow systems ✓

Error Tracking

See It In Action

AI Conversation Simulator

Quick Start (3 Steps)

Install

Config

First Trigger

Commands

Typical Use Cases

Adding Error Handling to New Controller

Instrumenting Cron Jobs

Database Performance Monitoring

Overview

your project Sentry Integration Skill

Purpose

When to Use This Skill

🚨 CRITICAL RULE

Current Status

Form Service ✅ Complete

Email Service 🟡 In Progress

Sentry Integration Patterns

1. Controller Error Handling

2. Route Error Handling (Without BaseController)

3. Workflow Error Handling

4. Cron Jobs (MANDATORY Pattern)

5. Database Performance Monitoring

6. Async Operations with Spans

Error Levels

Required Context

Service-Specific Integration

Form Service

Email Service

Configuration (config.ini)

Testing Sentry Integration

Form Service Test Endpoints

Email Service Test Endpoints

Performance Monitoring

Requirements

Transaction Tracking

Common Mistakes to Avoid

Implementation Checklist

Key Files

Form Service

Email Service

Configuration

Documentation

Related Skills

What Users Are Saying

Environment Matrix

Dependencies

Framework Support

Context Window

Security & Privacy

Information

Related Skills

Error Tracking

Distributed Tracing

Distributed Tracing