3.1. Auto-Instrumentation (APM Agent)

Overview

One label is enough for the OPENMARU WAS agent to be injected automatically into a workload. No image change is needed.

1. The Quickest Way to Use It

Add the following to the pod template labels of the Deployment to be monitored, and redeploy.

spec:
  template:
    metadata:
      labels:
        openmaru.io/was-agent: 'true'    # this one line applies auto-instrumentation

The label must go in spec.template.metadata.labels (the pod template), not in the Deployment's top-level metadata.labels.

After redeploying, every pod that comes up gets the following automatically.

• The khan-data shared volume (emptyDir)
• The khan-agent-init init container (unpacks the agent files)
• -javaagent and the OMAPM_* connection environment variables in the app container

2. Label Options

Label	Required	Default	Description
openmaru.io/was-agent	required	—	Instruments only when 'true'. Any other value, or unset, does nothing
openmaru.io/container-names	optional	(all)	Names the one container to instrument when there are several
openmaru.io/was-agent-version	optional	5.1.0	The agent version (image tag) to inject
openmaru.io/was-agent-image-pull-policy	optional	IfNotPresent	The agent image pull policy. Always is possible
openmaru.io/java-version	optional	11	The app's Java version. 1.7/1.8/11/21 and so on. Java 9 or later also gets JAVA_OPTS (add-opens) injected for module access

A full example:

spec:
  replicas: 1
  selector:
    matchLabels:
      deployment: testapp
  template:
    metadata:
      labels:
        deployment: testapp
        openmaru.io/was-agent: 'true'
        openmaru.io/container-names: 'testapp'            # may be omitted
        openmaru.io/was-agent-version: '5.1.0-10.3'       # may be omitted (default 5.1.0)
        openmaru.io/was-agent-image-pull-policy: IfNotPresent
        openmaru.io/java-version: '11'                    # may be omitted (default 11)
    spec:
      containers:
        - name: testapp
          image: my-registry/testapp:latest

3. The Environment Variables Added Automatically

Once instrumentation applies, the environment variables below are injected into the app container. An environment variable of the same name already on the Deployment is not overwritten (the user's value wins). The one exception is JAVA_TOOL_OPTIONS, which is appended to any existing value.

Environment variable	Example value	Meaning
OMAPM_HOST	openmaru-apm.openmaru-observ.svc.cluster.local	The APM server host (the Operator default OMAPM_HOST when unset)
OMAPM_PORT	8080	The APM server port
OMAPM_APPLICATION_NAME	testapp-${HOSTNAME:-:2}	The application name shown in APM
OMAPM_INSTANCE_ID	testapp-${HOSTNAME:-:2}-${HOSTNAME:-:3}	The instance identifier
OMAPM_TRANSACTION_TRACE_THRESHOLD	500	The transaction trace threshold (ms)
JAVA_TOOL_OPTIONS	-javaagent:/khan-agent/khan-agent-5.1.0.jar	Loads the agent (appended after any existing value)
JAVA_OPTS	-noverify --add-opens=...	Module access options for Java 9 and later (when java-version is above 8)

To name the APM server per workload, put OMAPM_HOST / OMAPM_PORT directly in the Deployment's container env. They win over the Operator defaults.

4. Confirming It Applied

Check that the init container and the javaagent went into the new pod.

# check the init container (khan-agent-init) and the volume (khan-data)
kubectl describe pod <pod-name> | grep -E "khan-agent-init|khan-data"

# check the injected environment variables
kubectl set env pod/<pod-name> --list | grep -E "OMAPM_|JAVA_TOOL_OPTIONS"

It is sound once that application and instance appear in the OPENMARU APM console (the WAS dashboard).

5. How It Works

6. When It Does Not Work

Symptom	What to check
The agent is not attached to the pod	Whether the label is in spec.template.metadata.labels, and whether the value is exactly 'true' (a string)
The init container image fails to pull	Whether the image path built from IMAGE_REGISTRY/IMAGE_NAMESPACE (the install settings) and was-agent-version actually exists
Injected into the wrong one of several containers	Name the target container with openmaru.io/container-names
Not visible in the APM console	Whether OMAPM_HOST/OMAPM_PORT point at the real APM server (including network reachability)
An env var set earlier has no effect	That is correct behaviour. An env var of the same name set by the user wins (it is not overwritten)

---