Integrating with IBM APM V8
TABLE OF CONTENTS
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.
Confirmed support for metrics for IBM Application Performance Monitoring V8.1.4 IF 10 with the following APM agents:
- Linux OS agent V220.127.116.11.14; supported on xLinux,zLinux,pLinux
- Datapower agent V18.104.22.168.14
- Windows OS agent V22.214.171.124.14
- Unix OS agent V126.96.36.199.14; supported on AIX
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 188.8.131.52, IF 10 or higher, on-premise only IBM Cloud Application Performance Management Advanced Private, Version 184.108.40.206, IF 10 or higher, on-premise only
The instructions for applying Interim Fix 10 for the APM V220.127.116.11 server can be found here: https://supportcontent.ibm.com/support/pages/ibm-application-performance-management-814-8140-ibm-apm-server-if0010-readme
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.
- Sign in to Instana, click More -> Agents -> Instana agent installation -> IBM.
- From the dropdown list, select IBM APM V8 Instana Integration Proxy.
- Download the APM V8 Instana Integration Proxy tgz file using the download button.
- Transfer the file from your default browser download location to your APM V8 server.
- Extract the tgz to a temporary location.
- Change to the sub-directory and locate the eba file.
- 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.
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:
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
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.
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 issue type:
There are one or more required items missing in the configuration. Make sure that your host is set in the configuration.yaml.
Monitoring issue type:
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).
Monitoring issue type:
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.
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.
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.