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:
-
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
- Docker Install
- Direct Installation
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. -
In case of the
license
andwhatap.server.host
options, use the container environment variable settings.
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.
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.
- Including the latest version of the agent in the application image
- Including the specified version of the agent in the application image
The following guides you to include the latest version of the agent in the application image.
-
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 /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/ -
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.
DockerfileFROM openjdk:8-jdk-slim
RUN mkdir -p /app && mkdir /whatap
WORKDIR /app
COPY /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 -
Build the Docker. Change
{YOUR_DOCKERFILE_DIR}
to the path where Dockerfile is located.cd {YOUR_DOCKERFILE_DIR}
docker build -t {IMAGE_NAME} .
The following guides you to include the specified version of the agent in the application image.
-
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 /data/agent/micro/whatap.agent-*.jar /whatap
# Copy the created whatap.conf file to the user container
COPY {YOUR_PROJECT_ROOT}/whatap.conf /whatap/ -
Check the version of the WhaTap agent.
docker run whatap/kube_mon ls /data/agent/micro | grep -E 'whatap\.agent-(.*?\.)(.*?\.)(.*?\.)jar' | sort | tail -1
# Output example
## whatap.agent-X.Y.Z.jar -
Add the following to the startup command of Dockerfile. In X.Y.Z, enter the agent version that you checked before.
-javaagent:/whatap/whatap.agent-X.Y.Z.jar -Dwhatap.micro.enabled=true
See the following definition example of the following Dockerfile.
DockerfileFROM openjdk:8-jdk-slim
RUN mkdir -p /app && mkdir /whatap
WORKDIR /app
COPY /data/agent/micro/whatap.agent-*.jar /whatap
COPY ./whatap.conf /whatap
COPY ./target/myApp.jar /app/
CMD ["java","-javaagent:/whatap/whatap.agent-X.Y.Z.jar","-Dwhatap.micro.enabled=true","-jar","/app/myApp.jar"]
EXPOSE 8080 -
Build the Docker. Change
{YOUR_DOCKERFILE_DIR}
to the path where Dockerfile is located.cd {YOUR_DOCKERFILE_DIR}
docker build -t {IMAGE_NAME} .
-
Select Download to download the installation file (whatap.agent.java.tar.gz).
-
Upload the dockerfile to the server and then unzip the file.
InfoTo download to the installation server, execute the following command.
wget https://api.whatap.io/agent/whatap.agent.java.tar.gz
-
When unzipped, the whatap directory is created. Check the settings in the whatap.conf file under the whatap directory, and then modify it as follows:
license={licenseKey}
whatap.server.host={proxyServer}InfoConfiguring the options for the Kubernetes internal application agent
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. -
In case of the
license
andwhatap.server.host
options, use the container environment variable settings.
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.
NoteOption 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.
-
-
Add the following to the startup command of Dockerfile. Check the agent file under the whatap directory, and then enter the version in X.Y.Z.
-javaagent:/whatap/whatap.agent-X.Y.Z.jar -Dwhatap.micro.enabled=true
See the following definition example of the following Dockerfile.
DockerfileFROM openjdk:8-jdk-alpine
RUN mkdir -p /app && mkdir /whatap
WORKDIR /app
COPY ./whatap.agent-X.Y.Z.jar /whatap/
COPY ./whatap.conf /whatap/
COPY ./target/myApp.jar myApp.jar
COPY ./paramkey.txt /whatap/
CMD ["java","-javaagent:/whatap/whatap.agent-X.Y.Z.jar","-Dwhatap.micro.enabled=true","-jar","/app/myApp.jar"]
EXPOSE 8080
-
whatap-virtual-X.Y.Z.jar: Monitoring target (sample application)
-
whatap.agent-X.Y.Z.jar: WhaTap agent
-
If the agent's file name is whatap.agent-1.2.3.jar, change the X.Y.Z part to 1.2.3.
-
For more information about addition of JVM options, see the following.
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.confparamkey=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.txtABCDEF # SQL variable and HTTP query lookup, thread stop function
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.
-
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"
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.
-