# バッチ設計書 4-TelemetryPing

## 概要

本ドキュメントはMedusaフレームワークのTelemetry Pingジョブについて、その設計内容を記述したバッチ設計書です。Telemetry Pingは6時間ごとにテレメトリデータを送信する内部ジョブであり、Medusaの利用状況を収集するために実装されています。

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

Telemetry Pingは、Medusaサーバーが正常に稼働していることを定期的に報告するための内部ジョブです。node-scheduleライブラリを使用してスケジューリングされ、6時間ごとに@medusajs/telemetryパッケージのtrack関数を呼び出します。

**業務上の目的・背景**：Medusaプラットフォームの利用状況を把握し、製品改善に役立てるためのテレメトリ機能です。匿名の利用統計を収集することで、Medusa開発チームはどの機能が使用されているか、どのような環境で動作しているかを理解できます。これはオープンソースプロジェクトの持続可能な開発を支援するための重要な機能であり、ユーザーは環境変数でオプトアウトすることも可能です。

**バッチの実行タイミング**：cron式`0 */6 * * *`により6時間ごとに実行されます。具体的には0時、6時、12時、18時に実行されます。

**主要な処理内容**：
1. node-scheduleによるスケジュール管理
2. @medusajs/telemetryのtrack関数呼び出し
3. "PING"イベントの送信

**前後の処理との関連**：Medusaサーバーの起動処理（start.ts）内でスケジュールが設定されます。サーバーが稼働している間、継続的に実行されます。他のバッチ処理との依存関係はありません。

**影響範囲**：外部のテレメトリサービスへのHTTP通信が発生します。データベースやローカルファイルシステムへの影響はありません。ネットワーク帯域への影響は最小限です。

## バッチ種別

内部Cronジョブ / テレメトリ送信

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 6時間ごと |
| 実行時刻 | 00:00, 06:00, 12:00, 18:00 |
| 実行曜日 | 毎日 |
| 実行日 | 毎日 |
| トリガー | cron（`0 */6 * * *`） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| サーバー稼働中 | Medusaサーバーが起動・稼働していること |
| node-scheduleの初期化 | start処理内でscheduleJobが呼び出されていること |

### 実行可否判定

- サーバーが稼働している限り自動的に実行される
- テレメトリのオプトアウト設定は@medusajs/telemetry側で処理される

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | 入力パラメータなし |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| なし | - | 入力データなし（固定イベント名を送信） |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| テレメトリサービス | HTTP | "PING"イベントを送信 |

### 出力ファイル仕様

ファイル出力なし

## 処理フロー

### 処理シーケンス

```
1. サーバー起動時
   └─ scheduleJob(CRON_SCHEDULE, callback)でジョブ登録
2. 6時間ごとにジョブ実行
   └─ node-scheduleがコールバックを呼び出し
3. track関数呼び出し
   └─ track("PING")でテレメトリ送信
4. 処理完了
   └─ 次回実行まで待機
```

### フローチャート

```mermaid
flowchart TD
    A[サーバー起動] --> B[scheduleJob登録]
    B --> C[6時間待機]
    C --> D[cronトリガー]
    D --> E[track PING呼び出し]
    E --> F[テレメトリ送信]
    F --> C
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| なし | - | - | データベース操作なし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ネットワークエラー | テレメトリサービスへの接続失敗 | @medusajs/telemetry内部で処理（サイレント失敗） |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（@medusajs/telemetry依存） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

- テレメトリ送信の失敗はアプリケーションの動作に影響しません
- エラーはサイレントに処理され、次回のスケジュール実行まで待機します

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1日4回 |
| 目標処理時間 | 数秒以内 |
| メモリ使用量上限 | 最小 |

## 排他制御

排他制御は不要です。単一のスケジュールジョブとして実行されます。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| - | - | 明示的なログ出力なし |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| - | - | - |

テレメトリ機能は監視対象外です。

## 備考

- CRON式は`EVERY_SIXTH_HOUR = "0 */6 * * *"`として定義されています
- track関数は@medusajs/telemetryパッケージからインポートされます
- サーバー起動時（`CLI_START`）および起動完了時（`CLI_START_COMPLETED`）にもtrack関数が呼び出されます
- テレメトリはプライバシーに配慮した匿名データのみを収集します
- ユーザーは環境変数を通じてテレメトリをオプトアウトできます
- 実装箇所: `packages/medusa/src/commands/start.ts` (L345-347)
