5. Installing on Containers and Kubernetes

Chapter 3 covered attaching the agent to a WAS installed directly on a server. This chapter covers the case where the WAS runs as a container.

Which Method to Choose

Method	What it does	When to use it
Baking it into the image	Build a base image containing the agent and have the application use it as its `FROM`	When you manage image builds yourself
S2I	Put the agent files in alongside the source and the build packages them	When developers upload only source and build
Automatic injection (Operator)	Just add a label to the workload and the agent goes in automatically. The image is not changed	Recommended when using Kubernetes or OpenShift

Automatic injection is covered not here but in the OPENMARU APM Operator User Guide. The image does not have to be touched and the Operator handles upgrades too, so in a Kubernetes environment consider that route first. The two methods below are for when the Operator cannot be used or the image has to be managed directly.

1. Baking the Agent into the Image

To monitor a WAS instance running as a container, an image containing the agent has to be built and registered in a registry. The build and deployment steps are described below.

Preparing the Agent Files

Unpack the file below on a Linux machine that can reach the registry and has Podman installed.

$ wget https://cloud.openmaru.io/api/v1/projects/{SAAS_PROJECT_ID}/download/was-agent.zip
$ unzip khan-agent-5.1.0.zip

Composing the Dockerfile

When building the image, include khan-agent-5.1.0.jar, khan-agent.conf, and user-interceptor.conf.

FROM registry.redhat.io/jboss-eap-7/eap74-openjdk8-openshift-rhel7

USER root

ENV JAVA_OPTS="-javaagent:/opt/eap/khan-apm/khan-agent-5.1.0.jar"
ENV JAVA_OPTS="-Dkhan.config.file=/opt/eap/khan-apm/khan-agent.conf"

ADD ./khan-agent-5.1.0.zip /opt/eap/
RUN unzip -q /opt/eap/khan-agent-5.1.0.zip -d /opt/eap/khan-apm && \
    chmod -R 777 /opt/eap/khan-apm

ADD khan-agent.conf /opt/eap/khan-apm
ADD user-interceptor.conf /opt/eap/khan-apm

USER jboss

For the configuration items in khan-agent.conf, see 4. Environment Variables Available in a Pod below.

Composing build.sh

This is the script that builds the image and pushes it to the registry. The address differs depending on whether the registry is on an external server or runs as a container, so change REGISTRY_URL to suit your environment.

$ vi build.sh

#/bin/bash
# -------------------------------------------------------------
# OPENMARU APM https://www.openmaru.io/
# for OpenShift Container JBoss EAP 7.0 Image Monitoring
#
# contact : service@opennaru.com
# Copyright (c) 2026. OPENMARU, Inc. All Rights Reserved.
# -------------------------------------------------------------

#/bin/bash
export REGISTRY_URL=default-route-openshift-image-registry.apps.ocp.opennaru.com

TAG_NAME=eap74-test
VERSION=5.1.0-7.1.1
#
# registry login examples
#

#oc login
#docker login -u devadmin -p $(oc whoami -t) $REGISTRY_URL
#podman login -u $(oc whoami) -p $(oc whoami -t) $REGISTRY_URL

#sudo docker login -p &lt;TOKEN_IN_OPENSHIFT_REGISTRY> -e unused -u unused $REGISTRY_URL
#oc login --token &lt;TOKEN_IN_OPENSHIFT_REGISTRY> ocp-master1.ocp-dev.opennaru.com

podman build --rm --tag=$TAG_NAME .

podman tag $TAG_NAME $REGISTRY_URL/openshift/$TAG_NAME:$VERSION
#$podman push $REGISTRY_URL/openshift/$TAG_NAME:$VERSION
podman push --tls-verify=false $REGISTRY_URL/openshift/$TAG_NAME:$VERSION

The image's namespace and image stream name are given as openshift/$TAG_NAME:$VERSION, so change them to whatever name you want.

Pushing requires being signed in to the registry. Sign in with oc login or podman login before building.

$ export REGISTRY_URL=default-route-openshift-image-registry.apps.ocp.opennaru.com

$ oc login
or $ podman login -u devadmin -p $(oc whoami -t) $REGISTRY_URL

Building and Pushing to the Registry

Run ./build.sh to build the image and push it.

$ ./build.sh

The build passes through the steps from STEP 1 in turn, then the push follows. Only three things need checking.

What to check	What appears in the log
Did the agent go into the image	The `ADD ./khan-agent-<version>.zip` and `ADD khan-agent.conf` steps pass without error
Are the startup options baked in	`ENV JAVA_OPTS="-javaagent:…"` and `ENV JAVA_OPTS="-Dkhan.config.file=…"`
Did it reach the registry	The final `Writing manifest to image destination` and `Storing signatures`

*/} Using cache … means the previous build result is being reused, which is normal. If the cache is used even after the agent files changed, rebuild with podman build --no-cache.

If it fails, first see which STEP it stopped at. Stopping at an ADD step means the file is not in the build directory; stopping at the push step is a registry sign-in or address problem.

Verifying the Image

After deploying, check that it connects and works in OPENMARU APM.

Check the agent connection
Check JVM monitoring
Check the T-Map when calling /session/index.jsp

If it does not work, check the order of JAVA_OPTS in the process. It has to be in this order.

ps -ef | grep jboss
...omitted...
-javaagent:/opt/eap/khan-apm/khan-agent/khan-agent-5.1.0.jar
...omitted...
-Xbootclasspath/p:...omitted...
...omitted...
-Djava.util.logging.manager=org.jboss.logmanager.LogManager

2. Using It in the Application Image

Put the image you built into the FROM clause of the application Dockerfile.

FROM registry.access.redhat.com/jboss-eap-6/eap64-OpenShift

… omitted …

⇒

FROM docker-registry-default.ocp-dev.opennaru.com/jboss-eap-6/eap64-OpenShift

… omitted …

Deploying the application with the image built this way makes the instance appear in the console and transactions start flowing. When the instance is visible under WAS > Dashboard, the installation is finished.

How to read the screens and the troubleshooting features (thread dumps, heap analysis) are covered in the user guide.

3. Building with S2I

S2I (Source-to-Image) is an open-source build method that generates a runnable container image from source code alone, used mainly in OPENMARU COP and Red Hat OpenShift. It uses the source-based method by default but also supports the Dockerfile and binary methods. Its advantage is that developers can control the build process directly.

Putting the downloaded khan-agent-5.1.0.zip file in the data directory below deploys it to the /deployments/data directory of the pod.

warning

Depending on the S2I (Source-to-Image) image, the /deployments/data path can differ

project/
├── data/
│   ├── khan-agent-5.1.0.jar     # the agent JAR file
│   ├── khan-agent.conf          # the agent configuration file
│   └── user-interceptor.conf    # the agent configuration file (user interceptor)
└── src/
    └── ...                      # the user application source code

Tip

Even without S2I (Source-to-Image), if you build with a Dockerfile you can include the Agent files with ADD.

Configuration

Info

It can be configured by referring to Agent Configuration per WAS Type.

...
spec:
...
  containers:
    - resources: {}
      name: testapp
      env:
        - name: OMAPM_HOST
          value: 10.20.2.9
        - name: OMAPM_PORT
          value: '80'
        - name: JAVA_TOOL_OPTIONS
          value: '-javaagent:/data/khan-agent-5.1.0.jar'
        - name: JAVA_OPTS
 value: '-Dtest1=1 --add-opens=java.base/...'## omitted
        - name: OMAPM_APPLICATION_NAME
          value: 'testapp-${HOSTNAME:-:2}'
        - name: OMAPM_INSTANCE_ID
          value: 'testapp-${HOSTNAME:-:2}-${HOSTNAME:-:3}'
        - name: OMAPM_TRANSACTION_TRACE_THRESHOLD
          value: '500'

4. Environment Variables Available in a Pod

These are the OPENMARU APM khan-agent.conf configuration items that can be given as environment variables on a Deployment.

Setting	Description	Default
OMAPM_APPLICATION_NAME	Specifies the application group name. Note that the build number does not appear either.	e.g. when `hostname` is `jboss-eap-egov-65-zs95r`, `eap-${HOSTNAME:-:5}` => `eap-65`
OMAPM_HOST
OMAPM_PORT		443
OMAPM_TLS		true
OMAPM_AGENT_IP
OMAPM_USER_KEY		NIL
OMAPM_INSTANCE_ID	Specifies the instance name. When set, it is shown as `[OMAPM_INSTANCE_ID value]-build number-random value`. When not set, the Deployment name is used.	e.g. when `hostname` is `jboss-eap-egov-65-zs95r`, `eap-${HOSTNAME:-:5}-${HOSTNAME:-:6}` => `eap-65-zs95r` case1: `instanceid-${RANDOM:4}` ==> `instanceid-qfPb` case1: `instanceid-${RANDOM:4}-s` ==> `instanceid-qfPb-s` case1: `instanceid-${IPADDR:3}` ==> `instanceid-23-10` `(ip=192.168.23.10)` case1: `instanceid-${HOSTNAME:-:2}` ==> `instanceid-apm` `(hostname=test-apm)` case1: `instanceid-${HOSTNAME:-:2}-${IPADDR:3}-${RANDOM:4}-s` ==> `instanceid-apm-23.10-afcg-s` `(hostname=test-apm, ip=192.168.23.10)`
OMAPM_AGENT_TYPE		WAS
OMAPM_AGENT_COMPRESS_TYPE	Specifies the agent's compression algorithm type.	lzw (default=snappy)
OMAPM_APDEX_THRESHOLD	Specifies the response time at which the user is satisfied, for APDEX (the default is 3 seconds).	3.0
OMAPM_TRANSACTION_TRACE_ENABLED	Specifies whether to use transaction tracing.	true
OMAPM_TRANSACTION_TRACE_THRESHOLD	Specifies the response time above which a transaction trace is collected (in ms). Default: 500 ms	500
OMAPM_TRANSACTION_TRACE_THRESHOLD _UNDER_DETAIL_ENABLED		false
OMAPM_SQL_CAPTURE_ENABLED	Specifies whether to collect SQL statements during a transaction trace.	true
OMAPM_TRANSACTION_TRACE_SQL_PARAMETERIZE		false
OMAPM_TRANSACTION_SAMPLING_INTERVAL	Specifies the transaction collection interval for the same URL. Setting 10 keeps a trace for only 1 in 10 for the same URL.	1
OMAPM_TRANSACTION_TRACE_SQL_STACKTRACE _THRESHOLD	Sets the SQL query stack trace threshold in ms.	30000
OMAPM_TRANSACTION_TRACE_HEADER_ENABLED	Specifies whether header tracing of the request is enabled.	true
OMAPM_TRANSACTION_TRACE_HEADER_KEYS	The key values of the request headers
OMAPM_TRANSACTION_TRACE_COOKIE_ENABLED	Specifies whether cookie tracing of the request is enabled.	false
OMAPM_TRANSACTION_TRACE_COOKIE_KEYS	The key values of the request cookies	JSESSIONID
OMAPM_TRANSACTION_TRACE_PARAMETER_KEYS	Adds URL parameters
OMAPM_DATABASE_FETCH_WARNINGS	Prints a warning when the comma-separated number of rows is fetched from a SQL ResultSet.	10000,20000,30000
OMAPM_DATABASE_CONN_LEAK_WARNING	Warning for a shortage of database connections	false
OMAPM_DATABASE_POOL_STAT_ENABLED	Specifies whether monitoring of overall database pool statistics is enabled	false
OMAPM_DATABASE_POOL_STAT_INCLUDE_PATTERNS	Specifies the comma-separated list of datasource name patterns to include
OMAPM_DATABASE_POOL_STAT_EXCLUDE_PATTERNS	Specifies the comma-separated list of datasource name patterns to exclude
OMAPM_INCLUDE_PACKAGES
OMAPM_TRANSACTION_EXCLUDE_URL_PATTERNS	URLs to exclude from monitoring (regular expression). e.g. `/test/test.,\/abc/test.*`	`\*`
OMAPM_TRANSACTION_EXCLUDE_URL_SUFFIX		`.gif,.swf,.css,.hwp,.xls,.xlsx,.eot,.pptx,` `.ppt,.asf,.pdf,.txt,.flv,.mp3,.mp4,.doc,` `.html,.wmv,.jpg,.zip,.wav,.png,.ttf,.mov,` `.ico,.js,.woff,.xml,.htc,.NewProxyConnection,` `.DelegatingConnection,.SqlSessionTemplate,` `.CUBRIDConnection,` `.PoolableConnection,.WrappedConnection,` `/bea_wls_deployment_internal/DeploymentService,` `.GIF,.SWF,.CSS,.HWP,.XLS,.XLSX,.EOT,.PPTX,` `.PPT,.ASF,.PDF,.TXT,.FLV,.MP3,.MP4,.DOC,` `.HTML,.WMV,.JPG,.ZIP,.WAV,.PNG,.TTF,.MOV,` `.ICO,.JS,.WOFF,.XML,.HTC`
OMAPM_TRANSACTION_EXCLUDE_URL_SUFFIX_EXCLUDE		true
OMAPM_TRANSACTION_EXCLUDE_USER_AGENT _PATTERNS		`^openmaru-health-check$`
OMAPM_TRANSACTION_ERRORPAGE_URL_PATTERNS		`/session/force500.\,/test/test500.`
OMAPM_TRANSACTION_WITH_EXCEPTION_VIEW _ENABLED		true
OMAPM_TRANSACTION_WITH_EXTERNAL_HTTP _ERROR_VIEW_ENABLED		true
OMAPM_TRANSACTION_WITH_EXTERNAL_HTTP _ERROR_CODES
OMAPM_TRAFFIC_CONTROL_ENABLED		true
OMAPM_TRAFFIC_CONTROL_PATTERN_1	Specifies the maximum number of concurrent requests allowed for the given pattern	`/test/slow., 100`
OMAPM_TRAFFIC_CONTROL_PATTERN_2	Specifies the maximum number of concurrent requests allowed for the given pattern	`/test/test., 100`
OMAPM_TRAFFIC_CONTROL.PATTERN_3	Specifies the maximum number of concurrent requests allowed for the given pattern	`/test/TestServlet., 100`
OMAPM_UBT_CHECK_ENABLED		false
OMAPM_UBT_CHECK_TYPE		ip
OMAPM_UBT_CHECK_USER_COUNT		100
OMAPM_UBT_CHECK_TIME_INTERVAL		1
OMAPM_UBT_CHECK_ALERT_DUP_PREVENT		30
OMAPM_USER_TRACKING_MODE	Specifies the user tracking mode. 0: client IP, 1: the `JSESSIONID` cookie, 2: the `KHANUSER` cookie - default	2
OMAPM_USER_THINKTIME_MINUTES		5
OMAPM_ENABLE_FILTER_INTERCEPTOR		false
OMAPM_ENABLE_IBATIS_INTERCEPTOR		false
OMAPM_ENABLE_MYBATIS_INTERCEPTOR		false
OMAPM_ENABLE_HTTP_INTERCEPTOR		false
OMAPM_ENABLE_SPRINGBATCH_INTERCEPTOR		false
OMAPM_ENABLE_LOGGING_INTERCEPTOR		false
OMAPM_TRACE_LOGGING_LEVELS		WARN,ERROR,FATAL
OMAPM_PUSH_TRANSACTION_NO_DELAY		true
OMAPM_ACTIVEUSER_COUNTFIRSTREQUEST		false
OMAPM_USER_CHARSET_ENCODING	Specifies the APM encoding value	UTF-8
OMAPM_USER_INTERCEPTOR_FILE	The name of the file holding the user's interceptor settings	`user-interceptor.conf`
OMAPM_LOG_DIR	Sets the APM log path	`/svc/test/khan-agent/log`
OMAPM_LOG_FILE	Specifies the log file name	`khan-agent-${INSTANCEID}.log`
OMAPM_LOG_LEVEL	Specifies the log level	INFO
OMAPM_LOG_BACKUP_INDEX	Sets how many log backup files to keep	3
OMAPM_LOG_ROTATE_SIZE	Specifies the log file size at which to rotate	10240000
OMAPM_SESSION_MANAGER_ENABLED	Whether the session manager is enabled	true
OMAPM_ACTIVE_SESSION_COUNT_ENABLED	Whether session counting is enabled	true
OMAPM_AUDIT_LOG_ENABLED	Whether the audit log file is enabled	true
OMAPM_AUDIT_LOG_USERIDKEY		`USER_ID`
OMAPM_AUDIT_LOG_DIR	Sets the audit log path
OMAPM_AUDIT_LOG_FILENAME	Specifies the audit log file name	`audit-{date: yyyy-MM-dd}.log`
OMAPM_AUDIT_LOG_POLICIES		daily: 00:00
OMAPM_AUDIT_LOG_BACKUPS	Sets how many audit log backup files to keep	3

Which Method to Choose​

1. Baking the Agent into the Image​

Preparing the Agent Files​

Composing the Dockerfile​

Composing build.sh​

Building and Pushing to the Registry​

Verifying the Image​

2. Using It in the Application Image​

3. Building with S2I​

Configuration​

4. Environment Variables Available in a Pod​