Monitoring IBM DataPower

After you install the Instana host agent, IBM DataPower sensor is automatically installed, but you need to configure IBM DataPower sensor as outlined in this topic. Then, you can view metrics that are related to IBM DataPower in the Instana UI.

The Instana DataPower Tracing feature can monitor the API Management capability and examine how APIs start in DataPower API Gateway. To use the Instana DataPower Tracing, you must first install and enable the IBM DataPower Tracing feature. For more information, see IBM DataPower Tracing.

Supported information

Supported operating systems

See Supported operating systems for IBM DataPower sensor.

Supported DataPower versions

Instana supports metrics and configuration data for IBM DataPower 2018.4, 10.0.1.x, 10.0.x and later versions, which are installed in the following platforms:

IBM DataPower sensor supports both local monitoring and remote monitoring.

Operating system Hardware
AIX 7.1 POWER System - Big Endian
macOS Big Sur 11.0 x86-64
Solaris 10 SPARC
Solaris 11 SPARC
Windows Server 2012 Standard Edition x86-64
Amazon Linux 1 x86-64
Amazon Linux 2 x86-64
CentOS 6.0 x86-32
CentOS 6.0 x86-64
CentOS 7 POWER System - Little Endian
CentOS 7 x86-32
CentOS 7 x86-64
CentOS 8 x86-64
Debian 10 x86-32
Debian 10 x86-64
Debian 9.0 x86-32
Debian 9.0 x86-64
Red Hat Enterprise Linux (RHEL) 8 IBM z Systems
Red Hat Enterprise Linux (RHEL) 8 POWER System - Little Endian
Red Hat Enterprise Linux (RHEL) 8 x86-64
Red Hat Enterprise Linux (RHEL) Server 6 IBM z Systems
Red Hat Enterprise Linux (RHEL) Server 6 x86-64
Red Hat Enterprise Linux (RHEL) Server 7 IBM z Systems
Red Hat Enterprise Linux (RHEL) Server 7 x86-64
SUSE Linux Enterprise Server (SLES) 12 IBM z Systems
SUSE Linux Enterprise Server (SLES) 12 POWER System - Little Endian
SUSE Linux Enterprise Server (SLES) 12 x86-64
SUSE Linux Enterprise Server (SLES) 15 IBM z Systems
SUSE Linux Enterprise Server (SLES) 15 POWER System - Little Endian
SUSE Linux Enterprise Server (SLES) 15 x86-64
Ubuntu 14.04 LTS POWER System - Little Endian
Ubuntu 14.04 LTS x86-32
Ubuntu 14.04 LTS x86-64
Ubuntu 16.04 LTS IBM z Systems
Ubuntu 16.04 LTS POWER System - Little Endian
Ubuntu 16.04 LTS x86-32
Ubuntu 16.04 LTS x86-64
Ubuntu 18.04 LTS IBM z Systems
Ubuntu 18.04 LTS POWER System - Little Endian
Ubuntu 18.04 LTS x86-32
Ubuntu 18.04 LTS x86-64
Ubuntu 20.04 LTS IBM z Systems
Ubuntu 20.04 LTS POWER System - Little Endian
Ubuntu 20.04 LTS x86-64

Prerequisites

For Instana agent to be able to monitor IBM DataPower appliance, resource monitoring needs to be enabled, such as REST management interface and statistics.

Configuring

Instana supports monitoring of both the remote and local IBM DataPower appliances. To collect data, you need to configure the following fields in the agent configuration file <agent_install_dir>/etc/instana/configuration.yaml:

com.instana.plugin.ibmdatapower:
  enabled: true
  poll_rate: 60 # Default is 60 seconds
  instances: # Multiple DataPower instances can be specified
    DATAPOWER_INSTANCE_HOST_1: # Remote DataPower Host or IP address
      port: '<INSERT_PORT_HERE>' # DataPower instance REST management interface port
      username: '<INSERT_USERNAME_HERE>' # User account to connect to DataPower
      password: '<INSERT_PASSWORD_HERE>' # User password to connect to DataPower
      cluster: '<INSERT_CLUSTER_HERE>' # The cluster to group multiple DataPower instances (optional)
    DATAPOWER_INSTANCE_HOST_2: # Remote DataPower Host or IP address
      port: '<INSERT_PORT_HERE>' # DataPower instance REST management interface port
      username: '<INSERT_USERNAME_HERE>' # User account to connect to DataPower
      password: '<INSERT_PASSWORD_HERE>' # User password to connect to DataPower
      cluster: '<INSERT_CLUSTER_HERE>' # The cluster to group multiple DataPower instances (optional)
    local: # Local monitoring configuration
      port: '<INSERT_PORT_HERE>' # Local DataPower REST management interface port
      username: '<INSERT_USERNAME_HERE>' # User account to connect to DataPower
      password: '<INSERT_PASSWORD_HERE>' # User password to connect to DataPower

Notes:

  • The poll_rate variable refers to the frequency of data retrieval from IBM DataPower. Its value is expressed in seconds. The default poll_rate value is 60 seconds. If multiple DataPower appliances are configured, increase the value of poll_rate to reduce the CPU usage by the DataPower sensor during each data retrieval interval.
  • If cluster is configured, then the remote DataPower instance is shown as a separate box in the specified availability zone.

Support matrix of IBM DataPower monitoring

The following table outlines the support matrix for IBM DataPower monitoring:

Support matrix Instana agent in a virtual machine Instana agent in a Kubernetes cluster Instana agent in a Docker container
DataPower in a virtual machine Supported Not supported Supported
DataPower in a Kubernetes cluster Supported Supported Supported
DataPower in a Docker container Supported Not supported Supported

Monitoring IBM DataPower in a virtual machine

Local monitoring

Local monitoring occurs when both the Instana agent and IBM DataPower run in the same virtual machine. In such a scenario, you don't need to configure the DataPower host or IP address, but only indicate it as local in the agent configuration file. Then, the IBM DataPower sensor automatically discovers the IP address of the DataPower appliance. See the following configuration example:

com.instana.plugin.ibmdatapower:
  enabled: true
  poll_rate: 60
  instances:
    local:
      port: '5554'       # DataPower instance REST management interface port (required)
      username: 'admin'  # User account to connect to DataPower (required)
      password: 'admin'  # User password to connect to DataPower (required)

Remote monitoring

Remote monitoring occurs when the Instana agent and IBM DataPower run in different virtual machines. In such a scenario, you need to configure the DataPower host or IP address. See the following configuration example:

com.instana.plugin.ibmdatapower:
  enabled: true
  poll_rate: 60
  instances:                   # Multiple DataPower instances can be specified
    10.0.0.1:                  # Remote DataPower Host or IP address
      port: '5554'             # DataPower instance REST management interface port (required)
      username: 'dpUser'       # User account to connect to DataPower (required)
      password: 'dpPassword'   # User password to connect to DataPower (required)
      cluster: 'clusterName'   # The cluster to group multiple DataPower instances (optional)
    datapower-inst.ibm.com:    # Remote DataPower Host or IP address
      port: '443'              # DataPower instance REST management interface port (required)
      username: 'dpUser'       # User account to connect to DataPower (required)
      password: 'dpPassword'   # User password to connect to DataPower (required)
      cluster: 'clusterName'   # The cluster to group multiple DataPower instances (optional)

Monitoring IBM DataPower in a Kubernetes cluster

Local monitoring

Local monitoring occurs when both the Instana agent and IBM DataPower run in the same virtual machine. In such a scenario, you don't need to configure the DataPower host or IP address, but only indicate it as local in the agent configuration file. The configuration is the same as outlined in the Local monitoring section.

The IBM DataPower sensor automatically discovers the IP address of the DataPower appliance. As a result, the sensor cannot differentiate each DataPower appliance. Therefore, all the DataPower appliances that are running in the Kubernetes cluster must have the same port, username, and password.

Remote monitoring

Remote monitoring occurs when the IBM DataPower runs in a Kubernetes cluster, and the Instana agent runs in a different virtual machine. The configuration is the same as outlined in the Remote monitoring section.

Monitoring IBM DataPower in Docker

Local monitoring

Local monitoring occurs when the Instana agent and IBM DataPower run in different Docker containers in the same virtual machine. In such a scenario, you don't need to configure the DataPower host or IP address, but only indicate it as local in the agent configuration file. The configuration is the same as outlined in the Local monitoring section.

Remote monitoring

Remote monitoring occurs when the IBM DataPower runs in a Docker container, and the Instana agent runs in a different virtual machine. The configuration is the same as outlined in the Remote monitoring section.

Viewing metrics

To view the metrics, complete the following steps:

  1. In the sidebar of the Instana UI, select Infrastructure.
  2. Click a specific monitored host.

Then, you can see a host dashboard with all the collected metrics and monitored processes.

Performance metrics

Appliances

Metric Description
System Load The percentage of total load on the device during the measurement interval.
CPU Usage The average CPU usage of the monitored DataPower appliance in the last 10 seconds.
Memory Usage The instantaneous memory usage as a percentage of the total memory.
Encreypted Filesystem Usage Usage of encrypted storage space on the device.
Connection Accepted The number of TCP accepted connections.
Work List The number of pending work items including internal communication in the queue for processing by the appliance.
Quiesced Domains Indicates the quiesce state of the domain.
Inactive Objects Number of inactive objects deployed on the device.
TCP Summary Established The number of TCP connections in the established state.
TCP Summary Syn Sent The number of TCP connections in the syn-sent state.
TCP Summary Syn Received The number of TCP connections in the syn-received state.
TCP Summary Fin Wait1 The number of TCP connections in the fin-wait-1 state.
TCP Summary Fin Wait2 The number of TCP connections in the fin-wait-2 state.
TCP Summary Closed The number of TCP connections in the closed state.
TCP Summary Close Wait The number of TCP connections in the close-wait state.
TCP Summary Time Wait The number of TCP connections in the close-wait state.
TCP Summary Last Ack The number of TCP connections in the last-ack state.
TCP Summary Listen The number of TCP connections in the listen state.
TCP Summary Closing The number of TCP connections in the closing state.

Domains

Metric Description
Current Memory Usage The instantaneous memory usage as a percentage of the total memory within this domain.
XML names
Metric Description
Used The number of XML names that are currently being used in this domain.
Percentage Free The currently available percentage of XML names in this domain.
Peering status
Metric Description
Pending Updates The number of outstanding commands on this member. For more information, see show gateway-peering-status.
Replication Offset The replication offset of a member. The replication offset of a member matches the offset of the primary when they share data-replication.

Ethernet interfaces

Metric Description
RX Bytes Bytes of traffic that is received.
RX Drops Number of received packets that are dropped.
TX Bytes Bytes of traffic that is transmitted.
TX Drops Number of packets that are dropped during transmission.
Received Per Second The number of packets that are received on the network interface per second.
Transmit Per Second The number of packets that are received on the transmitted interface per second.

MQ queue manager

Metric Description
Back-End Active Connections Number of active connections for the backend side.
Front-End Active Connections Number of active connections for the front-end side.

Services

Metric Description
Current Memory Usage The current memory usage by the service in the interval between 1 and 5 minutes ago.
Mean Transaction Time The mean transaction time over the last 10 minutes.
Throughput The transaction rate over the last 10 minutes.

SQL datasource

Metric Description
Active Connections Name of the SQL data source.

Health signatures

For each sensor, there is a curated knowledgebase of health signatures that are evaluated continuously against the incoming metrics and are used to raise issues or incidents depending on user impact.

Built-in events trigger issues or incidents based on failing health signatures on entities, and custom events trigger issues or incidents based on the thresholds of an individual metric of any given entity.

For information about built-in events for the Datapower sensor, see the Built-in events reference.

Troubleshooting

DataPower instance not shown in UI

On the Monitoring Issue list, find out the DataPower related events and check the solution according to the issue type.

Variable not defined

Monitoring issue type: ibmdatapower_var_not_defined

There are one or more required items missing in the configuration. Make sure that your DataPower instance port, username and password are set in the configuration.yaml.

Variable has an invalid value

Monitoring issue type: ibmdatapower_var_invalid_value

One or more required items have an invalid value in the configuration. Make sure that your DataPower instance port, username and password are set correctly in the configuration.yaml.

Connection error

Monitoring issue type: ibmdatapower_connection_error

The DataPower Sensor could not connect to the DataPower instance after many retries. Make sure that your DataPower instance port, username and password are set correctly in the configuration.yaml.

Other exception

Monitoring issue type: ibmdatapower_exception_error

The DataPower Sensor encountered an uncommon exception that is not yet documented. This might mean there is an issue with the Instana Agent or DataPower.