注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。

トラブルシューティング

ソースが期待どおりに動作しない場合は、このページを使って問題を診断し、解決します。このページでは、Data Connection で利用可能なトラブルシューティングツール、接続が機能しない場合に最初に確認する箇所、一般的な接続や証明書の問題を解決する方法について説明します。

同期または Agent に固有の問題については、機能固有の問題を参照してください。ネットワークスループットによって取り込み速度が制限される場合は、ネットワークスループットを最適化するを参照してください。

最初に確認すること

ソースまたは接続が機能しない場合は、まずこのリストに沿って確認します。

  1. ソースに到達できることを確認します。 ソースページでプレビューを選択し、接続が確立されることを確認します。失敗する場合は、ソースターミナルを開き、ソースのホスト名とポートに対して dig、curl、openssl s_client を実行します。
  2. エグレス設定を確認します。 Foundry ワーカーのソースでは、正しいエグレスポリシーがアタッチされており、そのポリシーで許可されるアドレス、ポート、プロトコルがソースの接続先と一致していることを確認します。ネットワークエグレスログを確認します。
  3. 資格情報を確認します。 資格情報が古くなっている可能性がある場合、特に移行後は、資格情報を再入力します。
  4. 証明書を確認します。 PKIX または SSLHandshakeException エラーは、ソースに正しい証明書が設定されていないことを示します。証明書と TLS を参照してください。
  5. OAuth 認可を確認します。 ソースがアウトバウンドアプリケーションを使用している場合、HTTP 401: Unauthorized などのエラーは通常、呼び出し元のユーザーが対話型の認可フローを完了していない、アウトバウンドアプリケーションが無効になっている、または設定されたスコープが不十分であることを示します。OAuth とアウトバウンドアプリケーションを参照してください。
  6. AI FDE に引き継ぎます。 Foundry ワーカーのソースでは、AI FDE でデバッグするを使用すると、AI FDE がこれらの確認を順に行い、具体的な修正方法を提示します。

ソースが Agent ワーカーを使用している場合は、Data Connection で Agent がオンラインと表示されていることも確認し、ステータスごとのガイダンスについては Agent のトラブルシューティングリファレンスを参照してください。

トラブルシューティングツール

Data Connection には、プラットフォームを離れることなく接続、認証、データ移動の問題を調査できる組み込みツールが用意されています。

AI FDE でデバッグする

Foundry ワーカーのソースでは、Palantir の AI を活用した Forward Deployed Engineer である AI FDE にデバッグを任せることができます。AI FDE は、ソースとそれに関連するエグレスポリシーをコンテキストに読み込み、このページで説明するエグレスログとソースデバッグツールを使用して、接続の失敗を代わりに調査します。

ソースから AI FDE のデバッグセッションを開始するには、次の手順を実行します。

  1. Data Connection アプリケーションで、デバッグするソースを開きます。
  2. 接続情報パネルで、デバッグの横にあるドロップダウンの矢印を選択し、AI FDE でデバッグを選択します。
  3. ソースとそのエグレスポリシーがコンテキストとして事前に読み込まれた状態で、AI FDE が新規タブに開きます。AI FDE は、ソース設定の確認、各エグレスポリシーの確認、ネットワークエグレスログの取得、ライブ接続テストの実行を含むデバッグ計画を提案します。

AI FDE は、正常に動作している点と失敗している点を要約し、具体的な修正方法を提案します(例:エグレスポリシーの不足、アドレスやポートの誤り、TLS 設定の問題、資格情報の問題)。

AI FDE でデバッグは、Foundry ワーカーのランタイムを使用するソースでのみ利用可能です。AI FDE を使用するには、エンロールメントで AIP を有効にする必要があります。AI FDE の仕組み、機能、コンテキストと権限の管理方法については、AI FDE の概要を参照してください。

ソースターミナル

ソースと同じ接続設定を使用するターミナルを利用できます。dig、curl、netcat、openssl などのコマンドを使用して、外部システムとのネットワーク接続をテストできます。

ターミナルを開くには、ソースページの接続情報にあるネットワーク接続パネルで、デバッグを選択します。

ソースターミナルには、ソースページの接続情報にあるネットワーク接続パネルでデバッグを選択してアクセスできます。

dig

dig コマンドは DNS 名前解決をテストし、ソースのホスト名が正しく解決されるかどうかを確認するために使用できます。たとえば、DNS で palantir.com が解決されるかどうかをテストするには、dig palantir.com を実行します。レスポンスに ANSWER SECTION が表示されれば、DNS 名前解決は成功しています。

ソースで Agent プロキシのエグレスポリシーを使用している場合、dig が 10.238.0.X などの内部仮想 IP アドレスを返すことがあります。Foundry はこのアドレスを使用して Agent 経由で接続をルーティングします。このアドレスは外部システムの実際の IP アドレスではありません。

したがって、ソースターミナルで dig のレスポンスが正常に返っても、Agent が宛先の名前解決や宛先への到達に成功することを確認したことにはなりません。接続をテストするには、元のホスト名とポートを指定し、HTTP には curl、TLS には openssl s_client など、適切なツールを使用します。

以下は、成功した dig コマンドの例です。

appuser@localhost:/root$ dig palantir.com

; <<>> DiG 9.18.30-0ubuntu0.20.04.2-Ubuntu <<>> palantir.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 13561
;; flags: qr rd ra; QUERY: 1, ANSWER: 4, AUTHORITY: 0, ADDITIONAL: 0

;; QUESTION SECTION:
;palantir.com.                  IN      A

;; ANSWER SECTION:
palantir.com.           300     IN      A       151.101.129.170
palantir.com.           300     IN      A       151.101.1.170
palantir.com.           300     IN      A       151.101.193.170
palantir.com.           300     IN      A       151.101.65.170

;; Query time: 99 msec
;; SERVER: 10.100.0.53#53(10.100.0.53) (UDP)
;; WHEN: Fri Oct 31 14:56:58 UTC 2025
;; MSG SIZE  rcvd: 142

curl

curl コマンドは、外部システムの特定のホストとポートへの HTTP 接続をテストします。ポートが指定されていない場合は、プロトコルから推定されます(例:HTTP では80、HTTPS では443)。たとえば、https://palantir.com への接続を確立できるかどうかをテストするには、curl https://palantir.com を実行します。

以下は、成功した curl コマンドの例です。

appuser@localhost:/root$ curl https://palantir.com
<HTML><HEAD><meta http-equiv="content-type" content="text/html;charset=utf-8">
<TITLE>301 Moved</TITLE></HEAD><BODY>
<H1>301 Moved</H1>
The document has moved
<A HREF="https://www.palantir.com/">here</A>.
</BODY></HTML>

curl コマンドが応答しない場合は、--connect-timeout フラグを使用してタイムアウト(秒)を設定します。

Copied!
1 curl --connect-timeout 10 https://palantir.com

openssl

openssl コマンドは SSL/TLS 接続をテストし、HTTPS 接続の証明書を検証します。たとえば、palantir.com のポート 443 への SSL/TLS 接続を確立できるかどうかをテストするには、openssl s_client -connect palantir.com:443 -servername palantir.com を実行します。

以下は、成功した openssl コマンドの例です。

appuser@localhost:/root$ openssl s_client -connect palantir.com:443 -servername palantir.com
CONNECTED(00000003)
depth=2 C = BE, O = GlobalSign nv-sa, OU = Root CA, CN = GlobalSign Root CA
verify return:1
depth=1 C = BE, O = GlobalSign nv-sa, CN = GlobalSign Atlas R3 DV TLS CA 2024 Q2
verify return:1
depth=0 CN = *.palantir.com
verify return:1
---
Certificate chain
 0 s:CN = *.palantir.com
   i:C = BE, O = GlobalSign nv-sa, CN = GlobalSign Atlas R3 DV TLS CA 2024 Q2
   a:PKEY: rsaEncryption, 2048 (bit); sigalg: RSA-SHA256
   v:NotBefore: Jun 17 16:50:15 2024 GMT; NotAfter: Jul 19 16:50:14 2025 GMT
---
SSL handshake has read 3654 bytes and written 442 bytes
---

接続に成功すると、証明書の詳細と、SSL ハンドシェイクが完了したことを示すメッセージが表示されます。コマンドが応答しない場合や証明書の検証エラーが表示される場合は、ネットワークまたは証明書の設定に問題がある可能性があります。

UI で設定した証明書は、ターミナル環境に自動的には含まれません。ターミナルで使用するには、インラインで直接指定するか、nano/vim を使用して手動で追加します。

Copied!
1 2 3 4 5 echo "-----BEGIN CERTIFICATE----- MIIGXjCCBUagAwIBAgIQASByQ6gv8Z6X7wEqsyBb1DANBgkqhkiG9w0BAQsFADBY ... 9lc= -----END CERTIFICATE-----" > server-cert.pem

自己署名証明書や mTLS など、カスタム証明書を使用してテストするには、証明書ファイルを指定します。

Copied!
1 2 3 4 5 openssl s_client -connect my-server.example.com:443 \ -servername my-server.example.com \ -CAfile server-cert.pem \ -cert client-cert.pem \ -key client-key.pem

これらのコマンドが成功しても接続が機能しない場合は、一部の証明書またはソースの資格情報が正しく設定されていない可能性が高いです。

ネットワークエグレスのログとメトリクス

Foundry ワーカーのソースでは、ネットワークエグレスのログとメトリクスにより、ソースが実際に行っているネットワーク呼び出しを把握できます。これらのツールは、ターミナルでのデバッグだけでは明らかにならないネットワークの問題を特定するのに役立ちます。

  • Build ログ: ビルドページでログを選択し、ネットワークエグレスログフィルターを適用して、そのビルドのネットワークエグレスアクティビティを確認します。
  • Control Panel: Control Panel > ネットワークのエグレスに移動し、ポリシーを選択して観測可能性タブを開くと、ソースごとに集計されたログと、そのポリシーの使用状況メトリクスを表示できます。

ソースのプレビューと探索

さらに詳しくデバッグする前に、ソースにそもそも到達できるか、設定が正しいかを確認します。

  • プレビュー: ソースページの右側のパネルでプレビューを選択し、接続が正常に確立されていることを確認します。
  • 探索: ソース探索の表示を使用して、ソースのテーブル、ファイル、プレビューを確認します。探索が成功しても特定の同期が失敗する場合は、ソースよりも同期設定に問題がある可能性が高いです。

Job tracker

実行中または最近完了した同期のステータスを調査するには、Job tracker アプリケーションを開き、同期を選択します。そこから、ステータス、ステージ、ログを確認できます。JDBC 同期の場合は _data-ingestion.log も確認できます。

接続とエグレス

接続を成功させるには、Foundry がネットワーク経由で外部システムに到達できるように許可する必要があります。Foundry ワーカーのソースでは、接続を許可する特定のホスト、ポート、プロトコルを許可リストに登録するエグレスポリシーを通じて、これを制御します。認証前に接続が失敗する場合は、通常、エグレスの問題です。

エグレスの問題が疑われる場合にデバッグするには、次の手順を実行します。

  1. 正しいエグレスポリシーがソースにアタッチされていることと、ポリシーで許可されているホスト、ポート、プロトコルが接続先のシステムと一致していることを確認します。
  2. ソースターミナルで dig、curl、openssl s_client を使用し、そもそもホストに到達できるかどうかをテストします。
  3. ネットワークエグレスログを確認して、ソースが実際に行っている外向きの呼び出しを把握し、どの呼び出しがブロックされているかを特定します。

エグレスポリシーを作成または申請するには、エグレスポリシーを設定するを参照してください。

ネットワークスループットを最適化する

ネットワークの遅延が大きいと、高帯域幅の接続であっても、インターネット経由のスループットが制限されることがあります。

Foundry にデータを取り込む際に、接続元側のホストでネットワーク設定を調整すると、スループットが向上する場合があります。データベースがプロキシの背後にある場合は、プロキシホストを設定します。

接続ホスト
Secure Tunnelsセキュアトンネルのイニシエーター
直接接続インターネットに公開されたホストまたはコンテナ

このセクションでは、TCP 輻輳制御アルゴリズムである Bottleneck Bandwidth and Round-trip propagation time(BBR)の有効化と、TCP 送信バッファーの上限の引き上げという2つの最適化について説明します。適用するステップは、接続方法によって異なります。

BBR 輻輳制御アルゴリズムを有効にする

BBR は、利用可能な帯域幅とネットワーク遅延に基づいて、ホストの送信レートを調整します。

Linux では、設定対象のホストで次のコマンドを実行し、出力に bbr が含まれていることを確認します。Data Connection Agent が管理する Secure Tunnels の場合、対象は Agent ホストです。

Copied!
1 sysctl net.ipv4.tcp_available_congestion_control

Data Connection Agent が管理する Secure Tunnels

Agent 設定では BBR が有効になりますが、TCP 送信バッファーは変更されません。BBR を有効にした後、Agent ホストで TCP 送信バッファーの上限も引き上げます。

BBR を有効にするには、次の手順を実行します。

  1. Data Connection で Agent を開き、Agent 設定タブを選択します。設定の管理セクションで詳細を切り替え、Envoy タブを選択します。

  2. YAML 設定に次のエントリーを追加します。

    Copied!
    1 optimizedTcpSendThroughput: true
  3. 変更を保存してから、Agent を再起動します。

Apollo が管理する Secure Tunnels

イニシエーターの Apollo 設定で optimizedTcpSendThroughput を true に設定します。これにより、BBR と 16 MiB の TCP 送信バッファーの両方が有効になるため、送信バッファーの上限を個別に引き上げる必要はありません。

直接接続

Linux では、データベースまたはプロキシのホストで BBR を有効にします。

  1. 次回の再起動まで BBR を有効にします。

    Copied!
    1 sudo sysctl -w net.ipv4.tcp_congestion_control=bbr
  2. systemd を使用するホストでは、再起動後も設定が維持されるように保存します。

    Copied!
    1 sysctl net.ipv4.tcp_congestion_control | sudo tee /etc/sysctl.d/99-foundry-bbr.conf

BBR が有効になるには、データベースまたはプロキシのサービスを再起動し、再接続する必要がある場合があります。

TCP 送信バッファーの上限を引き上げる

TCP 送信バッファーの上限を引き上げると、ホストが送信中の状態に保てるデータ量が増えます。

Linux では、送信バッファーの最大サイズを引き上げます。

  1. 現在の送信バッファーの最小サイズ、デフォルトサイズ、最大サイズをバイト単位で表示します。変更を元に戻す必要が生じた場合に備えて、これらの値を記録します。

    Copied!
    1 cat /proc/sys/net/ipv4/tcp_wmem
  2. 最大サイズが 16777216(16 MiB)未満の場合は、引き上げます。このコマンドでは、現在の最小値とデフォルト値が保持されます。

    Copied!
    1 sudo sysctl -w "net.ipv4.tcp_wmem=$(awk '{print $1, $2, 16777216}' /proc/sys/net/ipv4/tcp_wmem)"
  3. systemd を使用するホストでは、再起動後も設定が維持されるように保存します。

    Copied!
    1 sysctl net.ipv4.tcp_wmem | sudo tee /etc/sysctl.d/99-foundry-tcp-send-buffer.conf

証明書と TLS

このセクションでは、Foundry がクライアントとして、サーバーとして動作する外部システムへの接続を確立することを前提としています。基礎となる概念については、TLS ↗、mTLS ↗、SSL ↗ を参照してください。

PKIX 例外と SSL 例外

PKIX 例外やその他の SSLHandshakeException は、ソースとの認証に必要な証明書を Foundry が持っていない場合に発生します。正しい証明書をインストールしてください。

非推奨の TLSv1.0 または TLSv1.1 プロトコルのみをサポートするソースについては、安全でない TLSv1.0 および TLSv1.1 プロトコルを使用してデータソースに接続するを参照してください。Palantir は、非推奨の TLS バージョンの使用を推奨しません。

サーバー証明書とクライアント証明書

サーバー証明書とクライアント証明書の違いを理解することが重要です。

サーバー証明書(TLS): Foundry クライアントが外部システムとの TLS 接続を確立する際、外部システムは、自身の身元を証明し、暗号化された接続の確立に必要な公開鍵を提供するために証明書を提示します。次に、Foundry クライアントは、信頼されたルート認証局(CA)までの証明書チェーンを検証して、外部システムの身元を確認します。ほとんどのシステムは、広く知られた公開 CA のリストをデフォルトで信頼します。ソース設定(Foundry の truststore)にサーバー証明書を追加する必要があるのは、自己署名証明書やプライベート CA または内部 CA が発行した証明書など、これらの公開 CA のいずれによっても署名されていない証明書を外部システムが提示する場合のみです。サーバー証明書は証明書のみを指定し、秘密鍵は決して指定しません。

クライアント証明書(mTLS): クライアント証明書は、Foundry クライアントが外部システムに対して自身の身元を証明するために使用します。mTLS では、外部システムと Foundry が互いの身元を確認します。クライアント証明書は、証明書と秘密鍵のペアとして指定します。

証明書を設定するには、証明書を追加するを参照してください。

一般的な証明書エラー

[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate in certificate chain

このエラーは、ソース設定にサーバー証明書がないことを示します。Python 環境では、安全な接続を確立する際に、基盤となる OpenSSL ライブラリーが証明書チェーン ↗ 全体を検証します。

外部システムの証明書チェーン全体を取得するには、次のコマンドを実行します。

Copied!
1 openssl s_client -connect <external_systems_hostname>:<desired_port> -showcerts < /dev/null

外部システムへのネットワークアクセスがあるホストから、このコマンドを実行します。Foundry ワーカーのソースの場合は、ソースターミナルから実行します。Agent ワーカーのソースの場合は、Agent ホスト、または Agent のネットワークにアクセスできる別のシステムから実行します。

OAuth とアウトバウンドアプリケーション

ソースにアウトバウンドアプリケーションが設定されている場合、認証は呼び出し元ユーザーに代わって外部の OAuth 2.0 プロバイダーに委任されます。スケジュールされた関数や自動化などの非対話型コンテキストからソースを使用するには、ユーザーが事前に対話型の認可フローを少なくとも1回完了している必要があります。

よくある OAuth エラー

HTTP 401: Unauthorized

ソースにアウトバウンドアプリケーションが設定されているにもかかわらず、関数やワークフローが HTTP 401: Unauthorized を返す場合は、次の点を確認します。

  • 関数を呼び出すユーザーが、対話型の認可フローを少なくとも1回完了していること。
  • Control Panel でアウトバウンドアプリケーションが有効になっていること。
  • アウトバウンドアプリケーションに設定されたスコープに、リクエストされた API リソースへのアクセスに必要な権限が含まれていること。

Credentials expired and no refresh handler provided

このエラーは、Python または TypeScript 関数からソースを呼び出すときに表示されます。キャッシュされたリフレッシュトークンが期限切れになっているか、外部の OAuth 2.0 サーバーによって取り消されています。ユーザーは対話型インターフェースから関数(または同じアウトバウンドアプリケーションを元にした別のワークフロー)を呼び出し、認可フローを再度完了する必要があります。

Resolved source credentials are not present on the Source

このエラーは、Python または TypeScript 関数からソースを呼び出すときに表示されます。ソースにアウトバウンドアプリケーションが設定されていないか、呼び出し元の ID を認可済みのユーザーに解決できなかったことを示します。ソースのドメインに OAuth 2.0 認証が設定されていること、および関数がサービスアカウントではなく認証済みのエンドユーザーに代わって呼び出されていることを確認します。

機能固有の問題

上記のガイダンスは、どのソースにも適用されます。特定の機能に固有の問題については、専用のリファレンスを参照してください。