Skip to main content

Installing Docker Java

At the bottom of Management > Agent installation, click Install Application > Select the Docker Java tab in Install guide.

This process adds the settings for applying the agent to the JVM option of the Java application running on the Docker container and packages the container images as follows:

Note

  • EKS Fargate is to be supported later.

  • Git example code is provided to help you understand the Java application integration process. See the following.

Download agent​

To install the WhaTap application agent, create the whatap.conf file. Change {YOUR_PROJECT_ROOT} to the top-level path of the project to install the agent.

cat >{YOUR_PROJECT_ROOT}/whatap.conf <<EOL
whatap.server.host={proxyServer}
EOL

Setting the Kubernetes internal application agent options​

The settings required for the Kubernetes internal application agent can be configured in the whatap.conf file or through the container env field when releasing the agent.

  • The options in the whatap.conf file have higher priority than those set in the container env field.

  • If no value is set in whatap.conf or container env, the default value is used.

  • Use the In case of 'license' and 'whatap.server.host options, use the container environment variables settings. For more information, check [the following] (#application-conf-check).

If any settings in the configuration file are changed or important settings are lost, the configuration may not work properly. Therefore, it is recommended to configure container environment variables in the Kubernetes environment. For more information about other agent control options, see the following.

Note

Option unavailable in the Kubernetes environment

  • whatap.name: Unique name by which the collection server identifies agents. The name is generated based on the object on which the agent is running. Random assignment of users may cause problems with agent identification.

  • whatap.onode: The Kubernetes cluster node name is set by default. It is used to receive information about the node to which the agent belongs. When specified by the user, it may be difficult to accurately identify the node.

Note

Checking the whatap.server.host setting of the application ​

In some container images, you cannot directly set environment variables with . such as whatap.server.host. If this keeps the application agent from starting normally, directly modify the whatap.conf file to set the whatap.server.host value. The procedure how to check the whatap.server.host setting of the application is as follows:

  1. Enter into the WhaTap application container.

  2. By executing the following command, check whether the whatap.server.host value is included.

    ```bash 
    $ env | grep whatap.server.host
    ```

    If no value is output, it indicates that the container image cannot support configuration of the environment variables with .. In this case, use the configuration file instead of environment variables. Open the whatap.conf file and then manually set the whatap.server.host value as follows:

    ```bash
    whatap.server.host={WhaTap Collection Server IP}
    ```

The following guides you to include the latest version of the agent in the application image.

  1. Refer to the table below to check the Java APM agent version included in each kube_mon version.

    Java APM version info as of July 2, 2025
    whatap/kube_mon versionJava APM version
    latest2.2.61
    1.8.72.2.61
    1.8.62.2.55
    1.8.52.2.52
    1.8.42.2.50
    1.8.32.2.50
    1.8.22.2.48
    1.8.12.2.47
    1.8.02.2.42
    1.7.162.2.41
    1.7.152.2.39
    1.7.142.2.39
    1.7.132.2.39
    1.7.122.2.38
    1.7.112.2.38
    1.7.102.2.38
    1.7.92.2.38
    1.7.82.2.36
    1.7.72.2.35
    1.7.62.2.35
    1.7.52.2.34
    1.7.42.2.33
    1.7.32.2.33
    1.7.22.2.33
    1.7.12.2.32
    1.7.02.2.32
    1.6.12.2.32
    1.6.02.2.31
    1.5.92.2.31
    1.5.82.2.30
    1.5.72.2.28
    1.5.62.2.27
    1.5.52.2.27
    1.5.42.2.26
    1.5.32.2.26
    1.5.22.2.26
    1.5.12.2.26
    1.5.02.2.26
    1.4.92.2.25

  2. To include the WhaTap agent in the application image, add the following in the Dockerfile's final image build step. Change {YOUR_PROJECT_ROOT} to the top-level path of the project to install the agent.

    # Create the WhaTap agent directory in the user container
    RUN mkdir -p /whatap

    # Copy the WhaTap Java agent to the user container
    COPY --from=whatap/kube_mon /data/agent/micro/whatap.agent.kube.jar /whatap

    # Copy the created whatap.conf file to the user container
    COPY {YOUR_PROJECT_ROOT}/whatap.conf /whatap/

  3. Add the following to the startup command of Dockerfile.

    -javaagent:/whatap/whatap.agent.kube.jar -Dwhatap.micro.enabled=true

    See the following definition example of the following Dockerfile.

    Dockerfile
    FROM openjdk:8-jdk-slim
    RUN mkdir -p /app && mkdir /whatap
    WORKDIR /app
    COPY --from=whatap/kube_mon /data/agent/micro/whatap.agent.kube.jar /whatap
    COPY ./whatap.conf /whatap
    COPY ./target/myApp.jar /app/
    CMD ["java","-javaagent:/whatap/whatap.agent.kube.jar","-Dwhatap.micro.enabled=true","-jar","/app/myApp.jar"]
    EXPOSE 8080

  4. Build the Docker. Change {YOUR_DOCKERFILE_DIR} to the path where Dockerfile is located.

    cd {YOUR_DOCKERFILE_DIR}
    docker build -t {IMAGE_NAME} .
Tip

For Java 17 or later, add the --add-opens=java.base/java.lang=ALL-UNNAMED option related to the reflection.

Setting the security key​

Set a security key to query SQL variables and perform HTTP queries, or use the Thread stop function.

  • Java Agent 2.2.2 or later

    After creating the security.conf file in the $WHATAP_HOME path, enter a 6-character password consisting of alphabets and numbers as follows:

    security.conf
    paramkey=ABCDEF # SQL variable and HTTP query lookup
    threadkill=ABCDEF # Thread stop function

  • Java agent 2.2.2 or earlier

    After creating the paramkey.txt file in the $WHATAP_HOME path, enter a 6-character password consisting of alphabets and numbers as follows:

    paramkey.txt
    ABCDEF # SQL variable and HTTP query lookup, thread stop function
Tip

When updating the Java agent version to 2.2.2, the key values in the existing paramkey.txt file are automatically applied to the security.conf file. For example, if you used FEDCBA in paramkey.txt and updated to the version 2.2.2, it is applied to the security.conf file as follows:

paramkey=FEDCBA
threadkill=FEDCBA

If the paramkey.txt file does not exist, the key value of the security.conf file is automatically created as the key value of WHATAP.

Note

  • For agent settings related to recording SQL parameters, see the following.

  • For agent settings related to recording the HTTP parameters, see the following.

Configuring the container environment variables​

After building Docker, set container environment variables in the Kubernetes environment. Add the following items in the yaml file for releasing the application.

env:
- name: NODE_IP
  valueFrom: {fieldRef: {fieldPath: status.hostIP}}
- name: NODE_NAME
  valueFrom: {fieldRef: {fieldPath: spec.nodeName}}
- name: POD_NAME
  valueFrom: {fieldRef: {fieldPath: metadata.name}}
- name: OKIND
  value: {YOUR_OKIND_NAME}
- name: license
  value: {licenseKey}
- name: whatap.server.host
  value: {proxyServer}
- name: whatap.micro.enabled
  value: "true"

See the following example:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: #DeploymentName
  labels:
    app: #AppLabel
spec:
  replicas: 3
  selector:
    matchLabels:
      app: #AppLabel
  template:
    metadata:
      labels:
        app: #AppLabel
    spec:
      containers:
      - name: #ContainerName
        image: nginx
        ports:
        - containerPort: 80
        env:
        - name: NODE_IP
          valueFrom: {fieldRef: {fieldPath: "status.hostIP"}}
        - name: NODE_NAME
          valueFrom: {fieldRef: {fieldPath: "spec.nodeName"}}
        - name: POD_NAME
          valueFrom: {fieldRef: {fieldPath: "metadata.name "}}
        - name: OKIND
          value: #DeploymentName
        - name: license
          value: #licenseKey
        - name: whatap.server.host
          value: #proxyServer
        - name: whatap.micro.enabled
          value: "true"
Note

Roles of environment variables

  • NODE_IP: Collects the IP address of the node where the current Pod has been hosted.

  • NODE_NAME: Collects the name of the node where the current Pod is running.

  • POD_NAME: Collects the name of the current Pod.

  • OKIND (optional): Groups applications for Pods. If set to a deployment name, the corresponding Pods are grouped together.

  • license: Key for agent authentication.

  • whatap.server.host: Host IP of the WhaTap collection server

  • whatap.micro.enabled: Enables integration with containers.

Checking the agent installation​

  • To check whether the agent has been installed, go to Dashboard > Application Service Dashboard.

  • If you have manually installed the downloaded file but cannot see the agent in Dashboard, check the following.

    • Execute the command, ps -ef | grep whatap in the container, and then check whether the agent options have been applied properly.

    • Check the content of the container in the /whatap/logs path. Agent logs are output in the format of logs/{whatap configuration file name}-yyyymmdd.log.

Last updated on