Monitor IBM Or<strong>d</strong>er Management System Containers with Instana agent on Minikube

This tutorial shows how to deploy an IBM Instana agent for IBM Sterling Order Management System (OMS) Containers using the operator on a desktop-sized machine by using Minikube.

Introduction to IBM Sterling Order Management System and IBM Instana

IBM Sterling Order Management System (OMS) supports supply chain and commerce operations for large enterprises. It provides a strong platform for B2C and B2B organizations to innovate, stand out, and run omnichannel businesses with less overhead. To keep up with rapid innovation, enterprises use deployment and automation tools like docker and Kubernetes for speed and efficiency.

IBM Instana is an observability platform for monitoring and troubleshooting microservices and containerized applications. It offers automated performance monitoring, end-user experience tracking, root cause analysis, and anomaly detection, giving complete visibility into the health and performance of applications and services.

Prerequisites

Hardware requirements

At least 100 GB storage
At least 24 GB memory (32 GB recommended)
At least 8 virtual CPUs (16 recommended)

Stack used for demonstration

OS: Red Hat Enterprise Linux 8.10 (Ootpa)
Minikube: v1.32.0

Monitoring tool

IBM Instana SaaS or self-hosted Instana (this tutorial uses IBM Instana SaaS)

Estimated time

This tutorial takes about one hour to complete.

Note: Set up the OMS Operator before starting. For setup steps, see deploying IBM Order Management system and Order Service containers on Minikube.

deployment steps

Step 1. Initialize the Instana agent operator

Apply the Instana agent operator and create the namespace:

kubectl apply -f https://github.com/instana/instana-agent-operator/releases/latest/download/instana-agent-operator.yaml

Verify that the instana-agent namespace is created:

kubectl get namespace

Example output:

NAME                   STATUS   AGE
 default                Active   101d
 ingress-nginx          Active   101d
 instana-agent          Active   6s
 kube-node-lease        Active   101d
 kube-public            Active   101d
 kube-system            Active   101d
 kubernetes-dashboard   Active   101d
 olm                    Active   101d
 oms                    Active   101d
 operators              Active   101d

Create a file named instana-agent.customresource.yaml with the following content:

apiVersion: instana.io/v1
 kind: InstanaAgent
 metadata:
   name: instana-agent
   namespace: instana-agent
 spec:
   cluster:
     name: <instance-url>
   agent:
     key: <your-key>
     downloadKey: <your-download-key>
     endpointHost: <ingress-name>-saas.instana.io
     endpointPort: "443"
     env: {}
     configuration_yaml: |
       # Leave empty or add your Instana agent configuration.
       # See https://ibm.biz/K8s-agent-administer

Apply the YAML to create the Instana Custom Resource definition (CRd):

kubectl apply -f /home/supportuser/instana-agent/instana-agent.customresource.yaml

Step 2. Configure OMS

Open your OMS app server’s server.xml file and check that it includes the following features:

<featureManager>
     <feature>adminCenter-1.0</feature>
     <feature>jdbc-4.1</feature>
     <feature>jndi-1.0</feature>
     <feature>jsp-2.3</feature>
     <feature>servlet-3.1</feature>
     <feature>ssl-1.0</feature>
     <feature>monitor-1.0</feature>
 </featureManager>

In your OMEnvironment YAML, add the JVM argument and environment variables under spec.serverProperties.jvmArgs.propertyList:

spec:
   servers:
     - appServer:
         [...]
       [...]
       property:
         customerOverrides: AppServerProperties
         envVars: EnvironmentVariables
         jvmArgs: JVMArguments
   [...]
   serverProperties:
     customerOverrides:
       derivatives:
         - groupName: AppServerProperties
           propertyList:
             [...]
             # Prometheus properties
             yfs.prometheus.enabled: true
             yfs.prometheus.consolidate.count.enabled: true
     envVars:
       - groupName: EnvironmentVariables
         propertyList:
           AGENT_HTTP_ENABLEd: Y
           AGENT_HTTP_PORT: 8022
     jvmArgs:
       - groupName: JVMArguments
         propertyList:
           - -dcom.instana.agent.jvm.name=oms-appserver

Note: Ensure customerOverrides, envVars, and jvmArgs are also correctly defined under spec.servers.appServer.property. See the OMEnvironment custom resource manifest for details.

After redeploying your app server, check the jvm.options file in /opt/ibm/wlp/usr/servers/defaultServer to confirm the JVM argument was added.

Step 3. IBM MQ setup

For quick testing, you can use a dTK instance as the IBM MQ host. If you use a dTK instance, update the OMS instance’s /etc/hosts file to point to the dTK instance’s IP:
```
# /etc/hosts
   <dTK-instance-ip>  mqserver
```
Go to /home/oms/devtoolkit_docker/compose/docker/mqserver in the dTK instance and update the message delay monitoring level for IBM MQ in config.mqsc and listener.mqsc:
- For Medium monitoring level:
```
sh ALTER QMGR MONQ(MEdIUM) MONCHL(MEdIUM)
```
- For Low monitoring level (recommended for production):
```
sh ALTER QMGR MONQ(LOW) MONCHL(LOW)
```
To apply the MQ configuration changes, run the following in /home/oms/devtoolkit_docker/compose:
```
./om-compose.sh setup
```

Step 4. Configure the Instana agent

Exec into the instana-agent pod and back up the configuration.yaml file from /opt/instana/agent/etc/instana.

On your instance, create a configuration.yaml file and update it to enable the required plugins:

# PostgreSQL
 com.instana.plugin.postgresql:
   user: 'postgres'
   password: 'postgres'

 # IBM MQ
 com.instana.plugin.ibmmq:
   enabled: true
   poll_rate: 10
   queueManagers:
     OM_QMGR:
       host: 'mqserver'  # Use /etc/hosts, localhost, or dTK instance
       port: '1414'
       channel: 'SYSTEM.AdMIN.SVRCONN'
       queuesIncludeRegex: '^dEV.*'  # Allow only dEV-prefixed queues

 # Java Call Tracing
 com.instana.plugin.javatrace:
   instrumentation:
     enabled: true

 # Optional: CPU Profiling for Java (higher overhead in production)
 com.instana.plugin.profiling.java:
   enabled: true

 # Optional: Prometheus metrics (auto-discovery)
 com.instana.plugin.prometheus:
   - url: '/icc/servlets/prometheus'
   - url: '/isccs/servlets/prometheus'
   - url: '/isf/servlets/prometheus'
   - url: '/sbc/servlets/prometheus'
   - url: '/sma/servlets/prometheus'
   - url: '/smcfs/servlets/prometheus'
   - url: '/metrics'

Note: Update the plugin settings to match your environment. For example, configure db2 or PostgreSQL settings based on the database you use.

After updating the file, copy the new configuration.yaml from your instance to the Instana agent pod:

kubectl cp /home/supportuser/instana-agent/configuration.yaml instana-agent-<id>:/opt/instana/agent/etc/instana/configuration.yaml -n instana-agent

To verify the agent’s configuration, exec into the pod and check the file:

kubectl exec instana-agent-<id> -n instana-agent -- cat /opt/instana/agent/etc/instana/configuration.yaml

Step 5. Instana UI setup

Open https://omsnp-ibmaiapps.instana.io/#/home
In the left menu, go to Applications.
Click the + Add button (bottom right) and select New application perspective.
- Under What kind of application would you like to model?, choose Kubernetes or container, then click Next.
- Add the following filters:
  - dest | Kubernetes Cluster > name = <instance-domain>
  - dest | Kubernetes deployment > namespace = oms
  Note: Your instance must be added as a Kubernetes cluster to appear. For more information, see Instana documentation: Application perspectives.
[Optional] Create a service rule using the {jvm.app.name} parameter for better service segmentation. For more details, see Instana documentation: Services.
Once the application perspective is set, create custom dashboards to view MQ and dB performance.

Summary

This tutorial explains how to deploy IBM Instana to monitor an IBM Order Management System (OMS) container on Minikube. It covers initializing the Instana Agent Operator, configuring OMS, and setting up the Instana agent for OMS, MQ, and dB. It includes monitoring PostgreSQL, IBM MQ, Java traces, and Prometheus metrics for performance analysis.

Monitor IBM Order Management System Containers with Instana agent on Minikube