mirror-doctor

Mirror パイプラインの診断

CLI コマンドを実行して根本原因を特定し、修正を実行することで、既存の Mirror パイプラインの問題を診断して解決します。

対応範囲

• 既存の Mirror パイプラインの問題を診断して解決します。
• 新しいパイプラインは構築しません。設定の参照には /mirror、新しい Turbo パイプラインの作成には /turbo-builder を使用してください。
• コマンドリファレンスとしては使用しません。CLI の構文やフラグの確認には /mirror を使用してください。
• Turbo パイプラインは扱いません。goldsky turbo の問題には /turbo-doctor を使用してください。
• シークレットは作成しません。認証情報の管理には /secrets を使用してください。ただし、診断の一環としてシークレットが存在するかどうかは確認してください。

診断ワークフロー

以下の手順を順番に実行してください。各ステップは前のステップを踏まえて進めます。

ステップ 1：認証を確認する

ユーザーがログインしていることを確認するため、goldsky project list 2>&1 を実行します。

• ログイン済みの場合： プロジェクト名を確認し、次に進みます。
• ログインしていない場合： ユーザーに /auth-setup を案内します。認証が機能するまで先に進まないでください。

ステップ 2：パイプラインを特定する

すべての Mirror パイプラインとそのステータスを一覧表示するため、goldsky pipeline list --include-runtime-details 2>&1 を実行します。

ユーザーがすでにパイプライン名を指定している場合は、一覧に存在することを確認します。指定していない場合は一覧を表示し、診断したいパイプラインを尋ねます。

希望ステータス（ACTIVE、INACTIVE、PAUSED）とランタイムステータス（STARTING、RUNNING、FAILING、TERMINATED）の両方を確認してください。Mirror パイプラインには両方のステータスがあり、その組み合わせから状況を把握できます。

ステップ 3：ステータスに基づいて切り分ける

希望ステータスとランタイムステータスの組み合わせによって、診断の進め方が決まります。

希望ステータス	ランタイム	意味	対応
ACTIVE	RUNNING	正常 — パイプラインはデータを処理しています	ユーザーに、どのような症状が発生しているか尋ねます。ステップ 4 に進みます。
ACTIVE	STARTING	パイプラインは初期化中です	どのくらい時間が経過したか尋ねます。10 分を超えている場合は、ステップ 4 に進みます。
ACTIVE	FAILING	パイプラインでエラーが発生していますが、まだ終了していません	すぐにステップ 4 に進みます。時間が重要です。
ACTIVE	TERMINATED	最も一般的な障害です。 パイプラインは実行を試みましたが、クラッシュしました。	ステップ 4 に進みます。
PAUSED	TERMINATED	ユーザーがパイプラインを一時停止しました（スナップショットが取得されています）。	再開するかどうかを尋ねます。goldsky pipeline start <name> --from-snapshot last
INACTIVE	TERMINATED	ユーザーがパイプラインを停止しました（スナップショットはありません）。	起動するかどうかを尋ねます。goldsky pipeline start <name>

ACTIVE + TERMINATED が最も一般的なケースです。 パイプラインの希望ステータスは ACTIVE（実行中であるべき）ですが、エラーによりランタイムが終了しています。ここを重点的に診断してください。

ステップ 4：診断データを収集する

問題の原因を把握するため、次のコマンドを実行します。

# Get error details and runtime metrics
goldsky pipeline monitor <name> 2>&1

# Check for in-flight requests blocking operations
goldsky pipeline monitor <name> --update-request 2>&1

# Get the pipeline definition to check for misconfig
goldsky pipeline get <name> --definition 2>&1

# Get pipeline info including version
goldsky pipeline info <name> 2>&1

# Check available snapshots
goldsky pipeline snapshots list <name> 2>&1

これらを順番に実行し、次に進む前に出力を分析してください。モニターの出力が最も重要です。エラーメッセージ、受信・書き込みレコードのメトリクス、ランタイムステータスの遷移が表示されます。

ステップ 5：エラーパターンを照合する

診断データに基づいて、次の既知のパターンと照合します。

シークレットの不正または欠落

症状： パイプラインは起動後すぐに終了します。モニターに認証情報または認証に関するエラーが表示されます。

確認方法： goldsky secret list 2>&1 を実行し、ステップ 4 で取得したパイプライン定義内の secret_name の値と照合します。

修正方法：

1. シークレットが存在しない場合は、作成するためにユーザーに /secrets を案内します。
2. シークレットは存在するものの認証情報が誤っている場合は、goldsky secret update でシークレットをそのまま更新します。必要な JSON 形式と認証情報の取り扱いについては、認証情報のローテーション に従ってください。使用中のシークレットを削除して再作成しないでください。
3. 再起動します：goldsky pipeline restart <name> --from-snapshot last

シンクに接続できない

症状： モニターの出力に接続タイムアウト、接続拒否、またはネットワークエラーが表示されます。パイプラインが FAILING と TERMINATED の間を繰り返すことがあります。

一般的な原因：

• AWS us-west-2 からのインバウンド通信がファイアウォールで許可されていない（Mirror パイプラインはこのリージョンから書き込みます）
• データベースが停止している、または再起動された
• 接続プールが枯渇している
• シークレット内のポートまたはホストが誤っている

対処方法：

1. us-west-2 からシンクに接続できることを確認します。
2. シークレットに正しいホスト、ポート、認証情報が設定されていることを確認します。
3. 接続が復旧したら、再起動します：goldsky pipeline restart <name> --from-snapshot last

リソースの枯渇

症状： パイプラインがしばらく実行された後に終了します。モニターに大量のレコード数や処理の遅延が表示されることがあります。大規模なバックフィルや、多数のソース／JOIN を含むパイプラインでよく発生します。

対処方法：

1. サイズを変更します：goldsky pipeline resize <name> <size> — サイズは s、m、l、xl、xxl です。
2. 小さいサイズから始め、徐々に大きくします。s でほとんどのワークロードに対応できます（最大 300K レコード／秒、約 8 個のサブグラフソース）。大規模なチェーンのバックフィルや負荷の高い JOIN には、l 以上を使用します。

実行中のリクエストによるブロック

症状： パイプラインを更新、削除、または再起動しようとすると、「Cannot process request, found existing request in-flight.」というエラーが表示されます。

診断： goldsky pipeline monitor <name> --update-request を実行すると、進行中の操作（通常はスナップショット）が表示されます。

対処方法：

1. 実行中の操作が進行中のスナップショットであれば、完了するまで待ちます。
2. 停滞している、または不要な場合：goldsky pipeline cancel-update <name>
3. その後、元の操作を再試行します。

スナップショットの停滞

症状： スナップショットの作成に時間がかかりすぎる、または失敗するため、パイプラインを一時停止、更新、再起動できません。--update-request モニターで、スナップショットの進行状況が特定の割合で止まっていることが確認できます。

対処方法：

1. 停滞しているスナップショットをキャンセルします：goldsky pipeline cancel-update <name>
2. 新しいスナップショットを待たずに再起動します：goldsky pipeline restart <name> --from-snapshot last
3. 使用可能なスナップショットがない場合：goldsky pipeline restart <name> --from-snapshot none（最初から開始します。データを再処理することをユーザーに伝えてください）

Transform SQL エラー

症状： SQL 関連のエラーメッセージが表示されてパイプラインが終了します。構文エラー、存在しないカラムの参照、型の不一致などが考えられます。

診断： パイプライン定義（goldsky pipeline get <name> --definition）を確認し、transforms セクションを調べます。

対処方法：

1. モニターの出力から SQL エラーを特定します。
2. パイプラインの YAML ファイル内の SQL を修正します。
3. 検証します：goldsky pipeline validate <file.yaml>
4. 再適用します：goldsky pipeline apply <file.yaml> --status ACTIVE --from-snapshot last

必要に応じて、SQL Transform の構文については /mirror を参照してください。

パイプラインが再起動を繰り返す

症状： パイプラインが STARTING → FAILING → TERMINATED の状態を繰り返します。モニターには同じエラーが繰り返し表示されます。

これは通常、別の根本原因の症状です — 不正なシークレット、シンクに接続できない、またはリソースの問題が考えられます。パイプラインは起動を試み続けますが、同じ問題に直面します。

対処方法：

1. モニターから根本的なエラーを特定します（通常は上記のいずれかのパターンです）。
2. まず根本原因を解消します。
3. その後、再起動します：goldsky pipeline restart <name> --from-snapshot last

シンクのダウンによる連鎖的な停止

症状： パイプラインは正常に実行されていましたが、シンク（データベース）が一時的に停止しました。パイプラインは自動で再試行し、ライターを再起動した後、最終的に終了しました。

これは想定された動作です — Mirror は一時的なシンクエラーを自動的に処理します（バッチを再試行 → ライターを再起動 → 問題が長時間続いた場合は失敗）。

対処方法：

1. シンクが復旧し、正常に動作していることを確認します。
2. 最後のスナップショットから再起動します：goldsky pipeline restart <name> --from-snapshot last
3. パイプラインはすべてを再処理するのではなく、中断した箇所から再開します。

ステップ 6：診断結果を提示する

問題を特定したら、調査結果を明確に提示します：

## Diagnosis

**Pipeline:** <name>
**Status:** <desired> + <runtime>
**Issue:** <one-line summary>

**Root cause:**
<What's wrong and why>

**Evidence:**
- <Error message or observation from monitor>
- <Relevant detail from pipeline definition>

**Recommended fix:**
1. <Step 1>
2. <Step 2>

**Prevention:**
<How to avoid this in the future, if applicable>

ステップ 7：修正を実行する

修正コマンドを直接実行するか、ユーザーに確認します。実行する前に必ずユーザーの確認を得てください。

• 再起動： goldsky pipeline restart <name> --from-snapshot last
• サイズ変更： goldsky pipeline resize <name> <size>
• ブロックされた操作のキャンセル： goldsky pipeline cancel-update <name>
• 最初から再起動： goldsky pipeline restart <name> --from-snapshot none（警告：データを再処理します）
• 設定の再適用： goldsky pipeline apply <file.yaml> --status ACTIVE --from-snapshot last
• 削除して再作成： goldsky pipeline delete <name> -f の後に goldsky pipeline apply <file.yaml> --status ACTIVE（最終手段）

実行後、goldsky pipeline monitor <name> を実行し、STARTING → RUNNING への遷移を確認して、復旧を検証します。

重要なルール

• 診断の前に必ずデータを収集してください。問題を推測してはいけません。
• 希望するステータスと実行時のステータスの両方を確認してください。組み合わせが重要です。
• 破壊的なコマンド（削除、最初からの再起動）を実行する前に、必ずユーザーに確認してください。
• --from-snapshot last は進行状況を保持します。--from-snapshot none は最初からやり直します。特別な理由がない限り、last を使用してください。
• 一時的なエラーは最大 6 時間、自動的に再試行されます。一時的ではないエラーは直ちに終了します。開始後すぐにパイプラインが終了した場合は、一時的なネットワーク障害ではなく、設定の問題（シークレットの不備や SQL の誤り）が原因である可能性が高いです。
• CLI での診断で解決できない問題については、パイプライン名、エラーメッセージ、プロジェクト ID を添えて [email protected] に問い合わせるよう提案してください。

Bash を使用できない場合

Bash ツールを使用できない場合は、ユーザーが実行する診断コマンドを出力し、わかりやすく構成してください。

1. コマンドを一度に 1 つずつ提示します。
2. 出力で確認すべき内容を説明します。
3. 出力についてユーザーから説明を受けたら、それに基づいて診断を進めます。

これは代替手段です。Bash を使用できる場合は、必ずコマンドの直接実行を優先してください。

関連項目

• /mirror — パイプラインの YAML 設定、CLI フラグのリファレンス、シンクの設定
• /secrets — シンクの認証情報の作成と管理
• /auth-setup — CLI のインストールと認証
• /turbo-doctor — Turbo パイプラインの問題の診断（Mirror は対象外）