注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。
このページでは、Agent ログの設定方法、Agent 設定に関する一般的な問題、およびデバッグのガイダンスについて説明します。
Agent Manager は、インストール先のサーバーでは「bootvisor」と呼ばれます。
ここで説明するステップは、Agent がインストールされているホストに SSH 接続した後に実行する必要があります。
ほかのトラブルシューティング項目を調べる前に、まず ./var/diagnostic/launch.yml を確認して、Agent が Foundry に正常に接続したことを確認することを推奨します。接続に失敗した場合は、enhancedMessage フィールドに記載された手順に従ってください。
Foundry への接続に必要な証明書が期限切れになった場合、または代替証明書をインストールする前にローテーションされた場合、Agent Manager と Foundry の接続が失われることがあります。これには、Foundry を信頼するために使用する証明書や、TLS トラフィックを検査するプロキシの証明書が含まれます。Agent 証明書を管理から代替証明書を追加するだけでは、切断された Agent Manager を復旧できません。更新を取得するには、正常な接続が必要です。
ホスト上の Agent Manager ログで、SSLHandshakeException、PKIX path building failed、CertificateExpiredException などの証明書検証エラーを確認します。Foundry 用の最新の認証局(CA)証明書は Palantir サポートから、プロキシ用の証明書はネットワーク管理者から入手してください。Foundry またはプロキシが期限切れのサーバー証明書を引き続き提示している場合、Agent の接続を復旧するには、その管理者がまず証明書を更新する必要があります。
Data Connection のAgent 証明書を管理を使用して、影響を受けている Agent に必要な証明書を追加し、以下の復旧方法のいずれかを選択します。影響を受けている Agent ごとに、この手順を繰り返します。
ホストと Agent Manager のトラストストアにアクセスできる場合は、デフォルトの Linux インストール環境で次のステップを実行します。これにより、既存のインストールを修復し、ソースの資格情報を保持します。
Agent Manager を実行するユーザーとしてホストに接続します。インストールディレクトリに移動し、自動再起動が設定されている場合は無効にして、Agent Manager を停止し、トラストストアをバックアップします。
Copied!1 2 3 4cd <agent-manager-install-directory> ./service/bin/auto_restart.sh clear ./service/bin/init.sh stop cp var/security/truststore.jks var/security/truststore.jks.bak
必要な CA 証明書を、それぞれ個別の PEM ファイルとしてホストに保存します。同梱の Java を使用して、証明書ごとに未使用のエイリアスを選択し、各証明書を Agent Manager のトラストストアにインポートします。
Copied!1 2cd jdk/amazon-corretto* ./bin/keytool -importcert -alias <CERT_ALIAS> -file /path/to/certificate.pem -keystore ../../var/security/truststore.jks
このトラストストアのデフォルトのパスワードは truststore です。インポートを承認する前に、証明書の提供元にフィンガープリントを確認してください。トラストストアで別のパスワードが使用されており、そのパスワードを入手できない場合は、Agent を再インストールするステップに従ってください。
Agent Manager のインストールディレクトリに戻り、起動します。
Copied!1 2cd <agent-manager-install-directory> ./service/bin/init.sh start
Data Connection で、Agent Manager が再接続することを確認します。Agentを再起動を選択して、Agent 証明書を管理から追加した証明書を適用し、Agent Manager と Agent の両方が接続されていることを確認します。以前に自動再起動が有効になっていた場合は、再度有効にします。
ローカルのトラストストアを更新できない場合は、最新の証明書を含む新しいパッケージを使用して、既存の Agent を再インストールします。
var/data/source-encryption-key と var/data/source-encryption-key.private を保持します。curl -s https://<your domain name>/magritte-coordinator/api/ping > /dev/null && echo pass || echo fail を実行します。
pass と表示されます。その場合は、次の操作を行います。
echo $http_proxy を実行すると、プロキシが使用されているかどうかを確認できます。curl: (6) Could not resolve host: ... のようなエラーが表示されることがあります。この場合、何らかの要因(ファイアウォールやプロキシなど)によって接続がブロックされている可能性が高いため、Palantir の担当者にお問い合わせください。<agent-manager-install-location>/var/log/startup.log ファイルの内容を確認します。
Caused by: java.net.BindException: {} Address already in use というエラーが表示される場合、Agent Manager がバインドしようとしているポートですでにプロセスが実行されています。
<agent-manager-directory>/var/conf/install.yml ファイルの内容を確認し、port パラメーターを探すことで特定できます(例:port: 1234 — この場合、1234がポートです)。port パラメーターが定義されていない場合、Agent Manager はデフォルトのポート7032を使用します。ps aux | grep $(lsof -i:<PORT> |awk 'NR>1 {print $2}' |sort -n |uniq)。ここで、<PORT> は Agent Manager がバインドしようとしているポートです。
com.palantir.magritte.bootvisor.BootvisorApplication が含まれている場合、別の Agent Manager がすでに実行されています。BindException エラーを修正するには、Agent Manager 用に、現在使用されていない新しいポートを見つける必要があります。
lsof -i :<PORT>。ここで、<PORT> は選択したポート番号です。利用可能なポートが見つかったら、<agent-manager-directory>/var/conf/install.yml に保存されている設定に port パラメーターを追加(または更新)する必要があります。
以下は、ポートを 7032 に設定した Agent Manager の設定スニペットの例です。
Copied!1 2 3... port: 7032 auto-start-agent: true
上記の設定を保存したら、<agent-manager-root>/service/bin/init.sh stop && <agent-manager-root>/service/bin/init.sh start を実行して Agent Manager を再起動します。
<agent-manager-directory>/var/data/processes/<latest-bootstrapper-directory>/var/log/startup.log ファイルの内容を確認します。
Caused by: java.net.BindException: {} Address already in use というエラーが表示される場合、Bootstrapper がバインドしようとしているポートですでにプロセスが実行されています。
port パラメーターで定義されています(例:port: 1234 — この場合、1234がポートです)。Bootstrapper のデフォルトのポートは7002です。ps aux | grep $(lsof -i:$PORT |awk 'NR>1 {print $2}' |sort -n |uniq)。ここで、$PORT は Bootstrapper がバインドしようとしているポートです。
com.palantir.magritte.bootstrapper.MagritteBootstrapperApplication が含まれている場合、別の Bootstrapper がすでに実行されています。BindException エラーを修正するには、Bootstrapper 用に、現在使用されていない新しいポートを見つける必要があります。
lsof -i :<PORT>。ここで、<PORT> は選択したポート番号です。利用可能なポートが見つかったら、Bootstrapper の設定で port パラメーターを設定する必要があります。これを行うには、Data Connection アプリケーションの Agent の概要ページに移動します。そこで詳細設定ボタンを選択し、最後に「Bootstrapper」タブに移動します。
以下は、ポートを 7002 に設定した Bootstrapper の設定スニペットの例です。
Copied!1 2 3 4server: adminConnectors: ... port: 7002 #This is the port value
設定を更新したら、変更を保存して Agent を再起動し、変更を反映させる必要があります。
多くの場合、これは Agent の別の「ゴースト」インスタンスが実行されていることが原因であり、そのインスタンスを見つけて停止する必要があります。
古いプロセスを見つけて終了するには、以下のステップに従います。
<agent-manager-install-location>/service/bin/init.sh stop を実行して Agent Manager を停止します。<agent-manager-install-location>/var/data/processes/index.json ファイルを削除します。for folder in $(ls -d <agent-manager-root>/var/data/processes/*/); do $folder/service/bin/init.sh stop; done を実行して、古いプロセスを停止します。<agent-manager-install-location>/service/bin/init.sh start)。Data Connection 経由ではなく、Agent がインストールされているホストで手動で Agent を起動すると、「ゴースト」プロセスが作成されることがあります。
Agent プロセスが「異常」と表示される場合、多くは、プロセスがクラッシュしたか、オペレーティングシステムまたはウイルス対策ソフトウェアなどの別のソフトウェアによってシャットダウンされたことが原因です。
オペレーティングシステムがプロセスをシャットダウンする理由はいくつかありますが、最も一般的なのは、プロセスの実行に必要なメモリーがオペレーティングシステムに不足していることです。これは、OOM (Out Of Memory) による強制終了と呼ばれます。
Agent または Explorer のサブプロセスがオペレーティングシステムによって OOM 強制終了されたかどうかを確認するには、grep "exited with return code 137" -r <agent-manager-directory> --include=*.log コマンドを実行します。このコマンドは、Agent Manager ディレクトリー内のすべてのログファイルから「exited with return code 137」を含むエントリーを検索します(リターンコード137は、プロセスが OOM 強制終了されたことを示します)。
次は、上記のコマンドの出力例で、Agent サブプロセスが OOM 強制終了されていることを示しています。./var/data/processes/bootstrapper~<>/var/log/magritte-bootstrapper.log:ERROR [timestamp] com.palantir.magritte.bootstrapper.ProcessMonitor: magritte-agent exited with return code 137。このような出力が表示された場合は、以下のヒープサイズの調整手順に沿って進めてください。
また、dmesg -T | egrep -i 'killed process' コマンドを実行すると、オペレーティングシステムのログで OOM 強制終了のエントリーを確認できます。このコマンドは、カーネルリングバッファー内で「killed process」というログエントリーを検索します。このエントリーは、プロセスが OOM 強制終了されたことを示します。
OOM 強制終了されたプロセスの実際のログエントリーは、次のようになります。
[timestamp] Out of memory: Killed process 9423 (java) total-vm:2928192kB, anon-rss:108604kB, file-rss:0kB, shmem-rss:0kB, UID:0 pgtables:1232kB oom_score_adj:0(java) を含まないエントリーは Agent に関連しないため、無視できます。ヒープの割り当てを変更する前に、まず次のことを行ってください。
free -h を実行します。6 GB のシステムでは、出力は次のようになります。Copied!1 2 3total used free shared buff/cache available Mem: 5.8Gi 961Mi 2.8Gi 9.0Mi 2.1Gi 4.6Gi Swap: 1.0Gi 0B 1.0Gi
free コマンドの出力では、available 列に、新しいアプリケーションの起動に使用できるメモリー量が表示されます。Agent に割り当て可能なメモリー量を特定するには、Agent を停止し、システムの負荷が通常から高負荷の状態で free -h を実行することを推奨します。available の値は、すべての Agent プロセスに合計で割り当てられるメモリーの最大量を示します。システム上のほかのプロセスでメモリーの追加が必要になることや、Agent プロセスによるオフヒープメモリーの使用を考慮し、可能であれば約2~4 GB の余裕を残すことを推奨します。free のすべてのバージョンで available 列が表示されるわけではないため、同等の情報を確認するには、システムで使用しているバージョンのドキュメントを参照する必要がある場合があります。
Agent Manager、Bootstrapper、Agent、Explorer の各サブプロセスに割り当てられているメモリー量を特定します。
Agent および Explorer のサブプロセスに割り当てられているメモリー量を確認するには、Data Connection 内の Agent 設定ページに移動し、詳細設定ボタンを選択して、「Bootstrapper」タブを選択します。各サブプロセスには専用の設定ブロックがあり、各ブロック内の jvmHeapSize パラメーターで、対応するプロセスに割り当てられるメモリー量が定義されています。
デフォルトでは、Bootstrapper サブプロセスには 512mb のメモリーが割り当てられています。これを確認するには、まず <agent-manager-directory>/var/data/processes/ ディレクトリーに移動し、ls -lrt を実行して、最後に作成された bootstrapper~<uuid> ディレクトリーを見つけます。そのディレクトリーに移動したら、./var/conf/launcher-custom.yml ファイルの内容を確認します。このファイルの Xmx の値が、Bootstrapper に割り当てられているメモリー量です。
デフォルトでは、Agent Manager サブプロセスにも 512mb のメモリーが割り当てられています。これは、<agent-manager-directory>/var/conf/launcher-custom.yml ファイルの内容を調べることで確認できます。このファイルの Xmx の値が、Agent Manager に割り当てられているメモリー量です。
Windows マシンにインストールされた Agent は launcher-custom.yml ファイルを使用しないため、デフォルトでは、Java は Agent Manager と Bootstrapper の各プロセスに、システムで利用可能な総メモリーの25%を割り当てます。これを修正するには、Agent Manager と Bootstrapper のヒープサイズを手動で設定する必要があります。以下の手順で設定できます。
setx -m JAVA_HOME "{BOOTVISOR_INSTALL_DIR}\jdk\{JDK_VERSION}-win_x64\"setx -m MAGRITTE_BOOTVISOR_WIN_OPTS "-Xmx512M -Xms512M"setx -m MAGRITTE_BOOTSTRAPPER_OPTS "-Xmx512M -Xms512M".\service\bin\magritte-bootvisor-winホストで利用可能なメモリー量と、上記の各サブプロセスに割り当てられているメモリー量を特定したら、上記のプロセスに割り当てるメモリー量を減らすか、ホストで利用可能なメモリー量を増やすかを判断します。
Agent プロセスで使用するメモリー量を安全に減らせるかどうかは、Agent の設定(たとえば、同時同期の最大数やファイルアップロードの並列度)、同期するデータの種類、および Agent の通常の負荷によって異なります。ヒープサイズを小さくすると、OS がプロセスを強制終了する可能性は低くなりますが、Java プロセスのヒープ領域が不足する可能性は高くなります。適切な値を見つけるには、異なる値を試す必要がある場合があります。この値の調整について支援が必要な場合は、Palantir の担当者にお問い合わせください。
1個または複数のサブプロセスに割り当てられるメモリー量を減らすには、次の手順を実行します。
jvmHeapSize パラメーターを設定できます。Copied!1 2 3agent: .... jvmHeapSize: 3g #This is jvm heap size value
デフォルトのヒープ割り当て
デフォルトでは、Agent は約3 GB のメモリーを必要とし、次のように割り当てられます。
Java プロセスはオフヒープメモリーも使用するため、これらのプロセス用に少なくとも4 GB の空きメモリーを確保することを推奨します。
Agent のダウンロードが失敗する主な原因は、ネットワーク接続とリンクの期限切れの2つです。
Foundry に接続できるものの、ダウンロードした tar.gz ファイルが無効である場合や、ダウンロード時にエラーメッセージが表示される場合は、リンクが期限切れになっているか、無効化されている可能性があります。
Agent パッケージのダウンロード中に disconnected unexpectedly エラーが発生する場合は、ダウンロードコマンドに --http1.0 フラグを追加して、curl が HTTP 1.0 を使用するように強制してみてください。これにより、特定のネットワーク環境で発生する可能性があるプロトコルネゴシエーションの問題を解決できる場合があります。
プロジェクト内に Agent を作成するには、そのプロジェクトの編集者である必要がありますが、プロジェクト内の Agent を管理するには、そのプロジェクトの所有者である必要があります。そのため、Agent を作成できても、その Agent のダウンロードリンクの生成や、その他の管理タスクを実行できない場合があります。Agent の権限の詳細については、権限リファレンスのドキュメントを参照してください。
Agent を作成しようとしたときに PERMISSION_DENIED エラーが発生する場合は、次の点を確認してください。
既存のプロジェクトに対する編集者権限のみを持ち、必要な組織レベルのロールがない場合は、適切な権限を持つ別のプロジェクトで Agent を作成するか、管理者に必要なロールをリクエストしてみてください。
Agent の権限の詳細については、権限リファレンスのドキュメントを参照してください。
TLSv.1.0 および TLSv1.1 は、古く安全でないプロトコルであるため、Palantir では対応していません。Data Connection Agent が使用する OpenJDK の Amazon Corretto ビルドでは、java.security ファイルの jdk.tls.disabledAlgorithms セキュリティプロパティで、TLSv1.0 および TLSv1.1 がデフォルトで明示的に無効化されています。
TLSv1.0 および TLSv1.1 のみに対応するデータソースシステムに接続しようとすると、Error: The server selected protocol version TLS10 is not accepted by client preferences などのさまざまなエラーで失敗します。
非推奨の TLS バージョンの使用は強く推奨しません。その使用に伴うセキュリティリスクについて、Palantir は責任を負いません。
TLSv1.0 および TLSv1.1 に一時的に対応することがどうしても必要な場合は、次のステップを実行します。
agent と explorer の両方の設定ブロックに tlsProtocols エントリーを追加し、その後に有効にするプロトコルを指定します。TLSv1.2 を使用しているソースが動作しなくならないよう、TLSv1.2 も必ず含めてください。例:Copied!1 2 3 4 5 6 7 8 9 10 11 12agent: tlsProtocols: - TLSv1 - TLSv1.1 - TLSv1.2 ... explorer: tlsProtocols: - TLSv1 - TLSv1.1 - TLSv1.2 ...

この設定により、Agent のアップグレードや再起動後も、Agent は引き続き TLSv1.0 および TLSv1.1 を許可します。データソースが新しい TLS バージョンに移行したら、Agent の詳細設定に加えたすべての変更を元に戻してください。
Agent のホストマシン上でのログストレージ設定を調整するには、次のステップに沿って進めます。
これで、新しい設定が反映されているはずです。
Agent が利用できなくなる理由はいくつかあります。たとえば、Agent が再起動中である場合や、Agent が稼働しているハードウェアがオフラインまたは再起動中である場合があります。
Agent が最初に利用できなくなった時点を確認する方法は2つあります。
ファイルは、Bootvisor が古いプロセスフォルダーをクリーンアップするまでディスク上に残ります(30日が経過するか、古いフォルダーが10個になるとクリーンアップが実行されます)。これらのファイルは暗号化されており、復号するためのキーは、終了したプロセスのメモリー内にのみ存在していました。