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

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

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

Agent Managerは、インストールされているサーバー上で「bootvisor」と呼ばれています。

このページでは、エージェントログの設定方法、エージェント設定の一般的な問題、およびデバッグのガイダンスについて説明しています。

エージェントおよびエージェントマネージャーが「オフライン」状態を示すが、エージェントホストで「実行中」を返す
エージェントマネージャーが「オフライン」状態を示す
ブートストラッパーが「未報告」状態を示す
エージェントが「オンライン」を示すが、再起動に応答しない
エージェントのステータスが「Unhealthy」を表示する
エージェントパッケージをダウンロードできない
エージェントを管理できない
Windowsマシン上のエージェントの問題
セキュリティの低い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-directory>/var/conf/install.yml ファイルの内容を確認し、「port」パラメーター（例：port: 1234 - ここで1234はポート）を探すことで行うことができます。ポートパラメーターが定義されていない場合、エージェントマネージャーはデフォルトのポート7032を使用します。
  - エージェントマネージャーがバインドしようとしているポートがわかったら、すでにそのポートで実行されているプロセスを特定する必要があります。これは、次のコマンドを実行することで実現できます： ps aux | grep $(lsof -i:<PORT> |awk 'NR>1 {print $2}' |sort -n |uniq) ここで <PORT> は、エージェントマネージャーがバインドしようとしているポートです。
    - 上記のコマンドが返す応答に com.palantir.magritte.bootvisor.BootvisorApplication が含まれている場合、別のエージェントマネージャーがすでに実行されていることを意味します。
    - この場合、これが意図的であるかどうかを判断する必要があります。意図的である場合は、下記の手順に従って、2つのエージェントマネージャーのポートをデコンフリクトするように設定を変更する必要があります。そうでない場合は、このホストで使用する特定のエージェントマネージャーインストールを決定し、他の実行中のものをすべて停止し、今後使用する予定のものだけを起動する必要があります。
- BindException エラーを修正するには、使用されていない新しいポートをエージェントマネージャー用に見つける必要があります。
  - ポート番号は1025から65536の間である必要があります（ポート番号0から1024は、特権サービス用に予約されており、よく知られたポートとして指定されています）。
  - 選択したポート番号でプロセスがすでに実行されているかどうかを確認するには、次のコマンドを実行します： lsof -i :<PORT> ここで <PORT> は選択したポート番号です。
- 利用可能なポートが見つかったら、<agent-manager-directory>/var/conf/install.yml に保存されている設定で port パラメーターを追加（または更新）する必要があります。
- 以下は、ポートが 7032 に設定された例の エージェントマネージャー設定スニペット です。
```
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-directory>/var/data/processes/<latest-bootstrapper-directory>/var/log/startup.log ファイルの内容を確認してください。
- 以下のエラーが表示された場合： Caused by: java.net.BindException: {} Address already in use、これは、ブートストラッパーがバインドしようとしているポートですでにプロセスが実行されていることを意味します。
  - これを解決するには、まずブートストラッパーがどのポートにバインドしようとしているかを確認する必要があります。これは、Data Connectionアプリ内のエージェント概要ページに移動することで行うことができます。そこから、「詳細設定」ボタンを選択し、最後に「ブートストラッパー」タブをクリックします。ブートストラッパーがバインドしようとするポートは、port パラメーターで定義されています（例：port: 1234 - ここで1234はポート）。ブートストラッパーのデフォルトポートは7002です。
  - ブートストラッパーがバインドしようとしているポートがわかったら、すでにそのポートで実行されているプロセスを特定する必要があります。これは、次のコマンドを実行することで実現できます： ps aux | grep $(lsof -i:$PORT |awk 'NR>1 {print $2}' |sort -n |uniq) ここで $PORT は、ブートストラッパーがバインドしようとしているポートです。
    - 上記のコマンドが返す応答に com.palantir.magritte.bootstrapper.MagritteBootstrapperApplication が含まれている場合、別のブートストラッパーがすでに実行されていることを意味します。
    - この場合、これが意図的であるかどうかを判断する必要があります。意図的である場合は、下記の手順に従って、2つのブートストラッパーのポートをデコンフリクトするように設定を変更する必要があります。そうでない場合は、このホストで使用する特定のブートストラッパーインストールを決定し、他の実行中のものをすべて停止し、今後使用する予定のものだけを起動する必要があります。
- BindException エラーを修正するには、使用されていない新しいポートをブートストラッパー用に見つける必要があります。
  - ポート番号は1025から65536の間である必要があります（ポート番号0から1024は、特権サービス用に予約されており、よく知られたポートとして指定されています）。
  - 選択したポート番号でプロセスがすでに実行されているかどうかを確認するには、次のコマンドを実行します： lsof -i :<PORT> ここで <PORT> は選択したポート番号です。
- 利用可能なポートが見つかったら、ブートストラッパーの設定で port パラメーターを設定する必要があります。これは、Data Connectionアプリ内のエージェント概要ページに移動することで行うことができます。そこから詳細設定ボタンを選択し、最後に「ブートストラッパー」タブに移動します。
- 以下は、ポートが 7002 に設定された例の ブートストラッパー設定スニペット です。
```
Copied!1
2
3
4
server:
  adminConnectors:
    ...
    port: 7002 #これがポートの値です
```
- 設定を更新したら、変更を保存し、効果を適用するためにエージェントを再起動する必要があります。

エージェントが「オンライン」を示すが、再起動に応答しない

これは、通常、「ゴースト」のエージェントインスタンスが実行されているためであり、それを見つけてシャットダウンする必要があります。

古いプロセスを見つけて終了するには、以下の手順に従ってください。

エージェントマネージャーを停止します。<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-install-location>/service/bin/init.sh start）。

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

エージェントのステータスが「Unhealthy」を表示する

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

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

エージェントまたはエクスプローラーサブプロセスがオペレーティングシステムによってOOMキルされたかどうかを確認するには、次のコマンドを実行します。 grep "exited with return code 137" -r <agent-manager-directory> --include=*.log。このコマンドは、エージェントマネージャーディレクトリ内のすべてのログファイルを検索し、'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ディストリビューションとシステム構成によって異なる場合があります）。
このシナリオでは、キルされたプロセスがエージェントに関連しているかどうかを確認しようとする必要があります。これを行う最も簡単な方法は、タイムスタンプを一致させることです。つまり、エントリのタイムスタンプがエージェントが不健康になった時間と一致している場合、それらは相関している可能性が高いです。注：(java) が含まれていないエントリは無視できます。これらはエージェントと関連していません。

ヒープサイズの調整

ヒープ割り当てを変更する前に、まず次のことを行ってください。

ホストが使用可能なメモリの量を計算します。
ホストが使用可能なメモリの量を確認するには、free -h を実行します。6 GBのシステムでは、出力は次のようになることがあります。

Copied!1
2
3
                total        used        free      shared  buff/cache   available
Mem:          5.8Gi       961Mi       2.8Gi       9.0Mi       2.1Gi       4.6Gi # メモリ: 合計 5.8Gi、使用中 961Mi、空き 2.8Gi、共有 9.0Mi、バッファ/キャッシュ 2.1Gi、利用可能 4.6Gi
Swap:         1.0Gi          0B       1.0Gi # スワップ: 合計 1.0Gi、使用中 0B、空き 1.0Gi

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

以下のサブプロセスにそれぞれどれだけのメモリが割り当てられているかを決定します。エージェントマネージャー、ブートストラッパー、エージェント、エクスプローラー。

エージェントとエクスプローラーのサブプロセスに割り当てられているメモリの量を調べるには、Data Connectionアプリ内のエージェント設定ページに移動し、詳細設定ボタンをクリックし、"Bootstrapper"タブを選択する必要があります。そこで、各サブプロセスが独自の設定ブロックを持っていることがわかります。各ブロック内には、関連するプロセスに割り当てられたメモリの量を定義するjvmHeapSizeパラメーターが表示されます。

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

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

Windowsマシンにインストールされたエージェントは、launcher-custom.ymlファイルを使用せず、デフォルトでJavaはエージェントマネージャーとブートストラッパープロセスにシステムが利用可能な合計メモリの25%を割り当てます。これを修正するには、以下の手順でエージェントマネージャーとブートストラッパーのヒープサイズを手動で設定する必要があります。

すべてのエージェントプロセス（エージェントマネージャー、ブートストラッパー、エージェント、エクスプローラー）を終了してください。
JAVA_HOMEを設定します：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

ホストが利用可能なメモリの量と、上記のサブプロセスに割り当てられているメモリの量を確認したら、次に行うべきことは：上記のプロセスに割り当てられたメモリの量を減らすか、ホストに利用可能なメモリの量を増やすかを決定します。

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

サブプロセスのうち1つ（または複数）に割り当てられたメモリの量を減らすには、以下の操作を行います。

上記のサブプロセスにそれぞれどれだけのメモリを割り当てるべきかを決定します。
- 注：ヒープサイズをデフォルト以下に減らすことはお勧めしません。デフォルトは以下にリストされています。
次に、Data Connection内のエージェントに移動し、詳細設定ボタンをクリックし、"Bootstrapper"タブを選択します。
ここで、個々のサブプロセスのjvmHeapSizeパラメーターを設定できます。
以下は、エージェント jvmHeapSizeを3GBに設定したブートストラッパー設定スニペットの例です。
```
Copied!1
2
3
agent:
    ....
    jvmHeapSize: 3g #これがjvmヒープサイズの値です
```
設定を更新したら、変更を保存し、エージェントを再起動して変更を反映させる必要があります。

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

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

エージェントサブプロセスに1GB
エクスプローラーサブプロセスに1GB
ブートストラッパーサブプロセスに512MB
エージェントマネージャーサブプロセスに512MB

Javaプロセスはヒープ外メモリも使用するため、少なくとも≥4GBの空き容量があることを確認してください。

エージェントパッケージをダウンロードできない

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

Foundryに接続できるが、ダウンロードで無効なtar.gzファイルやエラーメッセージが表示される場合は、期限切れか無効化されたリンクが原因かもしれません。

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

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

ユーザーは、プロジェクトのエディタである場合、そのプロジェクト内でエージェントを作成できますが、プロジェクトのオーナーである場合にのみ、そのプロジェクト内のエージェントを管理できます。つまり、ユーザーがエージェントを作成しても、エージェントのダウンロードリンクを生成したり、エージェントに関する他の管理タスクを実行したりすることができない場合があります。エージェントの権限に関する詳細は、権限リファレンスのガイダンスを参照してください。

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

TLSv.1.0およびTLSv1.1は、時代遅れで不安全なプロトコルであるため、Foundryではサポートされていません。Azul ZuluのOpenJDK 11.0.14ビルドでは、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を一時的にサポートする必要がある場合は、以下の手順を実行してください。

ブートバイザーにバンドルされているJDKのjava.securityファイルを探します。このファイルは、<bootvisor-directory>/jdk/<jdk-directory>/conf/security/java.securityにあるはずです。
java.securityファイルをブートバイザーディレクトリの外側の別の場所にコピーし（ファイルがブートバイザーのアップグレード時に上書きまたは削除されないようにするため）、/opt/palantir/tls-override/tls-overrides.java.securityのような名前に変更します。
コピーしたtls-overrides.java.securityファイルで、jdk.tls.disabledAlgorithmsプロパティを見つけ、その値からTLSv1とTLSv1.1を削除します。ファイルを保存します。
インターフェースのエージェントjvmArguments設定を、エージェント設定 > 設定 > 詳細 > ブートストラッパーの下に探します。エージェントとエクスプローラーの既存のjvmArgumentsに、次のJVM引数を追加します：-Djava.security.properties=/opt/palantir/tls-overrides/tls-overrides.java.security（オーバーライドファイルが作成された適切なパスを入力）。
UIからエージェントを再起動します。

これらの手順により、エージェントはエージェントのアップグレードを通じてTLSv1.0およびTLSv1.1を引き続き許可します。データソースが新しいTLSバージョンに移行したら、オーバーライドファイルとJVM引数を削除してください。

エージェントログの設定

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

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

新しい設定が適用されるはずです。