A.1. Reference and Troubleshooting
Overview
This chapter gathers the full list of auto-instrumentation labels, injected environment variables, and HPA metrics, together with frequently asked questions and the commands used for checking.
1. Label Reference (Auto-Instrumentation)
Set these in spec.template.metadata.labels.
| Label | Required | Default | Allowed values / example |
|---|---|---|---|
openmaru.io/was-agent | required | — | 'true' |
openmaru.io/container-names | optional | all | A container name (for example testapp) |
openmaru.io/was-agent-version | optional | 5.1.0 | An image tag (for example 5.1.0-10.3) |
openmaru.io/was-agent-image-pull-policy | optional | IfNotPresent | IfNotPresent / Always |
openmaru.io/java-version | optional | 11 | 1.7 / 1.8 / 11 / 21 |
2. Injected Environment Variable Reference
One of the same name that already exists is not overwritten. JAVA_TOOL_OPTIONS alone is appended.
| Environment variable | Default behaviour |
|---|---|
OMAPM_HOST | The Operator's OMAPM_HOST when unset |
OMAPM_PORT | The Operator's OMAPM_PORT when unset |
OMAPM_APPLICATION_NAME | <container>-${HOSTNAME:-:2} |
OMAPM_INSTANCE_ID | <container>-${HOSTNAME:-:2}-${HOSTNAME:-:3} |
OMAPM_TRANSACTION_TRACE_THRESHOLD | 500 (ms) |
JAVA_TOOL_OPTIONS | -javaagent:/khan-agent/khan-agent-<version>.jar (appended) |
JAVA_OPTS | add-opens options injected when java-version is above 8 |
3. Operator Installation Environment Variable Reference
| Key | Component | Meaning |
|---|---|---|
IMAGE_REGISTRY | Agent | The registry for the khan-agent image to inject |
IMAGE_NAMESPACE | Agent | The namespace within the registry (leading / included) |
OMAPM_HOST / OMAPM_PORT | Agent | The default APM server for the instrumented target |
Each name/value in envHpa | HPA | The apmAlias → APM server URL mapping |
<apmAlias>_ACCESS_KEY | HPA | (optional) That APM server's API access key |
4. HPA Metric Reference
| Metric | selector labels | What is queried |
|---|---|---|
tps | apmAlias, groupName | The TPS from {APM}/monitoring/api/metrics/apps/info/{groupName} |
5. Frequently Asked Questions (FAQ)
Q. Do I have to change the application image?
No. Adding the label is enough. The agent is injected by an init container and the original image is untouched.
Q. I already use -javaagent or OMAPM_HOST.
The environment variables you set win (they are not overwritten). JAVA_TOOL_OPTIONS is appended
after the existing value.
Q. What about a pod with several containers?
Name the one container to instrument with openmaru.io/container-names.
Q. Can it be used alongside a CPU/memory HPA?
Yes. A standard HPA's metrics array can hold Resource (cpu/memory) and External (tps) together.
Q. I have several APM servers.
Register each under its alias (name) in envHpa and select with apmAlias in the HPA (see
302 Autoscaling).
6. Troubleshooting at a Glance
| Area | Symptom | What to do |
|---|---|---|
| Installation | The Operator pods do not come up | Check the state and logs with kubectl get pod -n openmaru-apm, and check Helm enabled: true |
| Instrumentation | The agent is not injected | Check the label position (spec.template.metadata.labels) and the value 'true' |
| Instrumentation | The image fails to pull | Check the image built from IMAGE_REGISTRY/IMAGE_NAMESPACE plus was-agent-version exists |
| Instrumentation | Not shown in the APM console | Check OMAPM_HOST/OMAPM_PORT are reachable |
| HPA | TARGETS <unknown> | Check groupName/apmAlias are right and APM is reachable |
| HPA | No scaling | Review minReplicas/maxReplicas and target.value |
7. Commands for Checking
# Operator state
kubectl get pod -n openmaru-apm
kubectl logs deploy/openmaru-operator-apm-agent -n openmaru-apm
kubectl logs deploy/openmaru-operator-apm-hpa -n openmaru-apm
# confirm instrumentation applied
kubectl describe pod <pod> | grep -E "khan-agent-init|khan-data"
kubectl set env pod/<pod> --list | grep -E "OMAPM_|JAVA_TOOL_OPTIONS"
# HPA / external metrics
kubectl get hpa
kubectl get --raw "/apis/external.metrics.k8s.io/v1beta1/namespaces/<ns>/tps" | jq .