Java Agent インストール

1. モジュールの説明​

exem-java-agentは、Java VMベースのプロセスで実行されるWASのトランザクション、SQL、例外、リソース使用量を収集してExemONE収集サーバー(Receiver)に送信するモニタリングエージェントです。

2. サポート環境​

3. 通信ポート​

4. インストール方法​

環境に応じて3種類のインストール方式をサポートします。

4-1. On-Premiseインストール​

1. パッケージの解凍​

tar xvzf EXEM-JAVA-AGENT-[version].tar.gz

2. Receiver接続設定​

{インストールパス}/exem/java/cfg/agent/java.confファイルのRECEIVER_ADDRにExemONE収集サーバーのアドレスを入力します。

RECEIVER_ADDR=<収集サーバーIP>:9010

3. JVMオプションの設定​

WAS起動スクリプトに以下のJVMオプションを追加します。設定はWAS再起動後に適用されます。

Tomcat例($CATALINA_HOME/bin/catalina.shまたはsetenv.sh):

JAVA_OPTS="$JAVA_OPTS -Dexem.groupid=default -Dexem.agent.name=tomcat_agent -Dexem.bid=$(hostname) -javaagent:/home/exem/java/lib/exem-java-agent.jar"

JVMオプションの説明:

JDK 9以上で必須の追加オプション:

JDK 9からJavaのモジュール化によって、CPU/メモリ使用量の収集に以下のオプションを追加する必要があります。

--add-opens jdk.management/com.sun.management.internal=ALL-UNNAMED

HTTP外部呼び出し収集オプション(任意):

Javaの基本パッケージによるHTTP外部呼び出しデータの収集が必要な場合、以下のオプションを追加します。

--add-opens=java.base/sun.net.www.http=ALL-UNNAMED
--add-opens=java.base/sun.net.www.protocol.http=ALL-UNNAMED
--add-exports=java.base/sun.net.www=ALL-UNNAMED

JDK 9以上の全体例:

JAVA_OPTS="$JAVA_OPTS -Dexem.groupid=default -Dexem.agent.name=tomcat_agent -Dexem.bid=$(hostname) -javaagent:/home/exem/java/lib/exem-java-agent.jar --add-opens jdk.management/com.sun.management.internal=ALL-UNNAMED"

4-2. InitContainer方式 (Kubernetes)​

アプリケーションを再ビルドせずに、PodのinitContainerとしてエージェントをインストールする方法です。

事前条件:

• kubectlコマンドを実行できる環境が必要です。
• インストール対象のDeployment YAMLにExemONEの環境変数を追加する必要があります。

インストールパッケージの構成:

1. ConfigMapの作成​

以下の2つのConfigMapを作成します。

exem-java-agent-env (JVMオプション環境変数):

apiVersion: v1
kind: ConfigMap
metadata:
  name: exem-java-agent-env
  namespace: {{namespace指定}}
data:
  startup_opt: "-javaagent:/exem/java/lib/exem-java-agent.jar -Dexem.run.on.container=true"

exem-java-agent-config (エージェント設定ファイル):

apiVersion: v1
kind: ConfigMap
metadata:
  name: exem-java-agent-config
  namespace: {{namespace指定}}
data:
  java.conf: |
    RECEIVER_ADDR={{収集サーバーアドレス指定}}
  db.alias: |
    # ip.port.databasename=alias
  local.advice: |
    !javax/servlet/http/HttpServlet.*

2. Deployment YAMLの修正​

既存のDeployment YAMLのspec.template.specに以下の内容を追加します。

spec:
  template:
    spec:
      volumes:
        - name: exem-volume
          emptyDir: {}
        - name: config-volume-java-agent
          configMap:
            name: exem-java-agent-config
      initContainers:
        - name: install-exem-java-agent
          image: exem-java-agent-inst:x.x.x
          imagePullPolicy: IfNotPresent
          volumeMounts:
            - name: exem-volume
              mountPath: /exem
            - name: config-volume-java-agent
              mountPath: "/exem-config"
              readOnly: true
      containers:
        - name: <application-name>
          volumeMounts:
            - name: exem-volume
              mountPath: /exem
          env:
            - name: EXEM_GROUP_ID
              value: "{{group id指定}}"
            - name: EXEM_RUN_ON_CONTAINER
              value: "true"
            - name: EXEMWID
              valueFrom:
                fieldRef:
                  fieldPath: metadata.uid
            - name: EXEM_JAVA_AGENT_NAME
              value: "{{agent name指定}}"

環境変数の説明:

設定値の優先順位:

JVMオプション、環境変数、設定ファイルの3つの方式で指定でき、以下の順序で優先されます。

3. Tomcat使用時(任意)​

提供されたexem-java-agent-env ConfigMapを使用して、CATALINA_OPTSにエージェントオプションを適用します。

4-3. Dockerfile Rebuild方式​

インストール対象アプリケーションのDockerfileにエージェントを含めてイメージをビルドする方式です。

1. パッケージのアップロードと解凍​

イメージを再ビルドするサーバーにパッケージをアップロードした後、解凍します。

tar -xvzf EXEM-JAVA-AGENT-3.x.x.tar.gz
rm -f EXEM-JAVA-AGENT-3.x.x.tar.gz

2. Dockerfileにエージェント設定を追加​

COPY {パッケージパス}/exem {アプリケーション内パス}/exem
ENV EXEM_GROUP_ID={group_id}
ENV EXEM_RECEIVER_ADDR={IP:PORT}
ENV JAVA_OPTS={JAVA_OPTS}

例:

COPY /home/exemone/exem /home/exem
ENV EXEM_GROUP_ID=default
ENV EXEM_RECEIVER_ADDR=<収集サーバーIP>:9010
ENV JAVA_OPTS="$JAVA_OPTS -Dexem.groupid=$EXEM_GROUP_ID -Dexem.agent.name=tomcat_agent -javaagent:/exem/java/lib/exem-java-agent.jar -Dexem.run.on.container=true"

3. Dockerイメージのビルド​

docker build --tag {docker-user-id}/{repository-name} .

4. Deploymentの適用​

Deployment YAMLにExemONEの環境変数を追加した後、デプロイします。

kubectl apply -f app-deployment.yaml

5. インストール確認​

5-1. Agentログの確認​

エージェントログで正常起動を確認します。

tail -f {インストールパス}/exem/java/logs/exem-java-agent[バージョン].log

正常起動時は以下のようなログが出力されます。

[INFO ] [main] LOAD [com.exemone.ext.XM_BOUND_X]
[INFO ] [main] LOAD [com.exemone.ext.XM_RT]
[INFO ] [main] EXEM AGENT EXT [...]
[INFO ] [main] 3.0.23

5-2. ExemONE画面の確認​

Application > WAS画面で、該当WASがActive状態になっているかを確認します。