Configuring the IBM App Connect Enterprise (ACE) sensor

Prerequisites

Before you configure the IBM ACE sensor, complete the following steps:

1. Verify and activate the resource and message flow statistics collection state. The ACE metrics exist only when you activate the resource and message flow statistics collection.

   • To check the status of resource collection, run the following command:

     mqsireportresourcestats <integrationNode> -e <integrationServer>
     

     If the resource collection state is inactive, activate it by running the following command:

     mqsichangeresourcestats <integratorNode> -e <integrationServer> -c active
     

   • To check the status of message flow statistics, run the following command:

     mqsireportflowstats <integratorNode>  -s -e <integrationServer>  -j
     

     If the message flow collection state is inactive, activate the snapshot statistics collection for all message flows in the specified integration server and node, then emit the data in the JSON format.

     • To activate the snapshot statistics collection without setting the thread data level, run the following command:

       mqsichangeflowstats <integrationNode> -s -e <integrationServer> -j -c active -o json
       

     • To activate the snapshot statistics collection with setting the thread data level, run the following command:

       mqsichangeflowstats <integrationNode> -s -e <integrationServer> -j -t basic -c active -o json
       

     • To activate the snapshot statistics collection with setting both the thread data level and the node data level, run the following command:

       mqsichangeflowstats <integrationNode> -s -e <integrationServer> -j -t basic -n basic -c active -o json
       

     Notes:

     • If you want to check the thread use of each message flow, you need to enable thread data with option -t basic when you are using the mqsichangeflowstats command.
     • You can request two types of data collection, snapshot and archive. The snapshot type is the preferred choice for data collection. For more information, see the corresponding commands in the IIB or ACE docs.

2. Check whether your ACE is using MQTT or IBM MQ. The following commands look for MQTT or IBM MQ process and check if the operational events are published to the ACE sensor.

   • To check for MQTT, run the following command:

     ps -ef | awk '/bipMQTT/ && /<integrationNode>/' 
     mqsireportproperties <integrationNode> -b Events -o OperationalEvents/MQTT -n enabled
     

     To use MQTT as the destination for OperationalEvents publication in the ACE sensor, specify the MQTT port in the configuration.yaml file. If your MQTT is disabled, you can enable it. For more information, see the IBM App Connect documentation and use the preceding command to check the events that are published.

   • To check for IBM MQ, run the following command:

     mqsilist | grep <integrationNode>  # check there is a default queue manager configured.
     mqsireportproperties <integrationNode> -b Events -o OperationalEvents/MQ -n enabled
     

     To use IBM MQ in your ACE, complete the following steps:

     1. Set up a channel or use existing channel for the flow of the performance metrics data for integration server, message flow, and flow node.

     2. Ensure that the channel is accessible through the username or password that is specified in the configuration.yaml file.

     3. Specify the queue manager name and listening port in the configuration.yaml file along with the channel name, username, and password. For more information about channel configuration, see Resolving CHLAUTH access issues.

3. If the monitored server is an independent integration server, ensure that the following requirements are met:

   • Configure the publication of event messages as it is disabled by default. The ACE sensor monitors only OperationalEvents, not BusinessEvents. For more information, see Configuring the publication of event messages.
   • Use ACE 11.0.0.11 or later. Otherwise, you cannot use the UNIX domain socket, since .uds file does not exist for each server.

4. To enable the automatic discovery feature in the traditional ACE environment, ensure that the following requirements are met:

   • The IBM ACE sensor is enabled without configuring integration node or server in the <agent_install_dir>/etc/instana/configuration.yaml file.
   • Permission to access the ACE work path (for example, /var/mqsi/) is available to start the agent.
   • The MQTT process is running properly for the related integration node. To check, run the ps -ef | grep -E 'bipMQTT.*<integrationNode>’ command on the host.

   With automatic discovery, you can see all running integration servers that are listed on the host dashboard of the Instana UI even when all the prerequisites are not met.

Procedure

For the traditional ACE environment, Instana supports monitoring of both remote and local IBM ACE instances. You need to configure the fields in the agent configuration <agent_install_dir>/etc/instana/configuration.yaml file. You can use the following configurations:

• To use remote monitoring, set the IP address of the target ACE server as the value of the host.

• To use the local monitoring, comment out the host attribute. The local monitoring is used by default.

• To monitor brokers or integration servers with the same name on different hosts, use brokerName:x or integrationServer:x as the key of the brokers or integration servers. For example, BK1:1and BK:2.

• To use automatic discovery feature, do not set any field under NodesOrServers. The automatic discovery feature in the ACE sensor discovers all integration servers that are running on the host and starts monitoring them automatically without any configuration.

The minimum poll rate depends on IBM ACE. If the poll rate that you set on Instana is lesser than the minimum poll rate on IBM ACE, the minimum poll rate is applied.

To get tips about how to get the values for these fields, see the Useful tips for ACE sensor configuration blog.

See the following sample configuration.yaml file for ACE configuration:

com.instana.plugin.ace:
  enabled: true
  poll_rate: 60                  
  forceRemote: false             
  flowNodesExcludedRegex: ''     
  NodesOrServers:                
    SampleNode/Server:                  
      host: '<ACE_SERVEr_HOST>'                
      restApiPort: '<ACE_REST_API_PORT>'      
      aceUsername: '<VIWER_USER>'              
      acePassword: '<VIWER_USER_PASSWORD>'    
      keystore: '<ACE_KEYSTORE_PATH>'         
      keystorePassword: '<ACE_KEYSTORE_PASSWORD>'     
      excludedServers: '<INTEGRATION_SERVER_NAMES>'   
      flowNodesExcludedRegex: ''                
      availabilityZone: 'IBM ACE Custom Zone'   
      mqHost: '<MQ_HOST>'                       
      mqport: '<MQ_LISTENING_PORT>'             
      queuemanagerName: '<QMGR_NAME>'           
      channel: '<SVRCONN_CHANNEL>'              
      mqUsername: '<AUTHORIZED_USER>'           
      mqPassword: '<USER_PASSWORD>'             
      mqKeystore: '<MQ_KEYSTORE_PATH>'          
      mqKeystorePassword: '<MQ_KEYSTORE_PASSWORD>' 
      mqCipherSuite: '<MQ_CIPHER_SUITE>'           

The following table contains the configuration parameters and their description: