失敗しているパイプラインをデバッグする

パイプラインの問題を迅速にデバッグして解決する能力は、パイプラインの保守作業の中核をなすものです。これにより、組織の重要なワークフローにデータを供給する本番パイプラインの信頼性と有用性を維持できます。

このページでは、パイプライン保守担当者としてオンコール当番中にヘルスチェックの失敗通知を受け取った際の、標準作業手順書（SOP）の土台として使用できるフレームワークを紹介します。

前提知識

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

また、パイプライン保守チームが、パイプラインで繰り返し発生する問題についてインシデントログやその他のドキュメントを記録していることも前提としています。これはベストプラクティスであり、現在そのようなドキュメントがない場合は作成してください。

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

必ず、次の3つの質問を順番に検討することから始めます。

影響の軽減： この問題の影響をできるだけ早く軽減できますか？たとえば、次の方法があります。
- スケジュールを再ビルドします。単一のデータセットや失敗しているジョブではなく、スケジュールを再ビルドすることを推奨します。これにより、再ビルドがスケジュール履歴に表示されます。スケジュール履歴では、個々のデータセットの履歴ではなく、パイプラインの履歴を追跡できます。
- キューでの待機が多すぎる場合は、重複しているスケジュールやリソースを大量に使用するスケジュールを探してキャンセルします。
- 手動アップロードに問題がある場合は、トランザクションを安定していることがわかっているバージョンに戻します。
分類： 問題のカテゴリーは何ですか？
- 問題を分類する目的は、根本原因の特定を支援し、解決に別のチームの関与が必要かどうかを判断することです。
- 問題のカテゴリーの考え方と特定方法の詳細は、以下を参照してください。
より広範な影響： この問題はプラットフォームのほかの部分にも影響している可能性がありますか？

パイプラインのドキュメントを読んでください。この問題は以前に解決されたことがあるかもしれません。また、影響を軽減する際に行ってはいけないことについての警告があるかもしれません。たとえば、一部のビルドは非常に多くのリソースを消費し、利用が集中する時間帯には環境のパフォーマンスに影響する可能性があります。このような詳細は、チーム全体に向けて十分に文書化しておく必要があります。

問題のカテゴリー分類

問題の影響を軽減する試みの後、パイプライン保守担当者はさらに深く調査し、根本原因を理解して対処する必要があります。デバッグ時に問題の分類が役立つのは、根本原因を特定しやすくなるためです。特に重要なのは、自分で問題を修正できるのか、それとも別のチームに連絡する必要があるのかを迅速に判断できることです。

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

上流の問題： 他者が管理するインフラストラクチャや作成物に関連する問題
- Foundry の外部： 上流のデータソースの問題
- Foundry 内部： 対象のパイプラインの上流にあるデータセットやプロジェクトが原因の問題
プラットフォームの問題： Foundry プラットフォームのサービスが期待されるとおりに動作しないことが原因の問題
変更： _監視を担当しているパイプラインの範囲内で_何らかの変更が生じたことによる問題。これは最もよくある問題のカテゴリーであり、多くの場合、ユーザーによる変更が原因です。たとえば、次のようなものがあります。
- コードの変更
- スケジュールの変更
- パイプライン内のデータサイズの増加

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

デバッグフレームワーク

上記で強調した手順の詳細は次のとおりです。

特定： 上記の手順を進める際は、何に問題があるのかを非常に正確に特定することが重要です。次のような質問に答えます。
- 問題はいつ始まりましたか？
- パイプラインのどのステップで失敗しましたか？
- どのヘルスチェックに失敗していますか？
- パイプライン内の何らかの変更が、この問題のある状態を引き起こしましたか？
これにより、上流の問題やプラットフォームの問題について、必要に応じてほかのチームと効果的に情報を共有でき、解決までの時間を短縮できます。また、プラットフォームでのデバッグスキルの向上にもつながります。
対処：
- 上流の問題： パイプラインの上流にあるプロジェクトやデータソースからのデータの遅延、欠落、または誤りが実際に問題の原因であると確認できたら、上流のデータを担当するチームに連絡します。
  - ヒント： 監視を開始する前に、上流チームの連絡先を文書化しておくと役立ちます。これにより、オンコール担当者が連絡しやすくなります。
- プラットフォームの問題： Foundry の予期しない動作を特定し、パイプラインでのユーザーによる変更が原因ではないと判断できた場合は、Palantir の担当者に連絡します。観察された変更の詳細を含め、問題についてできるだけ具体的な情報を伝えます。これらを見つけるためのヒントは、以下のセクションを参照してください。
- 変更： 監視対象のパイプライン内で何らかの変更が生じたと特定した場合は、通常、修正のための対処を行えます。場合によっては、詳しい情報を得るために変更を行った人に連絡する必要があります。パイプライン内で何らかの変更が生じたかどうかを特定する方法については、次のセクションを参照してください。
［任意］下流のユーザーへの連絡： 上記の図には記載されていない手順として、問題を分類し、根本原因をさらに特定した後に、パイプラインの下流の利用者に通知することが適切な場合があります。これは、問題の影響、範囲、継続時間、およびパイプラインのユースケースによって異なります。
回避策： 別のチームやユーザーによる修正に時間がかかる場合は、中期的な回避策を実施し、パイプラインの正常な部分が下流の利用者のために引き続き実行されるようにすると役立つことがあります。具体的な暫定対応は、問題とユーザーのニーズによって異なります。たとえば、次の方法があります。
- 問題のあるデータセットやパイプラインブランチをスケジュールから外して、問題を切り離します。
- Python ライブラリのバージョンが問題の根本原因である場合は、別のバージョンに固定します。これは、meta.yml でライブラリ名の横にバージョン番号を明示的に指定することで行えます。

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

パイプライン保守担当者が直面する最もよくある問題は、監視しているパイプライン内で何らかの変更が生じたことによる意図しない結果です。また、このカテゴリーでは、パイプライン保守担当者が最も大きな裁量を持ち、別のチームに頼らずに直接問題を修正できます。

具体的な手順は次のとおりです。

パイプライン内のどこから問題が生じているのかを、できる限り正確に突き止めます。たとえば、スケジュール、データセット、トランザクション、コードの変更などを特定してみます。
以前の正常な実行と現在の問題のある状態を比較し、何が変わったのかを特定します。質問のチェックリストを頭に入れておくと役立つことがあります。以下に、質問の例と、答えを見つけるために役立つツールの例を示します。
- 通常より遅くなっていますか？これはキューでの待機が原因ですか、それともビルドの計算処理に実際に長い時間がかかっていますか？
- ファイルやデータのサイズに変更はありますか？
- コードの変更はありますか？スキーマの変更はありますか？
- スケジュールの変更はありますか？
- 進行中のプラットフォームのインシデントはありますか？

ツール

上記の質問の一部に答えるために使用する Foundry のツールに詳しくない場合は、以下のリストに、調査でよく使われるパターンの例を示しています。このリストはすべての可能性を網羅するものではなく、調査を始めるためのガイドです。

ジョブ/ビルドが通常より遅くなっていますか？

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

データセットのサイズに変更はありますか？トランスフォームが処理するデータ量は増えていますか？

データセットプレビュー：どの Foundry データセットでも、履歴タブと比較タブでデータセットの履歴の概要を確認でき、過去のトランザクションと比較して変更内容の概要を把握できます。
Contourでは、履歴ビューにアクセスして、概要ボードを使って行数を比較できます。また、データが追加/作成された日付を表す列がある場合は、グラフを作成して、追加日ごとの行数を比較できます。
Spark の詳細：任意のジョブで Spark の詳細ボタン（下記参照）をクリックすると、タスク数メトリクスなど、パイプライン内のデータ量が増えているかどうかを判断するのに役立つ情報を確認できます。

パイプライン内のコードは変更されていますか？

データセットプレビューの比較タブでは、データセットの過去のトランザクションを比較する際に、直接対応するトランスフォームファイルのコード変更を確認できます。
Code Repositories では、コードタブのファイルの変更（コミット履歴）ヘルパーでコード変更を確認できます。
Data Lineage ツールでは、パイプライン全体のスキーマの概要をすばやく把握できます。サイドパネルのプロパティとヒストグラムは、パイプライン内のどのデータセットに特定の列が含まれているかを追跡する際に特に役立ちます。

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

スケジュールは変更されていますか？

プラットフォームのさまざまな場所にあるスケジュールカードで、スケジュールが最後に変更された日時を確認できます。
スケジュールのメトリクスページにあるスケジュールのバージョンタブでは、スケジュールの設定にどのような変更が加えられたかを正確に特定できます。

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

確認できる症状だけでは問題が何か判断できない場合は、ほかのジョブ、ビルド、または関連するプラットフォームコンポーネントで同様の症状が発生していないか確認することが、調査を進めるうえで役立ちます。

特に、次の質問への答えを確認してください。

再現可能ですか？
- この問題は一貫して発生しますか？
- 発生にパターンはありますか？たとえば、毎週、週末明けの月曜日の午前9時に失敗しますか？
影響範囲はどこまでですか？
- ジョブが遅い、または失敗している場合、ほかのトランスフォームのジョブでも同じことが起きていますか？それとも、ほかの Python ジョブでのみ起きていますか？

Builds アプリケーションを使ってプラットフォーム全体のジョブ履歴を絞り込むと、上記の質問への答えを見つけるのに役立ちます。

パイプラインの問題をすばやくデバッグして解決する能力は、パイプラインの保守担当者の業務の中核をなすものです。これにより、組織の重要なワークフローにデータを供給する本番パイプラインの信頼性と有用性を維持できます。このページで説明したガイドラインに沿って調査しても問題を特定できない場合は、Palantir の担当者にお問い合わせください。