この章ではエージェントのインストール方法について説明します。エージェントはWebアプリケーションサーバのプロセス、またはスタンドアロンのJAVAデーモンプロセスにインストールできます。

エージェント(JAVA)のディレクトリ構成

JENNIFERのパッケージファイルを解凍すると、agent.javaというディレクトリが作成されます。agent.javaディレクトリの構成は次の通りです。

エージェント(JAVA)のファイル構成

agent.javaディレクトリには3つのjarファイルがバージョン毎にあります。jennifer.jarファイルはインターフェースのみを含んでいますが、エージェントが開始するときは最新バージョンのjennifer.impl-x.x.x.jarファイルをロードします。各ファイルの説明は次の通りです。

エージェント(JAVA)の構成と設定

エージェントのインストールでは、監視対象のJAVA起動オプションの設定を変更します。

エージェント(JAVA)のJAVAオプション

監視対象としてエージェントを設定するためには、以下の2つのオプションを追加します。

エージェントのホームが/home/jennifer5/agent.javaの場合、次のようにオプションを追加します。

JENNIFERエージェントはJAVA1.5以上に対応しています。JENNIFERバージョンによって対応するJAVAのバージョンが異なります。次の表を参照してインストールするJENNIFERのバージョンを確認してください。

エージェント(JAVA)の必須オプション

エージェントを初期化するために設定すべき必須オプションは次の通りです。

inst_id（インスタンスID）の手動設定

初期インストールの時点でinst_idを指定しなかった場合、inst_idはデータサーバから自動的に割り当てられます。この場合、inst_idは10000からの使用可能なIDが昇順で付与されます。

手動でinst_idを指定する場合、構成ファイル（jennifer.conf）のinst_idを指定します。

inst_id = 999

エージェント(JAVA)のインストール

起動オプションの追加

インストールするには次の2つのオプションをモニタリング対象のJAVA起動オプションに追加します。

エージェントのホームが/home/jennifer5/agent.javaの場合、次のようにオプションを追加します。

-Djennifer.config=/home/jennifer5/agent.java/conf/jennifer.conf
-javaagent:/home/jennifer5/agent.java/jennifer.jar

OpenTelemetryエージェントの使用

JENNIFER5.6.2からは非同期処理をより正確にモニタリングするため、OpenTelemetryエージェントを提供します。

OpenTelemetryエージェントのインストール方法

OpenTelemetryエージェント(/agent.java/ext/opentelemetry-javaagent.jar)は既存JENNIFERエージェント(/agent.java/jennifer.jar)と同じく-javaagent起動オプションに設定します。

-javaagent:/home/jennifer5/agent.java/jennifer.jar
-javaagent:/home/jennifer/agent.java/ext/opentelemetry-javaagent.jar

次に、JENNIFERデータサーバの起動オプションにOpenTelemetryが収集したデータを受信するポート番号を指定します。(/server.data/bin/jennifer_data.sh)

JAVA_OPTS=" ${JAVA_OPTS} -Djennifer.unofficial.opentelemetry.collect.port=4317"

最後に、OpenTelemetryエージェントを使用するには、エージェント設定ファイル(jennifer.conf)に次の設定を追加します。

enable_opentelemetry = true
server_grpc_port = 4317

OpenTelemetryエージェント使用次の注意事項

OpenTelemetryは、トレース、 メトリック、 ログなどの テレメトリ データを 作成および管理するために設計されたオープンソースのフレームワークです。そのため、長年性能を改善してきたJENNIFERエージェントと比べるとまだデータの処理(収集・保存)に最適化されてありません。

特に、OpenTelemetryエージェントを使用するとJENNIFERエージェントよりトランザクションの数が増えますし、プロファイルデータの保存もテキストタイプのまま保存するためデータサーバのディスク使用量がJENNIFERに比べて非常に大きくなる場合があります。

本番環境へ導入する場合は、十分なテストを行った上に導入することを推奨します。

アプリケーションサーバ別の注意事項

ほとんどの場合、上記の2つのオプションを追加するだけでインストール作業は終わりますが、一部のアプリケーションサーバの場合は追加の設定が必要です。この節では追加の設定が必要なアプリケーションサーバとその方法について説明します。

JBossにインストールする場合

JBoss-EAP 6(Communityバージョン7)以降の場合、設定ファイルのjboss.modules.system.pkgsオプションに追加の設定が必要です。

-Djboss.modules.system.pkgs=org.jboss.byteman,aries,java.sql,javax.sql

GlassFishにインストールする場合

次のようにasadminツールを使用して、JVMオプションを追加できます。

# Linux
glassfish4/bin/asadmin create-jvm-options "-javaagent\:<jennifer_agent_home>/jennifer.jar"

# Windows
glassfish4\bin> asadmin.bat create-jvm-options '-javaagent:<Drive_letter>:<agent_home>\jennifer.jar'

$GLASSFISH_HOME/configディレクトリにあるosgi.propertiesファイルをオープンして、以下の内容をorg.osgi.framework.bootdelegationオプションに追加します。

org.osgi.framework.bootdelegation=${eclipselink.bootdelegation}, \
                              com.sun.btrace, com.sun.btrace.*, \
                              aries, aries.*, \
                              org.netbeans.lib.profiler, org.netbeans.lib.profiler.*

Jettyにインストールする場合

Jettyの基本JAVAオプション設定ファイルは jetty.shです。

1. $JETTY_HOME/binディレクトリのjetty.shファイルで以下のオプションを追加します。

-Djennifer.config=/home/jennifer5/agent.java/conf/jennifer.conf
-javaagent:/home/jennifer5/agent.java/jennifer.jar

#####################################################

# Add jetty properties to Java VM options.
#####################################################
JAVA_OPTIONS+=("-Djetty.home=$JETTY_HOME" "-Djava.io.tmpdir=$TMPDIR" "-Djennifer.config=/home/j5/jennifer5/agent.java/conf/jennifer.conf" "-javaagent:/home/j5/jennifer5/agent.java/jennifer.jar" )

2. APサーバプロセスを再起動します。

3. JENNIFERエージェントが正常に動作すると、エージェントログファイルに以下の内容が表示されます。

2020-09-01/16:35:05 [I023] Agent own advanced option is found : domain_id = [1000]
2020-09-01/16:35:05 [I023] Agent own advanced option is found : inst_id = [10000]
2020-09-01/16:35:05 [I023] Agent own advanced option is found : log_encoding = [UTF-8]
2020-09-01/16:35:05 [I023] Agent own advanced option is found : log_rotation = [true]
2020-09-01/16:35:05 [I023] Agent own advanced option is found : log_level = [1]
2020-09-01/16:35:05 [I023] Agent own advanced option is found : server_address = [192.168.0.31]
2020-09-01/16:35:05 [I023] Agent own advanced option is found : server_port = [5000]
2020-09-01/16:35:05 [I001] Agent initialized
2020-09-01/16:35:05 [I001] loading control module : /Users/nomin/jennifer5/agent/agent.java/jennifer.impl-5.5.2.2.jar
2020-09-01/16:35:05 [I001] Agent Enable : true
2020-09-01/16:35:05 [I001] Agent Base Version 5.5.2
2020-09-01/16:35:05 [I001] Agent Implementation Version 5.5.2.2
...
2020-09-01/16:35:09 [I001] Runtime Module initialized

バッチにインストールする場合

独立実行型のバッチにインストールする場合、トランザクションをモニタリングするためエージェント設定ファイルに次の設定が必要です。

application_start_point = packageName.ClassName methodName
または
profile_service_class = packageName.ClassName methodName

バッチ処理が早すぎて、データサーバとセッションが結ばれる前に終わってモニタリングができない場合はエージェント設定ファイルに次のオプションを設定するとモニタリング可能です。

send_transaction_in_application_thread = true

また、次の条件に当てはまる環境ではメモリ使用量が継続的に増加する可能性があるので、注意してください。

• 普段使用するヒープメモリ使用量が少ない。

• 起動オプションにヒープメモリ関連設定(-Xms, -Xmx)がない。

• 物理メモリのサイズが大きくて、デフォルトの最大ヒープメモリサイズが、通常使用するヒープメモリ使用量より非常に大きい。

Azure App Serviceにインストールする場合

Azureに対応できるJAVA Web App Serviceは次の2つに分類できます。

• JAVA Web App Service for Windows

• JAVA Web App Service for Linux

JAVA Web App Service for Windows

[開発ツール]の[コンソール]を利用してWindows用JNIライブラリ(例、sys-0.2.1-windows-64.dll)を「%home%\SiteExtensions\JenniferJavaAgentExtension\agent.java\libs」ディレクトリへコピーします。

正常にインストールができましたら、%home%\SiteExtensions\JenniferJavaAgentExtension\agent.java\logsファルだにログが生成されます。

1. created.logが生成されて内容に「installed」と出力されているかを確認します。

2. 次にagent_<yyyyMmdd>_<domain_id>_<inst_id>.logとagent_instrument_<yyyyMMdd>.logファイルの生成を確認します。エージェントログを開いて「Control module loading complete.」と「Runtime module loading complete...」メッセージが出力されているか確認します。

JAVA Web App Service for Linux

~:/home# cd site/wwwroot/
~:/home/site/wwwroot# mkdir apm
~:/home/site/wwwroot# cd apm
~:/home/site/wwwroot/apm# wget https://.../jennifer-agent-java-5.6.0.1.zip

~:/home/site/wwwroot/apm# unzip jennifer-agent-java-5.6.0.1.zip
Archive:  jennifer-agent-java-5.6.0.1.zip
   creating: agent.java/
   creating: agent.java/conf/
   creating: agent.java/ext/
   creating: agent.java/libs/
   creating: agent.java/libs/aix-7.1/
   ...
  inflating: agent.java/libs/windows/sys-0.2.0-windows-64.dll
  inflating: agent.java/libs/windows/sys-0.2.1-windows-32.dll
  inflating: agent.java/libs/windows/sys-0.2.1-windows-64.dll
~:/home/site/wwwroot/apm#

正常にインストールができましたら、/home/site/wwwroot/apm/agent.java/logsファルだにログが生成されます。

1. created.logが生成されて内容に「installed」と出力されているかを確認します。

2. 次にagent_<yyyyMmdd>_<domain_id>_<inst_id>.logとagent_instrument_<yyyyMMdd>.logファイルの生成を確認します。エージェントログを開いて「Control module loading complete.」と「Runtime module loading complete...」メッセージが出力されているか確認します。

コンテナ(Docker)にインストールする場合

インストールの流れ

└── workspace
    ├── Dockerfile
    └── jennifer-agent-java-x.x.x.x.zip

server_address = <DATA_SERVER_IP_ADDRESS>
server_port = <DATA_SERVER_LISTENING_PORT>

# default log_dir "{agent_home}/logs"
# log_dir = {agent_home}/logs
# log_file =
# log_level : 1(info), 2(debug), 3(trace)
log_level = 1
log_encoding = UTF-8
log_rotation = true
# log_max_age : Working when log_rotation is activated. Valid ragne is (1-365)
# log_max_age = 0

# domain_id : Valid range is (1-32767)
domain_id = <DOMAIN_ID>

└── workspace
    ├── Dockerfile
    ├── jennifer-agent-java-x.x.x.x.zip
    └── jennifer.conf

# JENNIFER Java Agent
AGENT_HOME=/opt/agent.java
export CATALINA_OPTS="$CATALINA_OPTS -javaagent:$AGENT_HOME/jennifer.jar -Djennifer.config=$AGENT_HOME/conf/jennifer.conf"

└── workspace
    ├── Dockerfile
    ├── jennifer-agent-java-x.x.x.x.zip
    ├── jennifer.conf
    └── setenv.sh

FROM alpine AS builder

ENV AGENT_VERSION=5.6.0.9
RUN apk --no-cache add unzip
COPY jennifer-agent-java-${AGENT_VERSION}.zip /
RUN unzip -oq jennifer-agent-java-${AGENT_VERSION}.zip -d /tmp


FROM tomcat:8.5-jre8-alpine

...

COPY --from=builder /tmp/agent.java /opt/agent.java
COPY jennifer.conf /opt/agent.java/conf/jennifer.conf
COPY setenv.sh ${CATALINA_HOME}/bin

docker build -t jennifer-java .

システムリソース(CPU、メモリ)使用量を収集するためのJNIモジュール登録

JNIモジュールを利用してCPU、メモリデータを収集する方法は次の通りです。モニタリング対象OSによって、使用するJNIモジュールが異なります。

1. エージェントをインストールしたディレクトリ配下のlibsディレクトリでモニタリング対象OSに該当するディレクトリからJNIモジュールをlibsディレクトリへコピーします。

2. 「管理 > エージェント詳細オプション」画面で「enable_jmx_for_system_resource」をfalseに変更します。

3. エージェントを再起動します。

4. JNIモジュールの正常ロードをログで確認します。

2016-05-19/15:35:29 native lib libjennifer5-0.1.0-aix7.1_32.so loaded

エージェント(JAVA)の削除

エージェントを削除するにはJAVA起動オプションに追加した2つのオプションを削除し、対象プロセスを再起動します。

エージェント(JAVA)のアップグレード

エージェントのアップグレードは[管理 > エージェントアップグレード]画面で行います。