# バッチ設計書 22-log-processor.ts

## 概要

本ドキュメントは、CloudflareワーカーのトレースイベントをHoneycombに送信するログプロセッサーの設計を記載したバッチ設計書です。

### 本バッチの処理概要

log-processor.tsは、Cloudflare Workers のTail機能を利用して、ZEN API（LLM API プロキシ）へのリクエストをリアルタイムで監視し、メトリクスデータをHoneycombに送信するログ処理バッチです。APIの利用状況、エラー発生率、地理的分布などを可観測性プラットフォームで分析可能にします。

**業務上の目的・背景**：ZEN APIは複数のLLMプロバイダーへのプロキシとして機能しており、リクエストの成功率、レイテンシ、エラー発生状況をリアルタイムで把握する必要があります。Honeycombへのメトリクス送信により、運用チームはダッシュボードでシステム健全性を監視し、障害発生時の迅速な原因特定を可能にします。

**バッチの実行タイミング**：Cloudflare Workers のTail機能により、対象ワーカーへのリクエスト発生時にリアルタイムで実行されます。

**主要な処理内容**：
1. Cloudflare Tailイベントの受信とフィルタリング
2. ZEN API エンドポイントへのPOSTリクエストのみを抽出
3. Cloudflare CFメタデータ（地理情報等）の抽出
4. ログメッセージから `_metric:` プレフィックスのメトリクスデータ解析
5. Honeycomb APIへのバッチイベント送信

**前後の処理との関連**：ZEN API（Cloudflare Worker）からのトレースイベントを受信します。Honeycombでのデータ分析、アラート、ダッシュボード表示が後続処理となります。

**影響範囲**：ZEN APIの可観測性システム全体に影響し、障害検知、パフォーマンス分析、利用状況レポートに関わります。

## バッチ種別

ログ転送 / メトリクス収集

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | リアルタイム（イベント駆動） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | Cloudflare Workers Tailイベント |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Cloudflare Workers | ZEN APIワーカーが動作中であること |
| Honeycomb API Key | Resource.HONEYCOMB_API_KEY.valueが設定されていること |
| ネットワーク接続 | Honeycomb API（api.honeycomb.io）へのアクセス可能 |

### 実行可否判定

- イベントタイプがrequest（HTTPリクエスト）であること
- HTTPメソッドがPOSTであること
- リクエストパスが以下のいずれかに該当すること：
  - `/zen/v1/chat/completions`
  - `/zen/v1/messages`
  - `/zen/v1/responses`
  - `/zen/v1/models/`で始まるパス

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| events | TraceItem[] | Yes | - | Cloudflare Tailイベント配列 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| Cloudflare Tail | TraceItem | ワーカー実行トレースイベント |
| Resource.HONEYCOMB_API_KEY | Secret | Honeycomb認証キー |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| Honeycomb API | JSON | メトリクスイベントバッチ |
| console.log | Text | デバッグ出力 |

### 出力ファイル仕様

ファイル出力なし

| 項目 | 内容 |
|-----|------|
| ファイル名 | - |
| 出力先 | https://api.honeycomb.io/1/batch/zen |
| 文字コード | UTF-8 |
| 区切り文字 | - |

## 処理フロー

### 処理シーケンス

```
1. Tailイベント受信
   └─ events配列をループ処理
2. イベントフィルタリング
   └─ event.event存在チェック
   └─ request存在チェック
   └─ POSTメソッドチェック
   └─ ZEN APIパスチェック
3. メタデータ抽出
   └─ Cloudflare CF情報（地理、タイムゾーン等）
   └─ レスポンスステータス、リクエスト長
4. ログメッセージ解析
   └─ `_metric:`プレフィックスのJSON解析
   └─ LLMエラー検出時はエラーイベント追加
5. イベント配列構築
   └─ completionsイベント追加
6. Honeycomb送信
   └─ POST /1/batch/zen
   └─ X-Honeycomb-Teamヘッダー認証
```

### フローチャート

```mermaid
flowchart TD
    A[Tailイベント受信] --> B[イベントループ開始]
    B --> C{event.event存在?}
    C -->|No| B
    C -->|Yes| D{request存在?}
    D -->|No| B
    D -->|Yes| E{POST?}
    E -->|No| B
    E -->|Yes| F{ZEN APIパス?}
    F -->|No| G[return]
    F -->|Yes| H[CFメタデータ抽出]
    H --> I[ログメッセージ解析]
    I --> J{_metric:あり?}
    J -->|Yes| K[メトリクスデータマージ]
    K --> L{llm.error?}
    L -->|Yes| M[エラーイベント追加]
    L -->|No| N[completionsイベント追加]
    M --> N
    J -->|No| N
    N --> O[Honeycomb API送信]
    O --> P[レスポンス確認]
    P --> B
```

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

### 操作別データベース影響一覧

本バッチはデータベースを操作しません。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | - |

### テーブル別操作詳細

データベース操作なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Honeycomb送信失敗 | ネットワークエラー、認証エラー | console.logでステータス出力 |
| - | JSON解析エラー | 不正な_metric:データ | 例外スロー（処理中断） |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

- Honeycomb送信失敗時はconsole.logでステータスとレスポンスボディを出力
- トレースイベント自体は失われないため、Cloudflareログで確認可能

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | イベント単位 |
| コミットタイミング | Honeycomb送信成功時 |
| ロールバック条件 | なし（ベストエフォート送信） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | イベント数に依存 |
| 目標処理時間 | イベント受信後即時 |
| メモリ使用量上限 | Cloudflare Workers制限に準拠 |

## 排他制御

- 並列実行可能（イベントごとに独立）
- Honeycomb APIへのバッチ送信は順次処理

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | - | - |
| 進捗ログ | メトリクスデータ解析時 | JSON.stringify(data, null, 2) |
| 終了ログ | Honeycomb送信後 | ret.status, ret.text() |
| エラーログ | - | - |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| Honeycomb送信成功率 | 要設定 | Honeycombアラート |
| llm.errorイベント数 | 要設定 | Honeycombアラート |

## 備考

- Honeycombデータセット名は「zen」
- イベントタイプは「completions」または「llm.error」
- Cloudflare CF情報には位置情報（国、都市、緯度経度、タイムゾーン）が含まれる
