失敗するパイプラインのデバッグ

パイプラインの問題を素早くデバッグし、解決する能力は、パイプライン保守作業の中核をなすものです。これにより、重要な組織のワークフローを供給する本番パイプラインが信頼性があり、意味のあるものであり続けることが保証されます。

このページでは、パイプライン保守担当者として、オンコールローテーション中にヘルスチェックの失敗に関する通知を受け取った際に、標準オペレーティングプロシージャ（SOP）の基本として使用できるフレームワークを提供します。

必要な知識

このページでは、Foundry のさまざまなツールやワークフローに精通していることが前提となっています。関連するセクションでリンクが提供されます。

また、パイプライン保守チームがインシデントログやパイプラインの繰り返し発生する問題に関するその他の文書を記録していることを前提としています。これはベストプラクティスであり、現在そのような文書がない場合は実装する必要があります。

デバッグフレームワークの概要

常に以下の 3 つの質問を順番に尋ねてください。

緩和: できるだけ早くこの問題を緩和できますか？例えば、以下のようなことを行います。
- スケジュールを再構築します。個々のデータセットや失敗したジョブではなく、スケジュールを再構築することをお勧めします。これにより、スケジュール履歴に表示されます。スケジュール履歴を使用すると、パイプラインの履歴ではなく、個々のデータセットの履歴を追跡できます。
- キューが多すぎる場合は、重複するスケジュールや集中的なスケジュールを探してキャンセルします。
- 手動アップロードが壊れている場合は、既知の安定したバージョンにトランザクションを戻します。
分類: 問題のカテゴリーは何ですか？
- 問題を分類する理由は、根本原因の特定を支援し、解決に別のチームの関与が必要かどうかを判断するためです。
- 以下で、問題のカテゴリーの特定方法と考え方について詳しく説明します。
広範な影響: この問題はプラットフォームの他の部分に影響している可能性がありますか？

ヒント

パイプラインのドキュメントを読んでください！おそらく、この問題はすでに解決されているかもしれません。または、緩和中に行ってはいけないことについての警告があるかもしれません。例えば、一部のビルドは非常に費用がかかり、ピーク使用時に環境のパフォーマンスに影響を与える可能性があります。このような詳細は、チーム全体で十分に文書化されるべきです。

問題カテゴリーの分類

問題を緩和しようとした後、パイプライン保守担当者として、根本原因を理解し対処するためにさらに深く理解する必要があります。デバッグ中に問題を分類する理由は、根本原因を特定するのに役立つためであり、最も重要なことは、問題を修正できるかどうか、または別のチームに連絡する必要があるかどうかを素早く判断するのに役立つからです。

問題のカテゴリーは 3 つあります。

上流の問題: 他の人が管理するインフラストラクチャや作成物に関連する問題
- Foundry の外部: 上流のデータソースに関する問題
- Foundry 内部: 対象のパイプラインの上流にあるデータセット/プロジェクトによって引き起こされる問題
プラットフォームの問題: Foundry プラットフォームのサービスが期待通りに動作していないことによって引き起こされる問題。
変更: 監視対象のパイプラインの範囲内で変更されたもの。これは問題の最も一般的なカテゴリーであり、ユーザーの変更によって引き起こされることがよくあります。例としては、以下のようなものがあります。
- コードの変更
- スケジュールの変更
- パイプライン内のデータサイズの増加

問題のカテゴリーごとの解決手順：

debugging-framework

上記で強調されている手順の詳細は次のとおりです。

識別: 上記の手順を実行する際に、何が壊れているかを非常に正確に識別することが重要です。次のような質問に答えます。
- この問題はいつ始まりましたか？
- パイプラインのどのステップで何かが失敗しましたか？
- どのヘルスチェックが失敗していますか？
- パイプライン内で何かが変更されて、この壊れた状態が引き起こされましたか？
これにより、上流の問題やプラットフォームの問題に関して必要に応じて他のチームと効果的にコミュニケーションを取り、解決時間を短縮できます。また、プラットフォームでのデバッグスキルも向上します。
アクション:
- 上流の問題: パイプラインの上流からの遅延、欠落、または正しくないデータによって問題が引き起こされていることを確認したら、上流のデータに責任を持つチームに連絡してください。
  - ヒント: モニタリングを開始する前に、上流チームの連絡先情報を文書化しておくと便利です。これにより、オンコール担当者が簡単に連絡を取ることができます。
- プラットフォームの問題: Foundry の予期しない動作を特定し、パイプライン内のユーザー変更を排除した場合は、Palantir の担当者に連絡してください。問題に関するできるだけ具体的な情報を提供してください。観察された変更の詳細も含めてください。以下のセクションで、これらを見つける方法についてのヒントがあります。
- 変更: 監視対象のパイプライン内で何かが変更されたことを特定した後、通常は問題を修正するアクションを実行できます。場合によっては、変更を行った人に詳細を尋ねる必要があるかもしれません。次のセクションでは、パイプライン内で何かが変更されたかどうかを特定する方法について説明します。
[オプション] 下流ユーザーへの通信: 問題が分類され、さらに根本原因が特定された後、パイプラインの下流の消費者に通知することが適切な場合があります。これは、問題の影響範囲、対象範囲、期間、およびパイプラインの使用事例によって異なります。
回避策: 別のチームやユーザーからの修正が時間がかかる場合は、健康なパイプラインの部分が下流の消費者に対して引き続き実行されるように、中期的な回避策を実装することが有益です。具体的な一時的な修正は、問題とユーザーのニーズによって異なります。例としては、以下のようなものがあります。
- 壊れたデータセットやパイプラインのブランチをスケジュールから削除することで、問題を隔離します。
- 問題の根本原因である場合、meta.yml でライブラリ名の隣に明示的なバージョン番号を指定することで、別の Python ライブラリのバージョンを固定します。

パイプライン内の変更を特定する

パイプライン保守担当者が直面する最も一般的な問題は、監視対象のパイプライン内で何かが変更されることによる意図しない結果です。また、パイプライン保守担当者として、最も制御が効くカテゴリーであり、他のチームに頼ることなく問題を直接解決できます。

詳しくは、以下の手順を実行します。

パイプライン内で問題が発生している箇所をできるだけ正確に特定します。例えば、スケジュール、データセット、トランザクション、コードの変更などを特定しようとします。
健康な以前の実行と現在の壊れた状態を比較して、何が変更されたかを特定します。質問のメンタルチェックリストを持っておくと便利です。以下は、質問の例と、答えを見つけるのに役立つツールの例です。
- いつもより遅いですか？これはキューイングによるものですか、それとも実際に計算に時間がかかっていますか？
- ファイル/データサイズの変更はありますか？
- コードの変更？スキーマの変更？
- スケジュールの変更？
- プラットフォームのインシデントが進行中ですか？

ツール

上記の質問に答えるために使用される Foundry のツールに精通していない場合、以下のリストは調査中に使用する最も一般的なパターンの例を提供します。このリストはすべての可能性を網羅しているわけではなく、ガイドとしての役割を果たします。

私のジョブ/ビルドはいつもより遅いですか？

Builds アプリケーションは、特定のデータセットに対するジョブを比較します。ビルドの概要の右上にあるプログレス詳細の切り替えを使用すると、キューイング時間と計算時間によるビルドの進行状況を確認できます。
- 失敗したジョブがスケジュールの一部としてビルドされた場合、ビルド詳細ページの左下にスケジュールカードが表示されます。以前のビルドを表すドットをクリックすることで、以前のスケジュールの実行を開くことができます。
スケジュールメトリクスでは、スケジュールの履歴の実行を表示し、実行を比較するためのメトリクスとグラフを表示できます。

データセットのサイズに変更がありますか？トランスフォームはより多くのデータで実行されていますか？

データセットプレビュー: Foundry のデータセットの履歴と比較タブは、データセットの履歴の概要を提供し、以前のトランザクションと比較してデータセットの変更内容の概要を取得できます。
Contour は、サマリーボードを使用して行番号を比較する歴史的ビューへのアクセスを提供します。また、データが追加/作成された日付を示す列がある場合、行数を日付に対して比較するチャートを作成できます。
Spark の詳細: 任意のジョブで Spark の詳細ボタンをクリックすると（下記参照）、パイプライン内により多くのデータがあるかどうかを示す情報が表示されます。タスクのカウントメトリックなどです。

spark-details-button

パイプライン内のコードが変更されましたか？

データセットプレビューの比較タブでは、データセットの履歴上のトランザクションを比較すると、直接トランスフォームファイルのコード変更が表示されます。
コードリポジトリ内の ファイルの変更（コミット履歴）ヘルパーは、コードタブでコードの変更を表示することができます。
Data Lineage ツールを使用すると、パイプライン全体のスキーマの概要を簡単に確認できます。特に、パイプライン全体で特定の列を含むデータセットを追跡するのに便利なのが、サイドパネルの プロパティ＆ヒストグラム です。

コードの変更は、Python や Java など、これをサポートする言語を使用している場合、トランスフォームにインポートされたライブラリで発生することがあります。トランスフォームで変更がない場合は、ライブラリ関数のロジックが変更されたかどうかを確認してみてください。

スケジュールが変更されましたか？

プラットフォームのさまざまな部分にあるスケジュールカードを使用すると、スケジュールが最後に変更されたときを確認できます。
スケジュールのメトリクスページにあるスケジュールバージョンタブを使用すると、スケジュール設定に対してどのような変更が行われたかを特定できます。

プラットフォームの問題を特定する

他のジョブ、ビルド、または関連するプラットフォームコンポーネントで同様の症状が見られるかどうかを確認することは、症状に基づいて問題が何であるかわからない場合に有益な調査方法です。

特に、次の質問に答えることを探してください。

再現性がありますか？
- この問題は一貫して発生しますか？
- パターンがありますか？例えば、毎週月曜日の午前 9 時に週末が終わった後に失敗するなどです。
範囲は何ですか？
- ジョブが遅いか失敗している場合、他のトランスフォームジョブでもこれを確認していますか？または、Python ジョブだけですか？

Builds アプリケーションを使用して、プラットフォーム全体のジョブ履歴をフィルタリングすることで、上記の質問に答えることができます。

パイプライン保守担当者の仕事の中核をなすのは、パイプラインの問題を素早くデバッグし、解決する能力です。重要な組織のワークフローを供給する本番パイプラインが信頼性があり、意味のあるものであり続けることを確実にするために、このページで説明されているガイドラインに従っても問題が特定できない場合は、Palantir の担当者に連絡してください。