Integrating with IBM APM V8

Activating IBM APM V8 support

Metric ingestion via the IBM APM V8 proxy sensor in the host agent is deactivated by default. To enable the reception of IBM APM V8 data in the host agent, please refer to the Sensor configuration section below.

Supported Versions

Confirmed support for metrics for IBM Application Performance Monitoring V8.1.4 IF 10 with the following APM agents:

  • Linux OS agent V8.1.4.0.14; supported on xLinux,zLinux,pLinux
  • Datapower agent V8.1.4.0.14
  • Windows OS agent V8.1.4.0.14
  • Unix OS agent V8.1.4.0.14; supported on AIX

Platforms and Pre-requisites

The support for integrating APM V8 with Instana is supported on the IBM Cloud Application Performance Management server platforms documented here: https://www.ibm.com/docs/en/capmp/8.1.4?topic=deployment-system-requirements

This support is intended to be applied to any of the following levels of IBM Cloud Application Performance Management server software:

IBM Cloud Application Performance Management Base Private, Version 8.1.4.0, IF 10 or higher, on-premise only IBM Cloud Application Performance Management Advanced Private, Version 8.1.4.0, IF 10 or higher, on-premise only

The instructions for applying Interim Fix 10 for the APM V8.1.4.0 server can be found here: https://supportcontent.ibm.com/support/pages/ibm-application-performance-management-814-8140-ibm-apm-server-if0010-readme

Configuration

Dependencies

In order for the sensor to gather metrics from the APM V8 server, an update needs to be made to the APM V8 server. To obtain the necessary file, follow the steps below.

  1. Sign in to Instana, click More -> Agents -> Instana agent installation -> IBM.
  2. From the dropdown list, select IBM APM V8 Instana Integration Proxy.
  3. Download the APM V8 Instana Integration Proxy tgz file using the download button.
  4. Transfer the file from your default browser download location to your APM V8 server.
  5. Extract the tgz to a temporary location.
  6. Change to the sub-directory and locate the eba file.
  7. Copy the eba file to the APM V8 Min server's dropins directory (default location is /opt/ibm/wlp/usr/servers/min/dropins). The eba will be automatically loaded by the Min server.

Sensor configuration

To enable the ibm-apmproxy sensor, locate the ibmapmproxy section of the agent configuration file and uncomment the lines for the sensor. Provide the host, protocol and port information for your APM V8 server in the corresponding fields: <agent_install_dir>/etc/instana/configuration.yaml:

com.instana.plugin.ibmapmproxy:
  enabled: true
  # host: Provide the hostname or IP address of the system where the APM V8 server is running.  No quotation marks are needed.
  host: '<INSERT_HOST_HERE>' # APM-Proxy host
  # port: provide the port defined for contacting the APM V8 server. No quotation marks are needed.
  port: 443 # APM-Proxy port Default
  datainterval: 1 # Default
  heartbeatinterval: 15 # Default  
  # protocol: indicate whether to connect with the APM V8 server using the secure (SSL) port or the insecure port.  Values are either "http" or "https".  Default is "https".  No quotation marks are needed. Ensure the value provided for the "port" variable is the appropriate port for your server.
  protocol: https # Default

Metrics collection

See the Instana Host sensor for the list of collected metrics from the Linux OS agent, the Windows OS agent and the Unix OS agent. See the Instana IBM Datapower sensor for the list of collected metrics from the IBM Datapower agent.

Note: the support for IBM Datapower metrics through this integration requires the Instana server to be Build 201 or higher.

Note: several metrics expected in the Instana Host and Datapower-related entities are not currently collected by the APM V8 agents. These metrics will be blank or null in the Instana UI.

Metrics are collected from the supported V8 agents attached to the APM V8 server and forwarded to Instana, resulting in the creation of Host and Datapower entities on the Instana UI.

Note: metrics are collected by the APM V8 agents at the interval defined by their existing subscription files. The available metrics from all supported agents are retrieved by the apmproxy sensor every one second as they become available at the V8 server.

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.

Events may be raised against the Host or Datapower entities created by forwarding the APM V8 metrics to the Instana server. See the possible events for the Host entity Built-in events reference or the Datapower entities Built-in events reference. Events can also be raised against the Agent to indicate that the sensor is missing configuration or experiencing a connection issue (see 'Monitoring Issues' below).

Monitoring Issues

Missing Configuration

Monitoring issue type: apmproxy_missing_config

There are one or more required items missing in the configuration. Make sure that your host is set in the configuration.yaml.

Connection Error

Monitoring issue type: apmproxy_connection_error

The IBM-APMProxy Sensor could not connect to the APM-Proxy server, after many retries. Make sure that your configuration properties are correctly set in the configuration.yaml. Make sure the protocol and port values are aligned (e.g., port 80 with protocol http or port 443 with protocol https).

Other Exception

Monitoring issue type: apmproxy_exception_error

The IBM-APMProxy Sensor encountered an uncommon exception that is not yet documented. This might mean there is an issue with the Instana Agent or APM-Proxy Server.

Additional Information

It is recommended that the Instana agent be installed directly on the APM V8 server, but it is not required. If the Instana agent is installed on a remote server, please make sure the APM V8 server IP address is reachable from the remote server. In addition, it may be desirable to disable monitoring of the APM V8 server system itself by disabling the other sensors listed in the agent configuration file, leaving only the ibm-apmproxy sensor enabled.

Performance considerations

If the volume of APM V8 agents to be integrated is more than a couple of hundred agents, the JVM memory available to the Instana host agent with the ibm-apmproxy sensor enabled should be increased.
See Setting host agent CPU and memory for information on how to increase the JVM memory for the Instana host agent. It is recommended to increase the host agent's maximum memory by 256m beyond the current setting.