データ接続と統合概要エージェントおよびデータ接続トラブルシューティングリファレンス

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

トラブルシューティングリファレンス

Agent Manager は、インストールされたサーバーで "bootvisor" と呼ばれます。

このページには、エージェントログの設定方法に関する情報、エージェント設定に関する一般的な問題の説明、およびデバッグのガイダンスが含まれています。記載されている手順は、エージェントがインストールされたホストにSSH接続した後に実行する必要があります。追加のトラブルシューティングトピックを確認する前に、まず./var/diagnostic/launch.ymlを確認して、エージェントがFoundryに正常に接続されたかどうかを確認することをお勧めします。接続が成功しなかった場合は、enhancedMessageフィールドに記載されている指示に従ってください。

エージェント設定に関する一般的な問題

エージェントとエージェントマネージャーが「オフライン」ステータスを示しているが、エージェントホストでは「実行中」と表示される
エージェントマネージャーが「オフライン」ステータスを示す
Bootstrapperが「報告なし」ステータスを示す
エージェントが「オンライン」と表示されるが、再起動に応答しない
エージェントステータスが「不健康」と表示される
エージェントパッケージをダウンロードできない
エージェントを管理できない

エージェント設定リファレンス

TLSv1.0およびTLSv1.1プロトコルを使用してデータソースに接続する
エージェントログの設定
エージェントがインストールされているホストがクラッシュした場合、キャッシュされたファイルはどうなりますか？

エージェント設定に関する一般的な問題

エージェントとエージェントマネージャーが「オフライン」ステータスを示しているが、エージェントホストでは「実行中」と表示される

最初のステップは、エージェントがインストールされたホストからFoundryにアクセスできることを確認することです。これを行うには、エージェントがインストールされたホストから次のコマンドを実行します: curl -s https://<your domain name>/magritte-coordinator/api/ping > /dev/null && echo pass || echo fail.
- すべてが正常に動作している場合、出力としてpassが表示されます。この場合、以下を行う必要があります:
  - Foundryにアクセスするためにプロキシが必要かどうかを確認し、必要な場合はエージェントがプロキシを使用するように設定されているかどうかを確認します（エージェントがプロキシを使用するように設定する方法についてはプロキシ設定ページを参照してください）。Unixベースのマシンのコマンドラインでecho $http_proxyを実行することで、プロキシが使用されているかどうかを確認できます。
  - プロキシが必要ないと思う場合、またはすでに設定されている場合は、Palantirの担当者に連絡してください。
- ホストからFoundryにアクセスできない場合、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がバインドしようとしているポートを確認する必要があります。これは<agent-manager-directory>/var/conf/install.ymlファイルの内容を確認し、portパラメーターを探すことで行えます（例：port: 1234 - ここで1234がポートです）。ポートパラメーターが定義されていない場合、Agent Managerはデフォルトポート7032を使用します。
  - Agent Managerがバインドしようとしているポートを確認したら、そのポートですでに実行されているプロセスを特定する必要があります。これは次のコマンドを実行することで行えます: ps aux | grep $(lsof -i:<PORT> |awk 'NR>1 {print $2}' |sort -n |uniq)。ここで<PORT>はAgent Managerがバインドしようとしているポートです。
    - 上記のコマンドの応答にcom.palantir.magritte.bootvisor.BootvisorApplicationが含まれている場合、別のAgent Managerがすでに実行されています。
    - この場合、これが意図的であるかどうかを判断する必要があります。意図的である場合、2つのAgent Managerの競合を解消するために構成でポートを変更する必要があります。そうでない場合、このホストで使用する特定のAgent Managerインストールを決定し、他に実行されているものを停止し、今後使用するものだけを起動します。
- BindExceptionエラーを修正するには、Agent Manager用の新しいポートを見つける必要があります。
  - ポート番号は1025から65536の間である必要があります（ポート番号0から1024は特権サービスおよび既知のポートとして指定されています）。
  - プロセスがすでにポートで実行されているかどうかを確認するには、次のコマンドを実行します: lsof -i :<PORT>。ここで<PORT>は選択したポート番号です。
- 利用可能なポートを見つけたら、構成にportパラメーターを追加（または更新）する必要があります。構成は<agent-manager-directory>/var/conf/install.ymlに保存されています。
- 以下は、ポートを7032に設定したAgent Managerの構成スニペットの例です:
```
Copied!1
2
3
...
port: 7032
auto-start-agent: true
```
- 上記の構成を保存したら、次のコマンドを実行してAgent Managerを再起動します: <agent-manager-root>/service/bin/init.sh stop && <agent-manager-root>/service/bin/init.sh start。

Bootstrapperが「報告なし」ステータスを示す

<agent-manager-directory>/var/data/processes/<latest-bootstrapper-directory>/var/log/startup.logファイルの内容を確認します。
- 次のエラーが表示された場合: Caused by: java.net.BindException: {} Address already in use、これはBootstrapperがバインドしようとしているポートですでにプロセスが実行されていることを意味します。
  - これを解決するために、まずBootstrapperがバインドしようとしているポートを確認する必要があります。これはData Connectionアプリケーション内のエージェント概要ページに移動することで行えます。そこから「詳細」構成ボタンを選択し、最後に「Bootstrapper」タブをクリックします。Bootstrapperがバインドしようとしているポートはportパラメーターの下に定義されています（例：port: 1234 - ここで1234がポートです）。Bootstrapperのデフォルトポートは7002です。
  - Bootstrapperがバインドしようとしているポートを確認したら、そのポートですでに実行されているプロセスを特定する必要があります。これは次のコマンドを実行することで行えます: ps aux | grep $(lsof -i:$PORT |awk 'NR>1 {print $2}' |sort -n |uniq)。ここで$PORTはBootstrapperがバインドしようとしているポートです。
    - 上記のコマンドの応答にcom.palantir.magritte.bootstrapper.MagritteBootstrapperApplicationが含まれている場合、別のBootstrapperがすでに実行されています。
    - この場合、これが意図的であるかどうかを判断する必要があります。意図的である場合、2つのBootstrapperの競合を解消するために構成でポートを変更する必要があります。そうでない場合、このホストで使用する特定のBootstrapperインストールを決定し、他に実行されているものを停止し、今後使用するものだけを起動します。
- BindExceptionエラーを修正するには、Bootstrapper用の新しいポートを見つける必要があります。
  - ポート番号は1025から65536の間である必要があります（ポート番号0から1024は特権サービスおよび既知のポートとして指定されています）。
  - プロセスがすでにポートで実行されているかどうかを確認するには、次のコマンドを実行します: lsof -i :<PORT>。ここで<PORT>は選択したポート番号です。
- 利用可能なポートを見つけたら、Bootstrapperの構成でportパラメーターを設定する必要があります。これはData Connectionアプリケーション内のエージェント概要ページに移動し、詳細構成ボタンを選択し、最後に「Bootstrapper」タブに移動することで行えます。
- 以下は、ポートを7002に設定したBootstrapperの構成スニペットの例です:
```
Copied!1
2
3
4
server:
  adminConnectors:
    ...
    port: 7002 #これはポートの値です
```
- 構成を更新したら、変更を保存し、エージェントを再起動して有効にする必要があります。

エージェントが「オンライン」と表示されるが、再起動に応答しない

ほとんどの場合、これはもう1つの「ゴースト」インスタンスが実行されているためです。これを見つけてシャットダウンする必要があります。

古いプロセスを見つけて終了するには、以下の手順に従います:

次のコマンドを実行してAgent Managerを停止します: <agent-manager-install-location>/service/bin/init.sh stop.
<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.
Data Connectionに戻り、エージェントが報告を停止したことを確認します（2-3分かかります）。
Agent Managerを起動します（<agent-manager-install-location>/service/bin/init.sh start）。

ホストで手動でエージェントを起動する（Data Connectionを通じてではなく）と、「ゴースト」プロセスが作成される可能性があります。

エージェントステータスが「不健康」と表示される

多くの場合、エージェントプロセスが「不健康」と表示されるのは、クラッシュしたか、オペレーティングシステムまたはアンチウイルスなどの他のソフトウェアによってシャットダウンされたためです。

オペレーティングシステムがプロセスをシャットダウンする理由はいくつかありますが、最も一般的なのはオペレーティングシステムに実行するための十分なメモリがないためです。これはOOM（Out Of Memory）キルと呼ばれます。

オペレーティングシステムによってエージェントまたはExplorerサブプロセスがOOMキルされたかどうかを確認するには、次のコマンドを実行します: grep "exited with return code 137" -r <agent-manager-directory> --include=*.log. これは、Agent Managerディレクトリ内のすべてのログファイルを検索し、'exited with return code 137'を含むエントリを探します（リターンコード137はプロセスがOOMキルされたことを示します）。

以下は、上記のコマンドによって生成された例外出力で、エージェントサブプロセスがOOMキルされていることを示しています: ./var/data/processes/bootstrapper~<>/var/log/magritte-bootstrapper.log:ERROR [timestamp] com.palantir.magritte.bootstrapper.ProcessMonitor: magritte-agent exited with return code 137. このような出力が表示された場合は、ヒープサイズの調整に関する以下の手順に従ってください。

また、次のコマンドを実行してOOMキルエントリのオペレーティングシステムログを確認することもできます: dmesg -T | egrep -i 'killed process. このコマンドは、'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
上記のログ行は、プロセスキルされたプロセスがPID 9423であることを示しています（注：ログメッセージはLinuxディストリビューションやシステム構成によって異なる場合があります）。
このシナリオでは、キルされたプロセスがエージェントに関連しているかどうかを確認する必要があります。最も簡単な方法はタイムスタンプを一致させることです。つまり、エントリのタイムスタンプがエージェントが不健康になった時間と一致する場合、2つが関連している可能性が高いです。（java）が含まれていないエントリは無視してもかまいません。

ヒープサイズの調整

ヒープ割り当てを変更する前に、まず以下を行う必要があります:

ホストに利用可能なメモリがどれだけあるかを計算します。
ホストにどれだけのメモリが利用可能かを確認するには、free -hを実行します。6GBシステムの場合、出力は次のようになるかもしれません:

Copied!1
2
3
4
5
6
7
                total        used        free      shared  buff/cache   available
Mem:          5.8Gi       961Mi       2.8Gi       9.0Mi       2.1Gi       4.6Gi
# Mem: メモリについての情報。totalは合計メモリ、usedは使用中のメモリ、freeは空きメモリ、
# sharedは共有メモリ、buff/cacheはバッファおよびキャッシュに使用されているメモリ、
# availableはアプリケーションが使用可能なメモリ。
Swap:         1.0Gi          0B       1.0Gi
# Swap: スワップについての情報。totalは合計スワップ領域、usedは使用中のスワップ領域、freeは空きスワップ領域。

free コマンドによって生成された出力では、available 列が新しいアプリケーションの起動に使用できるメモリの量を示します。エージェントに割り当てられるメモリ量を特定するために、エージェントを停止し、システムが通常から高負荷の状態にある間に free -h を実行することをお勧めします。available の値は、すべてのエージェントプロセスに割り当てることができる最大メモリ量を示します。他のプロセスがさらに多くのメモリを必要とする場合や、エージェントプロセスによるオフヒープメモリ使用を考慮して、可能であれば約 2 ～ 4GB のバッファを残すことをお勧めします。すべての free のバージョンが available 列を表示するわけではないので、システムのバージョンに関するドキュメントを確認して同等の情報を見つける必要があるかもしれません。

以下のサブプロセスごとに割り当てられたメモリ量を特定してください：Agent Manager、Bootstrapper、agent、および Explorer。

エージェントおよび Explorer サブプロセスに割り当てられたメモリ量を確認するには、Data Connection 内のエージェント設定ページに移動し、高度な設定ボタンを選択して「Bootstrapper」タブを選びます。そこから、各サブプロセスにはそれぞれの設定ブロックがあり、各ブロック内に関連するプロセスに割り当てられたメモリ量を定義する jvmHeapSize パラメーターが表示されます。

デフォルトでは、Bootstrapper サブプロセスには 512mb のメモリが割り当てられています。これは、まず <agent-manager-directory>/var/data/processes/ ディレクトリに移動し、ls -lrt を実行して最新の bootstrapper~<uuid> ディレクトリを見つけることで確認できます。最新の bootstrapper~<uuid> ディレクトリに移動したら、./var/conf/launcher-custom.yml ファイルの内容を確認できます。ここで、Xmx の値が Bootstrapper に割り当てられたメモリ量です。

デフォルトでは、Agent Manager サブプロセスにも 512mb のメモリが割り当てられています。これは、<agent-manager-directory>/var/conf/launcher-custom.yml ファイルの内容を確認することで確認できます。ここで、Xmx の値が Agent Manager に割り当てられたメモリ量です。

Windows マシンにインストールされたエージェントは launcher-custom.yml ファイルを使用しないため、デフォルトでは Java が Agent Manager および Bootstrapper プロセスにシステムの総メモリの 25% を割り当てます。これを修正するには、以下の手順に従って手動で Agent Manager および Bootstrapper のヒープサイズを設定する必要があります：

すべてのエージェントプロセス (Agent Manager、Bootstrapper、agent、および Explorer) を終了させることを確認してください。
JAVA_HOME を設定する: setx -m JAVA_HOME "{BOOTVISOR_INSTALL_DIR}\jdk\{JDK_VERSION}-win_x64\"
Agent Manager のヒープサイズを設定する: setx -m MAGRITTE_BOOTVISOR_WIN_OPTS "-Xmx512M -Xms512M"
Bootstrapper のヒープサイズを設定する: setx -m MAGRITTE_BOOTSTRAPPER_OPTS "-Xmx512M -Xms512M"
コマンドプロンプトを閉じ、新しいものを開く。これにより、上記の設定が反映されます。
Agent Manager を起動する: .\service\bin\magritte-bootvisor-win

ホストが使用可能なメモリ量と、上記のサブプロセスごとに割り当てられたメモリ量を確認したら、上記のプロセスに割り当てるメモリ量を減らすか、ホストに使用可能なメモリ量を増やすかを決定する必要があります。

エージェントプロセスに使用するメモリ量を安全に減らすことができるかどうかは、エージェントの設定 (たとえば、最大同時同期数およびファイルアップロード並列性) や同期されるデータの種類、エージェントの通常の負荷に依存します。ヒープサイズを減らすと、OS がプロセスを終了させる可能性が低くなりますが、Java プロセスがヒープスペースを使い果たす可能性が高くなります。動作する値を見つけるために、異なる値をテストする必要があるかもしれません。この値の調整に関して支援が必要な場合は、Palantir の担当者に連絡してください。

1 つ (または複数) のサブプロセスに割り当てられたメモリ量を減らすには、以下の手順を実行します：

上記のサブプロセスごとに割り当てるべきメモリ量を決定します。
- 注: デフォルト値よりもヒープサイズを小さくすることはお勧めしません。以下にデフォルト値が記載されています。
次に、Data Connection 内のエージェントに移動し、高度な設定ボタンを選択して、Bootstrapper タブを選びます。
ここで、各サブプロセスごとに jvmHeapSize パラメーターを設定できます。
以下は、agent の jvmHeapSize を 3gb に設定した例の Bootstrapper 設定スニペット です：
```
Copied!1
2
3
agent:
    ....
    jvmHeapSize: 3g #This is jvm heap size value
```
設定を更新したら、変更を保存し、エージェントを再起動して有効にします。

デフォルトのヒープ割り当て

デフォルトでは、エージェントには約 3gb のメモリが必要で、以下のように割り当てられます：

agent サブプロセスに 1gb
Explorer サブプロセスに 1gb
Bootstrapper サブプロセスに 512mb
agent Manager サブプロセスに 512mb

Java プロセスはオフヒープメモリも使用するため、少なくとも 4gb 以上のメモリを確保することをお勧めします。

エージェントパッケージのダウンロードに失敗

エージェントのダウンロードが失敗する主な原因は、ネットワーク接続と期限切れのリンクです。

Foundry に接続できるが無効な tar.gz ファイルを受け取るか、ダウンロード時にエラーメッセージが表示される場合、リンクが期限切れまたは無効化されている可能性があります。

期限切れのリンク: ダウンロードリンクは 10 分後に期限切れになります。
無効化されたリンク: ダウンロードリンクは一度だけダウンロードできるシークレットで保護されています。Microsoft Teams などのアプリケーションにエージェントのダウンロードリンクを貼り付けると、これらのアプリケーションがリンクをプレビューできるかどうかを確認しようとするため、リンクが無効になります。無効なリンクがある場合は、UI でリンクを再生成し、リンク全体をコピーするのではなく、2 つのシークレットワードを手入力してください。

エージェントを管理できない

ユーザーは、プロジェクト内でエージェントを作成するにはそのプロジェクトのエディターである必要がありますが、そのプロジェクト内のエージェントを管理するにはプロジェクトのオーナーである必要があります。つまり、ユーザーはエージェントを作成することはできても、ダウンロードリンクを生成したり、エージェントに対して他の管理タスクを実行したりすることができない場合があります。エージェントの権限について詳しくは、permissions reference ドキュメントのガイダンスを確認してください。

エージェント設定リファレンス

TLSv1.0 および TLSv1.1 プロトコルを使用してデータソースに接続する

TLSv1.0 および TLSv1.1 は時代遅れで安全ではないプロトコルであるため、Palantir ではサポートしていません。Data Connection エージェントで使用される 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 settings に移動し、Manage Configuration セクションの Advanced を選択します。次に、Bootstrapper タブを選択します。
agent および explorer 設定ブロックの両方に tlsProtocols エントリを追加し、有効にしたいプロトコルを続けて入力します。TLSv1.2 も含めて、使用するすべてのソースが問題なく動作するようにします。たとえば：

Copied!1
2
3
4
5
6
7
8
9
10
11
12
agent:
    tlsProtocols:
      - TLSv1       # TLSv1 は、セキュリティプロトコルです
      - TLSv1.1     # TLSv1.1 は、セキュリティプロトコルのアップデートされたバージョンです
      - TLSv1.2     # TLSv1.2 は、さらにアップデートされたセキュリティプロトコルです
...
explorer:
    tlsProtocols:
      - TLSv1       # TLSv1 は、セキュリティプロトコルです
      - TLSv1.1     # TLSv1.1 は、セキュリティプロトコルのアップデートされたバージョンです
      - TLSv1.2     # TLSv1.2 は、さらにアップデートされたセキュリティプロトコルです
...

Agent with custom legacy TLS protocols configured

Restart agent を選択します。

この設定により、エージェントはTLSv1.0およびTLSv1.1をエージェントのアップグレードおよび再起動にわたって許可し続けます。データソースが新しいTLSバージョンに移行したら、高度なエージェント設定で行ったすべての変更を元に戻します。

エージェントログの設定

ホストマシン上のエージェントのログ保存設定を調整するには、以下の手順に従います。

Data Connectionで、Agents ページに移動します。設定したいエージェントの名前を選択します。
設定パネルで、Advanced を選択します。
ログの設定オプションは、Logging ブロックの下にあります。ここで、ログの破棄を開始するタイミング、ログのアーカイブ方法、その他の設定を構成できます。
- 設定は、割り当てられたエージェントホストマシンのリソース、ログレベルの詳細度の好み、およびログ保持の好みを考慮する必要があります。詳細情報とガイダンスについては、Dropwizard configuration reference ↗を参照してください。
画面の右上隅にある Restart Agent を選択して、Foundryでエージェントを再起動します。

新しい設定が有効になっているはずです。

エージェントがインストールされているホストがクラッシュした場合、キャッシュされたファイルはどうなりますか？

ファイルは、Bootvisorが古いプロセスフォルダーをクリーンアップするまで（30日または10個の古いフォルダーがトリガーとなる）ディスクに残ります。これらのファイルは暗号化されており、それらを復号化するキーは終了したプロセスのメモリにのみ存在していました。