# ログ送信機能 有効化手順

## 概要

本ドキュメントでは、アプリケーションアカウントのログを任意の収集先へ送信する機能を有効化する手順について説明します。

ログ送信機能を有効化すると、以下のデータが毎日自動的に収集・送信されます。

- 汎用AIアプリログ、行政実務用AIアプリログ、ユースケースビルダーログ
- 行政実務用AIアプリ定義情報、行政実務用AIアプリ実行履歴
- Cognito ユーザー情報、Cognito ユーザーアクティビティログ

送信先は IAM 認証付きの API エンドポイントであれば何でも構いません。受信後のデータ処理は任意です。

設定は以下の順序で行います。

1. 受信側の API エンドポイントを用意する（事前作業）
2. パラメータファイルに設定を追加する
3. CDK をデプロイする
4. 翌日、ログが届いているか確認する

## 1. 受信側の API エンドポイントを用意する

> このステップは送信側の設定より先に完了させてください。受信先が存在しない状態でデプロイしても、ログは送信されません。

受信側の API は以下の要件を満たす必要があります。

### 認証

- AWS IAM 認証（SigV4）を使用すること
- 送信元アカウントの Lambda ロール（`GenerativeAiUseCasesStack-LoggingLambdaRole*`）が AssumeRole できる IAM ロール（CrossAccountRole）を用意すること

### エンドポイント

以下のパスで POST リクエストを受け付けること。

| パス                          | 送信されるデータ                   |
| ----------------------------- | ---------------------------------- |
| `/chat-logs`                  | 汎用AIアプリログ                   |
| `/gov-ai-logs`                | 行政実務用AIアプリログ             |
| `/use-case-builder-logs`      | ユースケースビルダーログ           |
| `/exapp-logs`                 | 行政実務用AIアプリ定義情報         |
| `/invoke-history-logs`        | 行政実務用AIアプリ実行履歴         |
| `/user-pool-users`            | Cognito ユーザー情報               |
| `/cognito-user-activity-logs` | Cognito ユーザーアクティビティログ |

準備が完了したら、以下の 2 つの値をメモしておいてください。

| 必要な値               | 例                                                           |
| ---------------------- | ------------------------------------------------------------ |
| 受信側のアカウント ID  | `123456789012`                                               |
| API エンドポイント URL | `https://xxx.execute-api.ap-northeast-1.amazonaws.com/prod/` |

## 2. パラメータファイルに設定を追加する

CDK プロジェクト（`packages/cdk`）を開き、対象環境のパラメータファイルを編集します。

**編集するファイル**: `env-parameters/self-hosting-{env}.ts`（例: `self-hosting-prod.ts`）

以下の設定を追加してください。

```typescript
export const commonProdParams: Partial<StackInput> = {
  // ... 既存の設定はそのまま ...

  // ▼ ログ送信機能の設定（ここを追加）
  destination: {
    accountId: "123456789012", // 手順 1. でメモした受信側アカウント ID
    endpointUrl: "https://xxx.execute-api.ap-northeast-1.amazonaws.com/prod/", // 手順 1. でメモした API エンドポイント URL
  },
  logAccumulationBucketExpirationDays: 364, // 自アカウント S3 の一時保存期間（日数）
  DailyExportEventHourUTC: "17", // DynamoDB エクスポート時刻（UTC）= JST 02:00
  TransferS3LogsHourUTC: "18", // 受信側への送信時刻（UTC）= JST 03:00
};
```

### 設定値の決め方

**`logAccumulationBucketExpirationDays`**
送信前のデータを一時的に保管する S3 バケットの保存期間です。

**`DailyExportEventHourUTC` と `TransferS3LogsHourUTC`**
処理は 2 段階で動きます。まず `DailyExportEventHourUTC` の時刻に DynamoDB から S3 へエクスポートし、次に `TransferS3LogsHourUTC` の時刻に受信側へ送信します。**必ず `DailyExportEventHourUTC` より後の時刻**を指定してください。

| UTC 時刻 | JST 換算   |
| -------- | ---------- |
| `"17"`   | 翌日 02:00 |
| `"18"`   | 翌日 03:00 |

## 3. CDK をデプロイする

```bash
npm ci
npm -w packages/cdk run cdk -- deploy --all --require-approval never -c env=-prod
```

`LoggingStack` は `GenerativeAiUseCasesStack` に含まれるため、`--all` で一緒にデプロイされます。

## 4. 動作確認する

ログの送信は `DailyExportEventHourUTC` / `TransferS3LogsHourUTC` で指定した時間に実行されます。送信時刻を過ぎた後に以下を確認してください。

### CloudWatch Logs で確認

AWS マネジメントコンソール → CloudWatch → ロググループ から、以下のロググループを確認します。

| ロググループ                                             | 確認内容                              |
| -------------------------------------------------------- | ------------------------------------- |
| `/aws/lambda/ExportDdbToS3-{appEnv}-ChatLogs`            | DynamoDB エクスポートが成功しているか |
| `/aws/lambda/TransferS3Logs-{appEnv}-ChatLogs`           | 受信側への送信が成功しているか        |
| `/aws/lambda/ExportUserPoolUsers-{appEnv}-UserPoolUsers` | ユーザー情報の送信が成功しているか    |

> `{appEnv}` はパラメータファイルの `appEnv` の値に置き換えてください。

正常時のログには `200` のレスポンスが記録されます。

## トラブルシューティング

### `AccessDenied` または `403 Forbidden`

受信側の CrossAccountRole が自アカウントからの接続を許可していない可能性があります。

```bash
# 接続できるか手動でテスト
aws sts assume-role \
  --role-arn arn:aws:iam::{受信側アカウントID}:role/CrossAccountRole-{自アカウントID} \
  --role-session-name test
```

失敗する場合は、受信側の CrossAccountRole の信頼ポリシーに自アカウント ID が含まれているか確認してください。

### DynamoDB エクスポートが失敗する

テーブルのポイントインタイムリカバリ（PITR）が有効か確認してください。

```bash
aws dynamodb describe-continuous-backups \
  --table-name {テーブル名} \
  --query 'ContinuousBackupsDescription.PointInTimeRecoveryDescription.PointInTimeRecoveryStatus'
# "ENABLED" と返れば OK
```

`DISABLED` の場合は AWS マネジメントコンソールから PITR を有効化してください。