Monitor IBM Order 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

1. 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

   Copy code

2. Verify that the instana-agent namespace is created:

   kubectl get namespace

   Copy code

   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

   Copy code

3. 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

   Copy code

   Apply the YAML to create the Instana Custom Resource Definition (CRD):

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

   Copy code

Step 2. Configure OMS

1. 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>

   Copy code

2. 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

   Copy code

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

3. 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

1. 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

   Copy code

2. 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)

     Copy code

   • For Low monitoring level (recommended for production):

     sh ALTER QMGR MONQ(LOW) MONCHL(LOW)

     Copy code

3. To apply the MQ configuration changes, run the following in /home/oms/devtoolkit_docker/compose:

   ./om-compose.sh setup

   Copy code

Step 4. Configure the Instana agent

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

2. 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'

   Copy code

   Show more

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

3. 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

   Copy code

4. 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

   Copy code

Step 5. Instana UI setup

1. Open https://omsnp-ibmaiapps.instana.io/#/home

2. In the left menu, go to Applications.

3. 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.

4. [Optional] Create a service rule using the {jvm.app.name} parameter for better service segmentation. For more details, see Instana documentation: Services.

5. 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.