# 機能設計書 44-Sentryプラグイン

## 概要

本ドキュメントは、Payload CMSにおけるSentry統合プラグイン（plugin-sentry）の設計を記載する。本プラグインは、PayloadアプリケーションのエラーをSentryに自動送信し、エラー監視とトラッキングを実現する。

### 本機能の処理概要

**業務上の目的・背景**：本番環境での障害検知と原因分析を効率化するため、エラー監視サービスとの統合が重要である。Sentryは広く使われるエラートラッキングサービスであり、本プラグインはPayloadのエラーフック機構を活用してシームレスな統合を提供する。

**機能の利用シーン**：
- 本番環境でのエラー監視とアラート
- エラー発生時のコンテキスト情報の収集
- ユーザー情報を含むエラートラッキング
- 管理画面でのReactエラーバウンダリ対応
- 特定のHTTPステータスコードのエラーのみキャプチャ

**主要な処理内容**：
1. afterErrorフックでのエラーキャプチャ
2. HTTPステータスコードに基づくフィルタリング
3. ユーザー情報、リクエストコンテキストの付加
4. カスタムコンテキスト関数によるメタデータ追加
5. Admin UIへのReact Error Boundaryの注入

**関連システム・外部連携**：
- Sentry（@sentry/nextjs等）
- Admin UI（React Error Boundary）

**権限による制御**：
- 特になし（エラーログは全ユーザーから収集）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 全管理画面 | 参照画面 | AdminErrorBoundaryでのクライアントエラーキャプチャ |

## 機能種別

監視 / エラーハンドリング / 外部連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| enabled | boolean | No | プラグインの有効/無効 | デフォルト: true |
| Sentry | SentryInstance | Yes* | Sentryインスタンス | enabled=true時は必須 |
| options.captureErrors | number[] | No | キャプチャする追加ステータスコード | デフォルト: [] |
| options.context | function | No | カスタムコンテキスト関数 | - |
| options.debug | boolean | No | デバッグモード | デフォルト: false |

### 入力データソース

- Payload設定ファイルでのプラグイン設定
- @sentry/nextjs（または他のSentry SDK）のインポート
- Payloadのエラーフックからのエラー情報
- リクエストオブジェクト（ユーザー情報、ヘッダー等）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | string | SentryのイベントID |

### 出力先

- Sentry（エラーイベント）
- ログ（debug=true時）

## 処理フロー

### 処理シーケンス

```
1. プラグイン初期化
   └─ enabled === false または Sentry未設定の場合は無効
2. afterErrorフックの登録
3. エラー発生時
   ├─ ステータスコードの判定
   │   ├─ 500以上 → キャプチャ
   │   ├─ captureErrorsに含まれる → キャプチャ
   │   └─ それ以外 → スキップ
   ├─ デフォルトコンテキストの生成
   │   ├─ extra.errorCollectionSlug
   │   └─ user（認証時）
   ├─ カスタムコンテキスト関数の呼び出し（設定時）
   └─ Sentry.captureException実行
4. AdminErrorBoundaryの注入
   └─ React Error Boundaryでクライアントエラーをキャプチャ
```

### フローチャート

```mermaid
flowchart TD
    A[エラー発生] --> B{enabled?}
    B -->|No| C[処理なし]
    B -->|Yes| D{Sentry設定済み?}
    D -->|No| C
    D -->|Yes| E[ステータスコード取得]
    E --> F{500以上?}
    F -->|Yes| G[コンテキスト生成]
    F -->|No| H{captureErrorsに含まれる?}
    H -->|Yes| G
    H -->|No| C
    G --> I{カスタムcontext設定?}
    I -->|Yes| J[カスタムコンテキスト適用]
    I -->|No| K[Sentry.captureException]
    J --> K
    K --> L{debug=true?}
    L -->|Yes| M[ログ出力]
    L -->|No| N[完了]
    M --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 500エラー自動キャプチャ | ステータスコード500以上のエラーは常にキャプチャ | デフォルト動作 |
| BR-02 | 追加ステータスキャプチャ | captureErrorsで指定したステータスコードもキャプチャ | captureErrors設定時 |
| BR-03 | ユーザー情報付加 | 認証済みユーザーの情報をコンテキストに付加 | req.userが存在する場合 |
| BR-04 | IP情報付加 | X-Forwarded-Forヘッダーからユーザーのipを取得 | ヘッダーが存在する場合 |
| BR-05 | コレクション情報付加 | エラー発生元のコレクションslugをextraに追加 | コレクション操作時 |

### 計算ロジック

特になし

## データベース操作仕様

本プラグインはデータベース操作を行わない。

## エラー処理

### エラーケース一覧

本プラグインはエラーをキャプチャするものであり、プラグイン自体がエラーを発生させることは想定していない。

## トランザクション仕様

該当なし

## パフォーマンス要件

- Sentry.captureExceptionは非同期で実行（awaitなし）
- エラー処理のオーバーヘッドは最小限

## セキュリティ考慮事項

- ユーザーのパスワードやセンシティブ情報はSentryに送信されない
- ユーザー情報はid、collection、email、username、ip_addressのみ
- カスタムコンテキスト関数でセンシティブ情報を追加しないよう注意が必要

## 備考

- Sentry SDKは別途インストール・設定が必要（@sentry/nextjs推奨）
- Admin UIのエラーバウンダリは@payloadcms/plugin-sentry/clientからインポート

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

プラグイン設定の型定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `packages/plugin-sentry/src/types.ts` | PluginOptions、SentryInstance、ContextArgs |

**読解のコツ**: `SentryInstance`はSentry SDKの型を抽象化している。`captureException`メソッドがあれば任意のSentry SDKで動作する。

#### Step 2: エントリーポイントを理解する

プラグインの全体ロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/plugin-sentry/src/index.ts` | sentryPlugin関数 |

**主要処理フロー**:
1. **32-36行目**: enabled/Sentryのチェック
2. **38行目**: オプションのデストラクチャリング
3. **43-49行目**: AdminErrorBoundaryプロバイダーの追加
4. **53-56行目**: afterErrorフックの追加
5. **57行目**: ステータスコードの取得
6. **58-78行目**: コンテキストの生成
7. **80行目**: Sentry.captureException呼び出し
8. **82-86行目**: デバッグログ出力

### プログラム呼び出し階層図

```
sentryPlugin (index.ts)
    │
    ├─ afterError hook
    │      ├─ ステータスコード判定
    │      ├─ デフォルトコンテキスト生成
    │      │      ├─ extra.errorCollectionSlug
    │      │      └─ user情報
    │      ├─ options.context（カスタム）
    │      └─ Sentry.captureException
    │
    └─ AdminErrorBoundary (client)
           └─ React Error Boundary
```

### データフロー図

```
[入力]                    [処理]                         [出力]

Payloadエラー ─────────▶ afterErrorフック ─────────────▶ フィルタリング
                              │                              │
                              ▼                              ▼
                      コンテキスト生成 ──────────────▶ Sentryイベント
                              │
                    ┌─────────┴─────────┐
                    ▼                   ▼
             デフォルト              カスタム
             コンテキスト            コンテキスト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/plugin-sentry/src/index.ts` | ソース | プラグインのエントリーポイント |
| types.ts | `packages/plugin-sentry/src/types.ts` | ソース | 型定義 |
| AdminErrorBoundary | `packages/plugin-sentry/src/client/AdminErrorBoundary.tsx` | ソース | React Error Boundary |
