your project Sentry Integration Skill

What Is This Skill?

The "your project Sentry Integration Skill" (Skill ID: error-tracking) is a productivity enhancement for the Happycapy Skills platform that enforces best practices for error tracking and performance monitoring using Sentry v8 across all your project services. By integrating this skill, you ensure that all exceptions, workflow errors, and performance issues within your project are automatically and consistently captured by Sentry, providing real-time visibility into your application's health. This integration is designed to be comprehensive and non-optional, making Sentry the central mechanism for error reporting and monitoring throughout your codebase.

The skill is sourced from an open repository (see source) and is structured to be easily added to any service, controller, cron job, or database interaction. Its strict mandate is that all errors must be captured by Sentry-never by console logging alone-ensuring that critical issues never go unnoticed.

Why Use It?

Modern software projects demand robust error tracking and performance monitoring to maintain reliability and user trust. Ad hoc logging or inconsistent exception handling can lead to missed issues, slow incident response, and a lack of actionable insights during debugging. The "your project Sentry Integration Skill" solves these problems by:

• Standardizing error tracking across all services and components
• Providing full-stack visibility into runtime errors and performance bottlenecks
• Enabling faster root cause analysis with contextual error data
• Reducing the risk of silent failures by enforcing Sentry capture as a non-negotiable rule
• Facilitating proactive performance optimization through integrated span tracking

By integrating this skill, your team benefits from a unified error monitoring strategy, leading to higher code quality, reduced downtime, and a more maintainable codebase.

How to Use It

1. Integrate Sentry v8 in Your

Service

First, ensure that your service is initialized with Sentry v8 according to the skill’s setup guidelines. Typically, this involves importing Sentry and initializing it with your project’s DSN and environment configuration.

import * as Sentry from '@sentry/node';

Sentry.init({
    dsn: process.env.SENTRY_DSN,
    environment: process.env.NODE_ENV,
    tracesSampleRate: 1.0, // Enable performance monitoring
});

2. Error Handling in

Controllers

All controllers should extend a common BaseController that implements required error handling logic. Instead of using console.error, use the controller's error handling method so all exceptions are reported to Sentry.

// CORRECT: Use BaseController for error handling
import { BaseController } from '../controllers/BaseController';

export class MyController extends BaseController {
    async myMethod() {
        try {
            // Business logic here
        } catch (error) {
            this.handleError(error, 'myMethod'); // Captured by Sentry
        }
    }
}

Do not use console.error or custom loggers for error reporting. All error capture must go through Sentry.

3. Instrumenting Cron

Jobs

Cron jobs and background processors must also be instrumented to capture errors and performance spans.

import * as Sentry from '@sentry/node';

async function runJob() {
    const transaction = Sentry.startTransaction({ name: 'cron:dailyReport' });
    try {
        // Cron job logic
    } catch (err) {
        Sentry.captureException(err);
    } finally {
        transaction.finish();
    }
}

4. Tracking Database

Performance

Wrap database queries with Sentry performance spans for visibility into query times and errors.

const span = Sentry.startSpan({ op: 'db.query', description: 'SELECT * FROM users' });
try {
    await db.query('SELECT * FROM users');
} catch (error) {
    Sentry.captureException(error);
} finally {
    span.end();
}

5. Adding Performance

Spans

Custom logic such as external API calls or complex workflows should be wrapped in Sentry spans to monitor latency and execution details.

const span = Sentry.startSpan({ op: 'external.api', description: 'Fetch user data' });
try {
    const data = await fetchUserData();
} catch (error) {
    Sentry.captureException(error);
} finally {
    span.end();
}

When to Use It

Leverage this skill in the following scenarios:

• Whenever you add error handling to any code path
• When creating new controllers, routes, or endpoints
• While instrumenting cron jobs, background workers, or scheduled tasks
• When tracking database performance or adding new queries
• While adding performance spans to monitor execution time
• Anytime you handle workflow errors, exceptions, or unexpected states

In summary: If your code can fail or slow down, it should be tracked by Sentry using the patterns enforced by this skill.

Important Notes

• Strict Rule: ALL errors must be captured to Sentry. Never use console.error or ignore exceptions. This is mandatory for every service, route, and job.
• Code Review: Any code submitted without proper Sentry instrumentation should be considered incomplete and flagged in code review.
• Skill Status: As of the latest update, the Form Service is fully integrated with Sentry v8, including all workflow errors and queue processors. The Email Service is partially integrated (6/22 tasks complete) with 189 legacy error logger calls pending migration.
• Consistency: Always use the provided base classes and patterns for error and performance tracking. Do not create ad hoc solutions.
• Documentation: Refer to the source repository for specific integration details and updates.

By following these practices and utilizing the "your project Sentry Integration Skill," your project will maintain a high standard of reliability and observability, enabling better incident response and continuous improvement.