error-tracking

プロジェクトの Sentry 統合スキル

目的

このスキルは、Sentry v8 のパターンに従って、プロジェクト内のすべてのサービスで包括的な Sentry エラー追跡とパフォーマンス監視を徹底します。

このスキルを使用する場面

• コードにエラー処理を追加するとき
• 新しいコントローラーやルートを作成するとき
• cron ジョブを計測するとき
• データベースのパフォーマンスを追跡するとき
• パフォーマンススパンを追加するとき
• ワークフローのエラーを処理するとき

🚨 重要なルール

すべてのエラーを Sentry に記録する必要があります。例外はありません。console.error だけを使用してはいけません。

現在の状況

Form Service ✅ 完了

• Sentry v8 の統合が完了
• すべてのワークフローエラーを追跡
• SystemActionQueueProcessor を計測済み
• テスト用エンドポイントを利用可能

Email Service 🟡 進行中

• フェーズ 1～2 が完了（6/22 タスク）
• ErrorLogger.log() の呼び出しが 189 件残存

Sentry 統合パターン

1. コントローラーのエラー処理

// ✅ 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. ルートのエラー処理（BaseController を使用しない場合）

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. ワークフローのエラー処理

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

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

4. cron ジョブ（必須パターン）

#!/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. データベースのパフォーマンス監視

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

// ✅ CORRECT - Wrap database operations
const result = await DatabasePerformanceMonitor.withPerformanceTracking(
    'findMany',
    'UserProfile',
    async () => {
        return await PrismaService.main.userProfile.findMany({
            take: 5,
        });
    }
);

6. スパンを使用した非同期オペレーション

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();
});

エラーレベル

適切な重大度レベルを使用してください。

• fatal：システムが使用不能（データベースの停止、重大なサービス障害）
• error：オペレーションの失敗。直ちに対応が必要
• warning：復旧可能な問題、パフォーマンスの低下
• info：情報メッセージ、オペレーションの成功
• debug：詳細なデバッグ情報（開発環境のみ）

必須コンテキスト

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

Sentry.withScope((scope) => {
    // ALWAYS include these if available
    scope.setUser({ id: userId });
    scope.setTag('service', 'form'); // or 'email', 'users', etc.
    scope.setTag('environment', process.env.NODE_ENV);

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

    Sentry.captureException(error);
});

サービス固有の統合

Form Service

場所：./blog-api/src/instrument.ts

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,
});

主なヘルパー：

• WorkflowSentryHelper - ワークフロー固有のエラー
• DatabasePerformanceMonitor - DB クエリの追跡
• BaseController - コントローラーのエラー処理

Email Service

場所：./notifications/src/instrument.ts

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,
});

主なヘルパー：

• EmailSentryHelper - メール固有のエラー
• BaseController - コントローラーのエラー処理

設定（config.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

Sentry 統合のテスト

Form Service のテスト用エンドポイント

# Test basic error capture
curl http://localhost:3002/blog-api/api/sentry/test-error

# Test workflow error
curl http://localhost:3002/blog-api/api/sentry/test-workflow-error

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

# Test error boundary
curl http://localhost:3002/blog-api/api/sentry/test-error-boundary

Email Service のテスト用エンドポイント

# Test basic error capture
curl http://localhost:3003/notifications/api/sentry/test-error

# Test email-specific error
curl http://localhost:3003/notifications/api/sentry/test-email-error

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

パフォーマンス監視

要件

1. すべての API エンドポイントでトランザクションを追跡する必要があります
2. 100ms を超えるデータベースクエリは自動的に検出されます
3. N+1 クエリを検出して報告します
4. cron ジョブでは実行時間を追跡する必要があります

トランザクションの追跡

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();
}

避けるべきよくある間違い

❌ 絶対に Sentry を使わずに console.error を使用しないでください ❌ 絶対に エラーを黙って無視しないでください ❌ 絶対に エラーコンテキストに機密データを含めないでください ❌ 絶対に コンテキストのない汎用的なエラーメッセージを使用しないでください ❌ 絶対に 非同期オペレーションのエラー処理を省略しないでください ❌ 絶対に cron ジョブの先頭行で instrument.ts をインポートし忘れないでください

実装チェックリスト

新しいコードに Sentry を追加するとき：

• Sentry または適切なヘルパーをインポートした
• すべての try/catch ブロックで Sentry にエラーを記録する
• エラーに適切なコンテキストを追加した
• 適切なエラーレベルを使用した
• エラーメッセージに機密データが含まれていない
• 時間のかかるオペレーションにパフォーマンス追跡を追加した
• エラー処理の経路をテストした
• cron ジョブの場合：instrument.ts を最初にインポートした

主要なファイル

Form Service

• /blog-api/src/instrument.ts - Sentry の初期化
• /blog-api/src/workflow/utils/sentryHelper.ts - ワークフローエラー
• /blog-api/src/utils/databasePerformance.ts - DB の監視
• /blog-api/src/controllers/BaseController.ts - コントローラーのベースクラス

Email Service

• /notifications/src/instrument.ts - Sentry の初期化
• /notifications/src/utils/EmailSentryHelper.ts - メールエラー
• /notifications/src/controllers/BaseController.ts - コントローラーのベースクラス

設定

• /blog-api/config.ini - Form Service の設定
• /notifications/config.ini - Email Service の設定
• /sentry.ini - 共有 Sentry 設定

ドキュメント

• 実装の全容：/dev/active/email-sentry-integration/
• フォームサービスのドキュメント：/blog-api/docs/sentry-integration.md
• メールサービスのドキュメント：/notifications/docs/sentry-integration.md

関連スキル

• データベース操作の前に database-verification を使用してください
• ワークフローのエラーコンテキストには workflow-builder を使用してください
• データベースのエラー処理には database-scripts を使用してください