@fghaffar/error-tracking

---
name: error-tracking
description: Add error tracking and performance monitoring to your project services. Use this skill when adding error handling, creating new controllers/routes, instrumenting background jobs, or tracking performance. Supports Sentry, Datadog, and other monitoring solutions. ALL ERRORS MUST BE CAPTURED - no exceptions.
---

# Error Tracking Integration Skill

## Purpose

This skill enforces comprehensive error tracking and performance monitoring across all services. Customize the patterns below for your specific monitoring solution (Sentry, Datadog, New Relic, etc.).

## When to Use This Skill

- Adding error handling to any code
- Creating new controllers or routes
- Instrumenting background jobs / cron tasks
- Tracking database or API performance
- Adding performance spans
- Handling async operation errors

## CRITICAL RULE

**ALL ERRORS MUST BE CAPTURED TO YOUR MONITORING SERVICE** - No exceptions. Never use console.error alone.

---

## Integration Patterns

### 1. Controller/Route Error Handling

#### Python (FastAPI)
```python
import logging
import sentry_sdk  # or your monitoring library

logger = logging.getLogger(__name__)

@router.get("/items/{item_id}")
async def get_item(item_id: str):
    try:
        result = await item_service.get_item(item_id)
        return result
    except ItemNotFoundError as e:
        logger.warning("Item not found", extra={"item_id": item_id})
        raise HTTPException(status_code=404, detail=str(e))
    except Exception as e:
        logger.error("Unexpected error", extra={"item_id": item_id, "error": str(e)}, exc_info=True)
        sentry_sdk.capture_exception(e)
        raise HTTPException(status_code=500, detail="Internal server error")
```

#### TypeScript (Express/Node.js)
```typescript
import * as Sentry from '@sentry/node';

router.get('/items/:id', async (req, res) => {
    try {
        const result = await itemService.getItem(req.params.id);
        res.json(result);
    } catch (error) {
        Sentry.captureException(error, {
            tags: { route: '/items/:id', method: 'GET' },
            extra: { itemId: req.params.id, userId: req.user?.id }
        });
        res.status(500).json({ error: 'Internal server error' });
    }
});
```

### 2. Service Layer Error Handling

```python
# Python
class ItemService:
    async def create_item(self, data: ItemCreate) -> Item:
        try:
            item = await self.repository.create(data)
            return item
        except IntegrityError as e:
            logger.warning("Duplicate item", extra={"data": data.model_dump()})
            raise DuplicateItemError("Item already exists")
        except Exception as e:
            logger.error("Failed to create item", extra={"error": str(e)}, exc_info=True)
            sentry_sdk.capture_exception(e)
            raise
```

```typescript
// TypeScript
class ItemService {
    async createItem(data: CreateItemDto): Promise<Item> {
        try {
            return await this.repository.create(data);
        } catch (error) {
            if (error instanceof DuplicateKeyError) {
                logger.warn('Duplicate item', { data });
                throw new ConflictError('Item already exists');
            }
            logger.error('Failed to create item', { error, data });
            Sentry.captureException(error);
            throw error;
        }
    }
}
```

### 3. Background Jobs / Cron Tasks

```typescript
#!/usr/bin/env node
// CRITICAL: Import monitoring first!
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 job logic here
            await processItems();
        } 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);
    });
```

```python
# Python (Celery)
import sentry_sdk
from celery import Celery

@celery_app.task(bind=True, max_retries=3)
def process_items(self):
    try:
        # Your task logic here
        result = do_processing()
        return result
    except TransientError as e:
        logger.warning("Transient error, retrying", extra={"error": str(e)})
        raise self.retry(exc=e, countdown=60)
    except Exception as e:
        logger.error("Task failed", extra={"error": str(e)}, exc_info=True)
        sentry_sdk.capture_exception(e)
        raise
```

### 4. Performance Monitoring

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

// Wrap slow operations with spans
const result = await Sentry.startSpan({
    name: 'database.query',
    op: 'db.query',
    attributes: {
        'db.operation': 'findMany',
        'db.table': 'items'
    }
}, async () => {
    return await prisma.item.findMany({ take: 100 });
});
```

```python
# Python with Sentry
import sentry_sdk

with sentry_sdk.start_span(op="db.query", description="Find items") as span:
    span.set_tag("db.table", "items")
    result = await db.items.find_many(limit=100)
```

---

## Error Levels

Use appropriate severity levels:

| Level | When to Use |
|-------|-------------|
| **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

Always include relevant context with errors:

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

Sentry.withScope((scope) => {
    // User context
    scope.setUser({ id: userId, email: userEmail });

    // Service/environment tags
    scope.setTag('service', 'api');
    scope.setTag('environment', process.env.NODE_ENV);

    // Operation-specific context
    scope.setContext('operation', {
        type: 'item.create',
        itemId: itemId,
        timestamp: new Date().toISOString()
    });

    Sentry.captureException(error);
});
```

```python
import sentry_sdk

with sentry_sdk.push_scope() as scope:
    scope.set_user({"id": user_id, "email": user_email})
    scope.set_tag("service", "api")
    scope.set_context("operation", {
        "type": "item.create",
        "item_id": item_id,
    })
    sentry_sdk.capture_exception(error)
```

---

## Configuration Templates

### Sentry (Node.js)

```typescript
// instrument.ts - Import this FIRST in your app
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: process.env.NODE_ENV === 'production' ? 0.1 : 1.0,
    profilesSampleRate: 0.1,
});
```

### Sentry (Python)

```python
# instrument.py - Import this FIRST in your app
import sentry_sdk
from sentry_sdk.integrations.fastapi import FastApiIntegration
from sentry_sdk.integrations.celery import CeleryIntegration

sentry_sdk.init(
    dsn=os.environ.get("SENTRY_DSN"),
    environment=os.environ.get("ENVIRONMENT", "development"),
    integrations=[
        FastApiIntegration(),
        CeleryIntegration(),
    ],
    traces_sample_rate=0.1 if os.environ.get("ENVIRONMENT") == "production" else 1.0,
)
```

### Environment Variables

```bash
# .env
SENTRY_DSN=https://your-dsn@sentry.io/project
ENVIRONMENT=development
```

---

## Common Mistakes to Avoid

| Don't | Do Instead |
|-------|------------|
| `console.error(error)` only | `logger.error() + captureException()` |
| Swallow errors silently | Always log + capture |
| Expose internal errors to clients | Return generic error messages |
| Generic error messages without context | Add meaningful context to all errors |
| Skip error handling in async operations | Always wrap async with try-catch |
| Forget to import instrument first | Import monitoring setup as first import |

---

## Implementation Checklist

When adding error tracking to new code:

- [ ] Imported monitoring library or helper
- [ ] All try/catch blocks capture to monitoring service
- [ ] Added meaningful context to errors
- [ ] Used appropriate error level (fatal/error/warning/info)
- [ ] No sensitive data in error messages
- [ ] Added performance tracking for slow operations
- [ ] Tested error handling paths
- [ ] For cron jobs: instrument file imported first

---

## Customization Notes

**Replace these for your project:**

1. **Monitoring Service**: Replace `Sentry` with your solution (Datadog, New Relic, etc.)
2. **Import Statements**: Update import paths for your project structure
3. **Environment Variables**: Match your configuration pattern
4. **Service Names**: Use your actual service names in tags
5. **Framework Integrations**: Add integrations for your frameworks

---

## Related Skills

- **backend-dev-guidelines** - General backend patterns
- **frontend-dev-guidelines** - Frontend error boundaries
- **skill-developer** - Creating monitoring-specific skills