Agent skill

Sentry v8 Error Tracking

by diet103 in diet103/claude-code-infrastructure-showcase

Enforces that every error in a service is captured to Sentry v8, with patterns for controllers, routes, cron jobs and database performance spans instead of console logging alone.

MITAuto-check: notesBackend & APIs

Install Sentry v8 Error Tracking

skills CLI
$ npx skills add diet103/claude-code-infrastructure-showcase --skill error-tracking -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install diet103/claude-code-infrastructure-showcase error-tracking --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/diet103/claude-code-infrastructure-showcase.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/error-tracking .claude/skills/error-tracking && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
error-tracking
GitHub stars
10k
Used in
2 other repos
Token cost
~2.3k tokens
SKILL.md length
442 words
Files
1
Skills in repo
5
Repo updated
First seen
Licence
MIT

At a glance

Enforces that every error in a service is captured to Sentry v8, with patterns for controllers, routes, cron jobs and database performance spans instead of console logging alone.

  • Works in 6 steps: Controller Error Handling → Route Error Handling (Without… → Workflow Error Handling → …
  • Adding error handling to a new or existing route or controller
  • SKILL.md covers Purpose, When to Use This Skill, 🚨 CRITICAL RULE and Current Status, plus 10 more sections
  • Calls curl

What it does

The skill states a single non-negotiable rule: every error must be captured to Sentry, never left as a console.error call alone, and applies whenever error handling is added, a new controller or route is created, a cron job is instrumented, or database performance needs tracking. It shows the pattern for controller-level error handling through a BaseController helper, and a separate pattern for routes that do not go through that base class, importing the Sentry Node SDK directly.

A further example shows a domain-specific Sentry helper used for workflow error handling, built in an earlier production project, so a team can build an equivalent helper for its own domain and call it the same way at each call site. The skill notes one example service as a complete reference implementation, with Sentry v8 fully integrated, all workflow errors tracked, background job processors instrumented and test endpoints available to check the integration.

When your agent uses it

  • Adding error handling to a new or existing route or controller
  • Instrumenting a cron job or background processor for error tracking
  • Adding a performance span around a database operation

Example prompts

  • “Add Sentry error tracking to this new controller using BaseController.”
  • “Instrument this cron job so its errors and performance are tracked in Sentry.”
  • “This route only logs errors to the console. Wire it up to Sentry properly.”

Requirements

  • Sentry v8 SDK (@sentry/node) configured for the service

Workflow steps

6 steps, taken from the step headings in SKILL.md.

  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

What it can do on your machine

Read from SKILL.md and the folder at commit 07f75ce. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • curl

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use curl, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Sentry v8 Error Tracking loads about 2.3k tokens when it runs. Until then it costs about 68 tokens; SKILL.md has 442 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~68
When it runs · the whole SKILL.md, loaded when a task matches
~2.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NoteMentions a .env fileSKILL.md:361
    - `config.ini` or `.env` - Sentry DSN and settings

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from diet103/claude-code-infrastructure-showcase at commit 07f75ce, republished under its MIT licence (© diet103). 442 words, ~2,346 tokens.

Download SKILL.mdSave it as .claude/skills/error-tracking/SKILL.md (or your agent's skills folder).
name
error-tracking
description
Add Sentry v8 error tracking and performance monitoring to your 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.

Sentry Integration Skill

Purpose

This skill enforces comprehensive Sentry error tracking and performance monitoring across all 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

Example: API Service ✅ Complete
  • Sentry v8 fully integrated
  • All workflow errors tracked
  • Background job processors instrumented
  • Test endpoints available

Sentry Integration Patterns

1. Controller Error Handling
typescript
// ✅ CORRECT - Use BaseController
import { BaseController } from '../controllers/BaseController';

export class MyController extends BaseController {
    async myMethod() {
        try {
            // ... your code
        } catch (error) {
            this.handleError(error, 'myMethod'); // Automatically sends to Sentry
        }
    }
}
2. Route Error Handling (Without BaseController)
typescript
import * as Sentry from '@sentry/node';

router.get('/route', async (req, res) => {
    try {
        // ... your code
    } catch (error) {
        Sentry.captureException(error, {
            tags: { route: '/route', method: 'GET' },
            extra: { userId: req.user?.id }
        });
        res.status(500).json({ error: 'Internal server error' });
    }
});
3. Workflow Error Handling

Example of a domain-specific Sentry helper from the original production project. If you build a helper like this for your domain, the call site looks like:

typescript
import { WorkflowSentryHelper } from '../workflow/utils/sentryHelper';

WorkflowSentryHelper.captureWorkflowError(error, {
    workflowCode: 'INVOICE_APPROVAL',
    instanceId: 123,
    stepId: 456,
    userId: 'user-123',
    operation: 'stepCompletion',
    metadata: { additionalInfo: 'value' }
});

Without a helper, plain Sentry works everywhere:

typescript
Sentry.captureException(error, {
    tags: { operation: 'stepCompletion' },
    extra: { workflowCode: 'INVOICE_APPROVAL', instanceId: 123, userId: 'user-123' }
});
4. Cron Jobs (MANDATORY Pattern)
typescript
#!/usr/bin/env node
// FIRST LINE after shebang - CRITICAL!
import '../instrument';
import * as Sentry from '@sentry/node';

async function main() {
    return await Sentry.startSpan({
        name: 'cron.job-name',
        op: 'cron',
        attributes: {
            'cron.job': 'job-name',
            'cron.startTime': new Date().toISOString(),
        }
    }, async () => {
        try {
            // Your cron job logic
        } catch (error) {
            Sentry.captureException(error, {
                tags: {
                    'cron.job': 'job-name',
                    'error.type': 'execution_error'
                }
            });
            console.error('[Job] Error:', error);
            process.exit(1);
        }
    });
}

main()
    .then(() => {
        console.log('[Job] Completed successfully');
        process.exit(0);
    })
    .catch((error) => {
        console.error('[Job] Fatal error:', error);
        process.exit(1);
    });
5. Database Performance Monitoring

Example from the original production project - a small helper that wraps DB calls in Sentry spans. Adapt to your codebase:

typescript
import { DatabasePerformanceMonitor } from '../utils/databasePerformance';

const result = await DatabasePerformanceMonitor.withPerformanceTracking(
    'findMany',
    'UserProfile',
    async () => {
        return await PrismaService.main.userProfile.findMany({
            take: 5,
        });
    }
);

The universally-available equivalent is a direct Sentry span:

typescript
const result = await Sentry.startSpan({
    name: 'db.userProfile.findMany',
    op: 'db.query',
    attributes: { 'db.model': 'UserProfile', 'db.operation': 'findMany' }
}, async () => {
    return await prisma.userProfile.findMany({ take: 5 });
});
6. Async Operations with Spans
typescript
import * as Sentry from '@sentry/node';

const result = await Sentry.startSpan({
    name: 'operation.name',
    op: 'operation.type',
    attributes: {
        'custom.attribute': 'value'
    }
}, async () => {
    // Your async operation
    return await someAsyncOperation();
});

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

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

Sentry.withScope((scope) => {
    // ALWAYS include these if available
    scope.setUser({ id: userId });
    scope.setTag('service', 'api'); // your service name
    scope.setTag('environment', process.env.NODE_ENV);

    // Add operation-specific context
    scope.setContext('operation', {
        type: 'workflow.start',
        workflowCode: 'INVOICE_APPROVAL',
        entityId: 123
    });

    Sentry.captureException(error);
});

Service Integration Examples

API Service (Example)

Location: ./api/src/instrument.ts

typescript
import * as Sentry from '@sentry/node';
import { nodeProfilingIntegration } from '@sentry/profiling-node';

Sentry.init({
    dsn: process.env.SENTRY_DSN,
    environment: process.env.NODE_ENV || 'development',
    integrations: [
        nodeProfilingIntegration(),
    ],
    tracesSampleRate: 0.1,
    profilesSampleRate: 0.1,
});

Key Helpers:

  • Custom Sentry helpers for domain-specific errors
  • DatabasePerformanceMonitor - DB query tracking
  • BaseController - Controller error handling
Notifications Service (Example)

Location: ./notifications/src/instrument.ts

typescript
import * as Sentry from '@sentry/node';
import { nodeProfilingIntegration } from '@sentry/profiling-node';

Sentry.init({
    dsn: process.env.SENTRY_DSN,
    environment: process.env.NODE_ENV || 'development',
    integrations: [
        nodeProfilingIntegration(),
    ],
    tracesSampleRate: 0.1,
    profilesSampleRate: 0.1,
});

Key Helpers:

  • Service-specific Sentry helpers for domain errors
  • BaseController - Controller error handling

Configuration (config.ini)

ini
[sentry]
dsn = your-sentry-dsn
environment = development
tracesSampleRate = 0.1
profilesSampleRate = 0.1

[databaseMonitoring]
enableDbTracing = true
slowQueryThreshold = 100
logDbQueries = false
dbErrorCapture = true
enableN1Detection = true

Testing Sentry Integration

Show full SKILL.md (180 more words)Show less
Example Test Endpoints
bash
# Test basic error capture
curl http://localhost:3000/api/sentry/test-error

# Test performance tracking
curl http://localhost:3000/api/sentry/test-performance

# Test database performance
curl http://localhost:3000/api/sentry/test-database-performance

Create test endpoints in your services to verify Sentry integration works end-to-end.

Performance Monitoring

Requirements
  1. All API endpoints must have transaction tracking
  2. Database queries > 100ms are automatically flagged
  3. N+1 queries are detected and reported
  4. Cron jobs must track execution time
Transaction Tracking
typescript
import * as Sentry from '@sentry/node';

// Automatic transaction tracking for Express routes
app.use(Sentry.Handlers.requestHandler());
app.use(Sentry.Handlers.tracingHandler());

// Manual transaction for custom operations
const transaction = Sentry.startTransaction({
    op: 'operation.type',
    name: 'Operation Name',
});

try {
    // Your operation
} finally {
    transaction.finish();
}

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 (Typical Structure)

Per Service
  • src/instrument.ts - Sentry initialization (imported first)
  • src/utils/sentryHelper.ts - Domain-specific error helpers
  • src/utils/databasePerformance.ts - DB monitoring
  • src/controllers/BaseController.ts - Controller base with Sentry
Configuration
  • config.ini or .env - Sentry DSN and settings
  • sentry.ini - Shared Sentry config (optional)

© diet103, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/error-tracking of diet103/claude-code-infrastructure-showcase.

Open the folder on GitHubat commit 07f75ce

Used in 2 other repositories

We found 9 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 2 other GitHub owners. This page covers the copy in diet103/claude-code-infrastructure-showcase, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Sentry v8 Error Tracking next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Sentry v8 Error Tracking compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Sentry v8 Error Tracking this skilldiet103/claude-code-infrastructure-showcase10k2 repos~2.3kAutomated safety check: NotesMIT
Logging Observabilitygetsentry/toolkit917—~2.6kAutomated safety check: PassCustom licence
Error HandlerEliasOulkadi/shokunin114—~3.6kAutomated safety check: NotesMIT
Logging and Error Reporting for Warpwarpdotdev/warp65k1 repos~5.6kAutomated safety check: PassAGPL-3.0
Error Handlingericrisco/rsc-harness156—~3.2kAutomated safety check: PassMIT
Inngest Durable FunctionsAsymmetric-al/core382—~4kAutomated safety check: PassAGPL-3.0

Similar skills

  • Logging Observability

    getsentry/toolkit

    Official

    Review code for correct logging and error handling patterns.

    917 GitHub stars~2.6k tokensUpdated today
    DevOps & CloudAuto-check passed
  • Error Handler

    EliasOulkadi/shokunin

    Design error handling, structured logging, and observability with OpenTelemetry (traces, metrics, logs), error classification, recovery patterns (retry with jitter, circuit breaker, bulkhead…

    114 GitHub stars~3.6k tokensUpdated 2 days ago
    DevOps & CloudAuto-check: notes
  • Guides log level choices and when to raise a structured Sentry event instead of a plain log line in the Warp Rust codebase, keeping secrets out of logs.

    65k GitHub starsUsed in 1 repo~5.6k tokens
    DevelopmentAuto-check passed
  • Error Handling

    ericrisco/rsc-harness

    A skill your agent uses when designing the reaction to a class of failures — typed error taxonomies, retry/backoff/timeout policy, circuit breakers, React/Next error boundaries, and the user-message…

    156 GitHub stars~3.2k tokensUpdated yesterday
    Backend & APIsAuto-check passed
  • Inngest Durable Functions

    Asymmetric-al/core

    A skill your agent uses when building functions that must survive process crashes, retry automatically on failure, run on a schedule, react to events, or maintain state across infrastructure…

    382 GitHub stars~4k tokensUpdated today
    Backend & APIsAuto-check passed
  • Sentry Miniapp SDK

    lizhiyao/sentry-miniapp

    Full Sentry SDK setup for Mini Programs — error monitoring, tracing, offline cache, source maps.

    686 GitHub stars~5k tokensUpdated yesterday
    DevOps & CloudAuto-check passed

More from diet103/claude-code-infrastructure-showcase

  • Claude Code Skill Developer Guide

    diet103/claude-code-infrastructure-showcase

    A guide to creating and managing Claude Code skills with auto-activation: skill-rules.json triggers, hooks, enforcement levels, YAML frontmatter and progressive disclosure.

    10k GitHub starsUsed in 10 repos~3.5k tokens
    Auto-check passed
  • Node Backend Development Guidelines

    diet103/claude-code-infrastructure-showcase

    Sets layered architecture and coding rules for Node.js, Express and TypeScript microservices, covering routes, controllers, services, repositories, Prisma, Sentry and Zod.

    10k GitHub starsUsed in 2 repos~2k tokens
    Auto-check passed
  • React Frontend Development Guidelines

    diet103/claude-code-infrastructure-showcase

    Guidelines for React 18 and TypeScript apps covering Suspense data fetching, lazy loading, feature folders, MUI v7 styling, TanStack Router and performance.

    10k GitHub starsUsed in 2 repos~2.9k tokens
    Auto-check passed
  • Verify Setup Health Check

    diet103/claude-code-infrastructure-showcase

    Run the infrastructure health check and fix anything that fails

    10k GitHub stars~363 tokensUpdated 2 mo ago
    Auto-check passed

Works with

Questions about Sentry v8 Error Tracking

What does Sentry v8 Error Tracking do?

Enforces that every error in a service is captured to Sentry v8, with patterns for controllers, routes, cron jobs and database performance spans instead of console logging alone. error call alone, and applies whenever error handling is added, a new controller or route is created, a cron job is instrumented, or database performance needs tracking. It shows the pattern for controller-level error handling through a BaseController helper, and a separate pattern for routes that do not go through that base class, importing the Sentry Node SDK directly.

When should I use Sentry v8 Error Tracking?

Sentry v8 Error Tracking fits situations like: adding error handling to a new or existing route or controller; instrumenting a cron job or background processor for error tracking; adding a performance span around a database operation.

How do I install Sentry v8 Error Tracking in Claude Code?

Run `npx skills add diet103/claude-code-infrastructure-showcase --skill error-tracking -a claude-code`. Or copy the skill folder (.agents/skills/error-tracking in diet103/claude-code-infrastructure-showcase) into .claude/skills/error-tracking in your project. Claude Code loads it when a task matches its description.

How do I install Sentry v8 Error Tracking in Codex?

Run `npx skills add diet103/claude-code-infrastructure-showcase --skill error-tracking -a codex`. Or copy the skill folder (.agents/skills/error-tracking in diet103/claude-code-infrastructure-showcase) into .agents/skills/error-tracking in your project. Codex loads it when a task matches its description.

Can I use Sentry v8 Error Tracking in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add diet103/claude-code-infrastructure-showcase --skill error-tracking -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/error-tracking, .gemini/skills/error-tracking, .github/skills/error-tracking and .opencode/skills/error-tracking in your project.

What does Sentry v8 Error Tracking need to run?

Going by SKILL.md and its folder, Sentry v8 Error Tracking needs the command-line tools its instructions call (curl). Our summary lists: Sentry v8 SDK (@sentry/node) configured for the service.

Does Sentry v8 Error Tracking access the network?

SKILL.md contains no URLs. Its commands use curl, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Sentry v8 Error Tracking safe to install?

Our automated static check of SKILL.md found notes only (mentions a .env file), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Sentry v8 Error Tracking use?

Sentry v8 Error Tracking is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Sentry v8 Error Tracking use?

About 2.3k tokens (SKILL.md is roughly 9.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Sentry v8 Error Tracking?

Skills that share tags, products or a category with Sentry v8 Error Tracking: Logging Observability (getsentry/toolkit, 917 stars), Error Handler (EliasOulkadi/shokunin, 114 stars), Logging and Error Reporting for Warp (warpdotdev/warp, 65k stars) and Error Handling (ericrisco/rsc-harness, 156 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Sentry v8 Error Tracking?

diet103 (a GitHub user) maintains it in diet103/claude-code-infrastructure-showcase, which has 10,030 GitHub stars. The repository holds 5 skills in this directory. The repository was last updated on July 13, 2026.

Source: diet103/claude-code-infrastructure-showcase on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.