バッチプログラムモニタリング

バッチアプリケーションにWhaTapエージェントを適用するためのインストールおよび設定手順を説明します。

Batch Application

バッチモニタリングの構成

バッチアプリケーションはWASとは異なり、実行と停止を繰り返します。そのため、バッチモニタリングは次の2つのプロセスに分かれています。

プロセス	役割	実行単位
バッチホスト(Batch Host)	バッチエージェントから受け取ったデータを収集サーバーに送信	ホストごとに1つ
バッチエージェント(Batch Agent)	バッチジョブのデータを収集してバッチホストに送信	バッチジョブごとに1つ

2つのプロセスはUDPで通信します。この構成により、複数のバッチジョブを並列に実行できます。バッチホストとバッチエージェントは、バッチジョブを実行するサーバーに一緒にインストールしてください。

通信要件

経路	プロトコル/ポート
バッチホスト → 収集サーバー	TCP 6600(アウトバウンド)
バッチエージェント → バッチホスト	UDP 6611

Batch Job UDP

バッチプログラムモニタリングはJavaモニタリングの付加機能ですが、Javaモニタリングエージェントとは別に動作する独立したシステムです。Javaエージェントの設定オプションはバッチモニタリングには適用されません。この文書に記載したオプションのみ使用してください。Javaエージェントでprofile_接頭辞を使うオプションは、バッチプログラムではtrace_接頭辞を使います。

エージェントのダウンロード

次のコマンドを実行して、バッチアプリケーションモニタリング用のエージェントをダウンロードしてください。

wget https://api.whatap.io/agent/whatap.agent.batch.tar.gz
tar xzf whatap.agent.batch.tar.gz

圧縮を解凍すると、次のように構成されます。

{BATCH_HOME}/
├── whatap.agent.batch.host-X.Y.Z.jar   バッチホスト
├── whatap.agent-X.Y.Z.jar              Javaエージェント
├── whatap.conf                         バッチホスト設定ファイル
└── agent/
    ├── whatap.agent.batch-X.Y.Z.jar    バッチエージェント
    └── whatap.conf                     バッチエージェント設定ファイル

whatap.confファイルがない場合は新しく作成した後、設定 > エージェントインストールメニューで確認できるlicenseとwhatap.server.host項目を追加してください。

設定ファイルの場所

注意

導入時に最も失敗しやすい部分です。必ず確認してください。

WhaTapは設定ファイルとログの場所をwhatap.homeを基準に決定します。whatap.homeが決まる方式は起動方法によって異なります。設定ファイルが見つからない場合、起動時のバナーにPCODE(0)が表示され、データを収集しません。

whatap.homeの決定方式

優先順位は次のとおりです。

-Dwhatap.homeを指定した場合は、常にその値が優先されます。
指定がない場合、-javaagentで起動したプロセス(バッチエージェント)はエージェントjarがあるディレクトリをwhatap.homeとして使用します。
-cpでメインクラスを指定して起動したプロセス(バッチホスト)は上記の自動設定が適用されないため、起動時点の作業ディレクトリがwhatap.homeになります。

プロセス	起動方法	whatap.home	読み込む設定ファイル
バッチホスト	`-cp` + メインクラス	作業ディレクトリ	作業ディレクトリの`whatap.conf`
バッチエージェント	`-javaagent`	エージェントjarがあるディレクトリ	jarと同じディレクトリの`whatap.conf`

注意

バッチホストは必ずインストールディレクトリに移動してから起動してください。ジョブスケジューラやジョブ管理製品から起動する場合、作業ディレクトリが想定と異なることがあります。起動スクリプト内で作業ディレクトリを明示的に移動してください。

バッチホストの設定

licenseとwhatap.server.hostのオプション値は、プロジェクトの設定 > エージェントインストールメニューで確認できます。

{BATCH_HOME}/whatap.conf
license=
whatap.server.host=
whatap.server.port=6600

Option	Default	Description
`license`	-	プロジェクトのアクセスキー
`whatap.server.host`	-	収集サーバーアドレス。二重化した場合はスラッシュ(/)で区切る。例) `10.0.0.1/10.0.0.2`
`whatap.server.port`	`6600`	収集サーバーポート

上記3項目だけで動作します。以降で説明するオプションは、必要な場合にのみ追加してください。

UDP受信の設定

バッチホストがバッチエージェントからデータを受け取るアドレスとポートです。

{BATCH_HOME}/whatap.conf
net_udp_listen_ip=0.0.0.0
net_udp_listen_port=6611

Option	Default	Description
`net_udp_listen_port`	`6611`	UDPデータを受け取るポート。既定ポートを他の用途で使う場合に変更
`net_udp_listen_ip`	`0.0.0.0`	UDPデータを受け取るためにバインドするIPアドレス。変更可能だが既定値を推奨

注意

UDPポートを変更する場合は、バッチホストとバッチジョブの両方を変更する必要があります。

変更対象	設定ファイル	オプション
受信側(バッチホスト)	`{BATCH_HOME}/whatap.conf`	`net_udp_listen_port`
送信側(バッチジョブ)	バッチジョブの`whatap.conf`	`net_udp_port`

片方だけ変更すると、エラーが表示されないままトランザクションデータを失います。バッチジョブは従来のポートに送信し続け、バッチホストは変更したポートでのみ待機するためです。変更後はバッチホストとバッチジョブの両方を再起動してください。

トレースステップ収集の設定

個別のトランザクショントレースは、ステップを無制限に収集できません。トランザクションごとに長さが制限されたバッファにトレースステップを保存し、既定の設定では1つのバッチジョブあたり1,000個まで収集します。

{BATCH_HOME}/whatap.conf
split_trace_enabled=false

Option	Default	Description
`split_trace_enabled`	`false`	トレースを分割して送信

注意

上限を超えたステップはトレースに表示されないまま欠落します。 トレース分析画面のステップ番号が1,000付近で途切れている場合がこれに該当します。

ステップ数が多いバッチジョブの処理内容をすべて取得する必要がある場合は、テクニカルサポートチームにお問い合わせください。

プロファイリング終了待機時間

バッチホストは実行中のジョブを定期的に点検し、一定時間ステップが届かないジョブのプロファイリングを強制終了します。

{BATCH_HOME}/whatap.conf
profile_expired_time=30000

Option	Default	Description
`profile_expired_time`	`30000`	最後のステップを受け取った時点からこの時間(ミリ秒)が経過するとプロファイリングを強制終了

バッチジョブが異常終了したときに、トランザクションが実行中の状態で残らないよう自動的に整理する機能です。強制終了したトランザクションにはlost-profileステップが記録されます。

外部システムの応答待ちなど、計測対象の処理が発生しない区間がこの時間を超えると、ジョブが正常に実行中であっても強制終了します。このような区間があるバッチジョブでは、実際の無入力区間より余裕のある値を設定してください。

バッチエージェントの設定

{BATCH_HOME}/agent/whatap.conf
net_udp_ip=127.0.0.1
net_udp_port=6611

job_name=sample-batch-job
time_limit=300000

trace_httpc_limit=1000000
trace_sql_limit=1000000

active_stack_enabled=true
active_stack_start_wait_time=1000
active_stack_time1=5000
active_stack_time2=10000

Option	Default	Description
`net_udp_ip`	`127.0.0.1`	データを送信するバッチホストのIPアドレス。同一サーバーで実行する場合は変更不要
`net_udp_port`	`6611`	データを送信するバッチホストのUDPポート。バッチホストの`net_udp_listen_port`と同じ値
`job_name`	-	バッチジョブを識別する名前。トランザクション名として表示。ジョブごとに固有の値を設定
`time_limit`	`300000`	遅延警告を表示するしきい値(ミリ秒)。ジョブを中断させる値ではない
`trace_httpc_limit`	`1000000`	バッチジョブ1件で収集するHTTP呼び出しの最大件数
`trace_sql_limit`	`1000000`	バッチジョブ1件で収集するSQLの最大件数
`active_stack_enabled`	`true`	アクティブスタックを収集するかどうか
`active_stack_start_wait_time`	`1000`	バッチジョブ開始後、最初のアクティブスタックを収集するまでの待機時間(ミリ秒)
`active_stack_time1`	`5000`	最初の5回までのアクティブスタック収集間隔(ミリ秒)
`active_stack_time2`	`10000`	6回目以降のアクティブスタック収集間隔(ミリ秒)

net_udp_ipとnet_udp_portは、バッチホストと同じサーバーで実行する一般的な構成であれば既定値で動作します。その他のオプションは必要な場合にのみ追加してください。

time_limitの設定

バッチジョブは通常は長時間実行され、ジョブごとに想定処理時間が異なります。ジョブごとにtime_limitを設定してください。

time_limitを設定すると、アクティブトランザクション画面の警告表示しきい値が自動的に計算されます。個別の設定は必要ありません。

経過時間	表示
`time_limit`の70%まで	既定の色
`time_limit`の70%超過	黄色
`time_limit`超過	赤色

Batch Job Time Limit

色の判定はジョブ全体の経過時間を基準にします。トレースを分割した場合も、区間ごとではなくジョブ全体の経過時間で判定します。

アクティブスタックの収集タイミング

バッチエージェントは、実行中のバッチジョブのスタックトレースを一定間隔で収集します。収集したアクティブスタックは、トレース分析画面でActiveStackステップとして確認できます。

active_stack_time1とactive_stack_time2はしきい値ではなく収集間隔です。既定値を基準にした収集タイミングは次のとおりです。

回数	収集時点	適用オプション
1回目	バッチジョブ開始後1秒	`active_stack_start_wait_time`
2回目 ~ 5回目	直前の収集から5秒間隔	`active_stack_time1`
6回目以降	直前の収集から10秒間隔	`active_stack_time2`

既定値で90秒間実行するバッチジョブでは、約12回のアクティブスタックを収集します。

収集間隔が切り替わる基準である5回は固定値であり、変更できません。変更できる項目はactive_stack_start_wait_time、active_stack_time1、active_stack_time2の3つの時間設定です。

active_stack_time1とactive_stack_time2の最小値は100ミリ秒です。100未満を設定しても100として適用されます。

アクティブスタックを収集しない場合は、active_stack_enabled=falseに設定してください。

収集件数の上限

バッチジョブ1件で収集するHTTP呼び出しとSQLの最大件数です。既定値はそれぞれ100万件です。

Option	Default
`trace_httpc_limit`	`1000000`
`trace_sql_limit`	`1000000`

設定した件数を超えると、その種類のデータ収集はその時点で停止し、超過分は統計に反映されません。バッチジョブ自体は実行を継続し、トランザクションも正常に完了します。

注意

収集が停止してもトレースに表示は残りません。実際の処理件数が上限を超える可能性がある場合は、あらかじめ十分に大きな値を設定してください。

トランザクション一覧に表示されるSQL件数またはHTTP呼び出し件数が設定した上限値と正確に一致する場合、上限に達した可能性があります。

2つのオプションに製品上の上限値はありません。ただし値を大きく設定するとバッチプロセスのメモリ使用量が増えるため、検証環境で確認してから運用環境に適用してください。

ジョブごとに設定を分ける

job_nameとtime_limitはジョブごとに異なる値を設定します。設定ファイルはwhatap.homeを基準に読み込むため、-Dwhatap.homeでジョブ別ディレクトリを指定する方式を推奨します。

エージェントjarは1か所に置き、設定ファイルのみジョブごとに用意してください。

{BATCH_HOME}/agent/whatap.agent.batch-X.Y.Z.jar   すべてのジョブで共有

{JOB_HOME}/
├── job-a/
│   ├── job-a.jar
│   └── whatap.conf      job_name=job-a, time_limit=600000
└── job-b/
    ├── job-b.jar
    └── whatap.conf      job_name=job-b, time_limit=120000

設定ファイルを読み込んだディレクトリにはlogsディレクトリが作成されます。ジョブディレクトリにlogsがない場合は、そのディレクトリの設定が使われていません。問題を確認するときの指標として活用してください。

実行

実行順序

バッチホストは、すべてのバッチジョブに対して1つだけ起動します。

すべてのバッチジョブを実行する前に、バッチホストを1回起動してください。
各バッチジョブを-javaagentオプションとともに実行してください。複数のジョブを並列に実行できます。
すべてのバッチジョブが終了した後にバッチホストを終了してください。

注意

設定ファイルは起動時に1回だけ読み込みます。設定を変更した場合、バッチエージェントは次に実行するジョブから反映され、バッチホストは再起動が必要です。

バッチホストのプロセスを強制終了すると、実行中のジョブから送信したデータを失うことがあります。すべてのジョブが終了した後に停止してください。

バッチホストの起動

Linux
Windows

Batch Host
cd {BATCH_HOME}
java -cp {BATCH_HOME}/whatap.agent.batch.host-X.Y.Z.jar:{BATCH_HOME}/whatap.agent-X.Y.Z.jar \
     -Dwhatap.name=batch whatap.agent.batch.App

Java 17以上の場合は、リフレクション関連のオプションを追加してください。

Batch Host, Java 17 or later
cd {BATCH_HOME}
java --add-opens=java.base/java.lang=ALL-UNNAMED \
     -cp {BATCH_HOME}/whatap.agent.batch.host-X.Y.Z.jar:{BATCH_HOME}/whatap.agent-X.Y.Z.jar \
     -Dwhatap.name=batch whatap.agent.batch.App

Batch Host
cd /d {BATCH_HOME}
java -cp "{BATCH_HOME}\whatap.agent.batch.host-X.Y.Z.jar;{BATCH_HOME}\whatap.agent-X.Y.Z.jar" -Dwhatap.name=batch whatap.agent.batch.App

Java 17以上の場合は、リフレクション関連のオプションを追加してください。

Batch Host, Java 17 or later
cd /d {BATCH_HOME}
java --add-opens=java.base/java.lang=ALL-UNNAMED -cp "{BATCH_HOME}\whatap.agent.batch.host-X.Y.Z.jar;{BATCH_HOME}\whatap.agent-X.Y.Z.jar" -Dwhatap.name=batch whatap.agent.batch.App

Windowsではクラスパスの区切り文字がセミコロン(;)です。コマンドプロンプトはセミコロンを引数の区切りとして解釈するため、クラスパス全体をダブルクォーテーションで囲む必要があります。

バッチジョブの実行

Linux
Windows

Batch Job
java -javaagent:{BATCH_HOME}/agent/whatap.agent.batch-X.Y.Z.jar \
     -Dwhatap.home={JOB_HOME}/job-a \
     -jar {JOB_HOME}/job-a/job-a.jar

Java 17以上の場合は--add-opens=java.base/java.lang=ALL-UNNAMEDを追加してください。

Batch Job
java -javaagent:{BATCH_HOME}\agent\whatap.agent.batch-X.Y.Z.jar ^
     -Dwhatap.home={JOB_HOME}\job-a ^
     -jar {JOB_HOME}\job-a\job-a.jar

Java 17以上の場合は--add-opens=java.base/java.lang=ALL-UNNAMEDを追加してください。

起動確認

起動時に表示されるバナーで設定の適用状況を確認します。バッチホストとバッチエージェントのバナーは異なります。

バッチホスト

WhaTap vX.Y.Z YYYYMMDD PCODE(プロジェクトコード)
Java <JDKバージョン> asmlib<バージョン> asm<バージョン>
whatap.agent-X.Y.Z.jar
./whatap.conf

Display	Description
`PCODE(数値)`	正常。数値はプロジェクトコード
`PCODE(0)`	`license`または設定ファイルが適用されていない。トラブルシューティングを参照

3行目にはバッチホストのjarではなく、Javaエージェントのjarファイル名が表示されます。正常な動作です。

バッチエージェント

WhaTap vX.Y.Z YYYYMMDD
Java <JDKバージョン> asmlib<バージョン> asm<バージョン>
whatap.agent.batch-X.Y.Z.jar
{JOB_HOME}/job-a/whatap.conf

バッチエージェントのバナーにはPCODEが表示されません。4行目に出力された設定ファイルのパスが、ジョブ別の設定が適用されたかを確認する基準です。意図したジョブディレクトリのパスでない場合は、whatap.homeが想定と異なる形で決定されています。

バナーのJava・asmの値は、プロセスを実行したJDKによって決まります。2つのプロセスを異なるJDKで起動すると、それぞれ異なる値が表示されます。

画面での確認

バッチジョブは、ヒットマップとトランザクション一覧でトランザクションとして確認できます。トランザクション名はjob_nameに設定した値です。

仮想トランザクション

split_trace_enabled=trueの場合、ステップ数が多いジョブはトレースが一定の単位で分割されて送信されます。分割した各区間は仮想トランザクションとして表示され、名前に連番が付きます。既定値はfalseのため、既定の設定では仮想トランザクションは表示されません。

job_name=sample-jobでステップ数が約5,000の場合の例です。

トランザクション名	内容	表示される所要時間
`sample-job-1` ~ `sample-job-4`	分割した区間(仮想トランザクション)	各区間の処理時間
`sample-job`	実際のトランザクション	ジョブ全体の所要時間

ジョブ全体の所要時間は、連番が付かないトランザクションで確認してください。ステップ番号はジョブ全体で連続します。

仮想トランザクションはヒットマップとTPSに反映されますが、統計にはジョブ1件として集計されます。トランザクション件数が多く計上されることはありません。
仮想トランザクションはCPU使用時間が0、クライアントIPアドレスが0.0.0.0と表示されます。
トレース分析画面でステップの実行内容をファイルとしてダウンロードする際、トレースが分割されているとファイルも分割単位に分かれます。ジョブ全体のステップ内容が必要な場合は、仮想トランザクションをそれぞれダウンロードしてください。

バッチエージェントのメトリクス指標の収集

ダッシュボードにはバッチホスト(Batch Host)のHeap Memoryを収集し、バッチアプリケーションのパフォーマンス指標はメトリクス(TagCount: batch_job_counter)として収集します。

`batch_job_counter`

batch job: pid, hostname, job_name
gc: gc_count, gc_time_sum, gc_oldgen_count
heap: heap_tot, heap_use, heap_max, heap_pending_final, heap_perm
cpu: cputime
thread count: thread_total_started, thread_count, thread_daemon, thread_peak_count

トラブルシューティング

バッチホストの起動バナーにPCODE(0)が表示されます

バナーの4行目に出力されたパスにwhatap.confがあるか確認してください。
ない場合はwhatap.homeが想定と異なる形で決定されています。設定ファイルの場所を確認し、必要であれば-Dwhatap.homeで明示的に指定してください。
設定ファイルがある場合は、licenseの値が正しいか確認してください。値に問題があるとログにWhaTap AccessKey Errorが記録されます。

java.net.BindExceptionエラー

UDP 6611がすでに使用中です。バッチホストを強制終了した場合、Javaプロセスが残ってポートを占有し続けることがあります。

Linux
Windows

ss -anu | grep 6611
ps -ef | grep whatap.agent.batch.App

netstat -ano | findstr ":6611"

残っているプロセスを終了してから、バッチホストを再起動してください。

ジョブごとに設定した内容が反映されません

そのディレクトリがwhatap.homeとして認識されていません。起動バナーの4行目に出力されたパスを確認してください。

最も多い原因は、エージェントjarを共有の場所に置き、設定ファイルだけをジョブディレクトリに置いた場合です。-javaagentで指定したjarのディレクトリがwhatap.homeになるため、ジョブディレクトリのwhatap.confは読み込まれません。-Dwhatap.homeでジョブディレクトリを指定してください。

モニタリングデータが表示されません

次の順序で確認してください。

バッチホストが起動しているか確認してください。
起動バナーのPCODEが0でないか確認してください。
バッチホストから収集サーバーへのTCP 6600が許可されているか確認してください。
バッチエージェントからバッチホストへのUDP 6611が通信できるか確認してください。
UDPポートを変更した場合、バッチホストのnet_udp_listen_portとバッチジョブのnet_udp_portが同じ値か確認してください。
{whatap.home}/logs/whatap.logにエラーが記録されているか確認してください。

ステップが途中で途切れています

収集の上限に達した場合です。上限に達してもトレースに表示は残らないため、次を確認してください。

確認項目	関連設定
ステップ番号が1,000付近で途切れているか	トレースステップ収集の設定
SQL件数が`trace_sql_limit`と一致するか	収集件数の上限
HTTP呼び出し件数が`trace_httpc_limit`と一致するか	収集件数の上限
トレースの最後に`lost-profile`ステップがあるか	プロファイリング終了待機時間

トランザクションにlost-profileが記録されます

profile_expired_time(既定30秒)の間ステップが届かず、プロファイリングを強制終了した状態です。

ジョブがkill -9などで異常終了した場合は、正常な自動整理の結果です。
ジョブが正常に実行中だった場合は、外部システムの応答待ちなど計測対象の処理が発生しない区間が30秒を超えた可能性があります。プロファイリング終了待機時間を参照して値を調整してください。

自動的に計算される設定

次の値はtime_limitから自動的に計算されます。設定ファイルに直接記載する必要はありません。

Option	Calculation
`warning_time`	`time_limit`の70%
`yellow_time`	`time_limit`の70%
`red_time`	`time_limit`の100%

適用確認チェックリスト

#	項目	確認方法
1	エージェントの解凍	`{BATCH_HOME}`配下と`agent`ディレクトリにjarがあります。
2	ホストの設定	`license`と`whatap.server.host`を記載しました。
3	通信要件	TCP 6600アウトバウンドを許可しました。
4	バッチホストの起動	バッチホストのバナーの`PCODE`が0ではありません。
5	エージェントの設定	ジョブごとに`job_name`と`time_limit`を設定しました。
6	ジョブの実行	`-Dwhatap.home`でジョブディレクトリを指定しました。
7	設定の適用	ジョブディレクトリに`logs`が作成されました。
8	データの確認	ヒットマップに`job_name`のトランザクションが表示されます。
9	所要時間の確認	連番が付かないトランザクションでジョブ全体の時間を確認しました。
10	並列実行	複数のジョブを同時実行し、`job_name`別に区分されて表示されます。
11	終了処理	すべてのジョブ終了後にバッチホストを停止しました。

次のステップ

オープンソース追跡

アプリケーションで使用するフレームワークやオープンソースライブラリによって、エージェントオプションの追加が必要になる場合があります。たとえば、フレームワークやオープンソースでspring-boot-3.x、feign-client-11、okhttp3-4.4使用の際は、次のようにオプションを設定します。
whatap.conf
```
weaving=spring-boot-3.0,feign-11,okhttp3-4.4
```
ユーザーのアプリケーション環境に合わせたフレームワークやオープンソースライブラリを設定する方法は、次の文書を参照してください。
インストールの点検

プロジェクトの作成とエージェントのインストール、JVMオプションまですべて適用したら、次の文書でチェック事項を確認します。
インストール問題の解決

エージェントをインストールする際に発生する可能性がある問題と、これを解決するための具体的なガイドを提供します。ファイアウォールの設定、SpringBoot及びTomcat JMXの設定、OSGIフレームワーク使用サーバーの設定など、様々な状況に対する解決策を案内します。詳細については、次の文書を参照してください。
エージェント設定

エージェント設定(whatap.conf)ファイルにオプションを適用して、モニタリングのための様々な機能を提供します。デフォルト設定から、サーバーの接続とデータ転送の設定、複数のアプリケーションサーバーの設定ファイルの管理方法、トランザクションの追跡などが含まれます。詳細については、次の文書を参照してください。
モニタリングの開始

すべての設定を完了してから、アプリケーションサーバーを再起動します。エージェントが情報の収集を開始します。まず、アプリケーションメニューでモニタリングデータが収集されていることを確認します。アプリケーションメニューの詳細については、次の文書を参照してください。

バッチモニタリングの構成​

通信要件​

エージェントのダウンロード​

設定ファイルの場所​

whatap.homeの決定方式​

バッチホストの設定​

UDP受信の設定​

トレースステップ収集の設定​

プロファイリング終了待機時間​

バッチエージェントの設定​

time_limitの設定​

アクティブスタックの収集タイミング​

収集件数の上限​

ジョブごとに設定を分ける​

実行​

実行順序​

バッチホストの起動​

バッチジョブの実行​

起動確認​

バッチホスト​

バッチエージェント​

画面での確認​

仮想トランザクション​

バッチエージェントのメトリクス指標の収集​

batch_job_counter​

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

バッチホストの起動バナーにPCODE(0)が表示されます​

java.net.BindExceptionエラー​

ジョブごとに設定した内容が反映されません​

モニタリングデータが表示されません​

ステップが途中で途切れています​

トランザクションにlost-profileが記録されます​

自動的に計算される設定​

適用確認チェックリスト​

次のステップ​