Setting Up JMX Agent for BAM

The JMX agent for BAM is used to monitor JMX attributes of a required JMX enabled server (Ex- Carbon based servers) and store the monitored data in BAM. The user can install the JMX agent either on a BAM server or any Carbon based server. The monitored data is sent to the BAM server using the Thrift API of BAM.

Installing JMX Agent

1. Download and setup WSO2 BAM or any other server you wish to install the JMX agent in. Installation instructions can be found in respective documentation.

   In this guide, JMX agent is installed on WSO2 BAM to monitor JMX attributes of BAM server itself and store related data in BAM. Similarly, JMX agent can be installed in any other Carbon-based server and use them to transfer data to WSO2 BAM.

2. To start the BAM server, execute:
   
   • on Linux CARBON_HOME/bin/wso2server.sh
   • on MS Windows CARBON_HOME\bin\wso2server.bat
3. In the management console, select Features under Configure menu. 
4. In the window that opens, select the Repository Management tab. 
5. Select a P2 repository either from a URL or a file. You need Carbon 4.0.5 feature repository or an earlier version (http://dist.wso2.org/p2/carbon/releases/4.0.5). Click Add.
    
6. Navigate to Available Features tab on the same window and select the repository added above. Then click Find Features.  
7. From the list of features that appears, select BAM JMX Agent Aggregate feature and click Install.
   If you select Group features by category option, the feature appears inside BAM Data Agents as follows:
    
8. Restart the server. (Shutdown/restart sub menu of the Main menu in the management console).

Using the JMX agent

1. In the management console, select JMX Agent from the Configure menu.
2. If there are any existing JMX monitoring profiles, they appear here. Each JMX monitoring profile is used to monitor a set of attributes from a single JMX server.
   You can enable/disable monitoring of JMX attributes from here and also edit the monitoring profiles.
   
3. To add a new monitoring profile, click Add Profile link and fill the required fields.
   
   
   • In the Basic information section, enter a unique profile name.
   • In the Data Receiver Information section,
   • Receiver address - The address used to send the data to BAM
   • Secure address - The address used to authenticate the data publishing request
   • username - The username for the data publisher
   • password - The password for the data publisher
   • schedule - Can configure how often the attributes should be monitored using a cron expression
   • In the JMX Server Information section, 
   • server URL - The JMX server URL. In this example we can use service:jmx:rmi://localhost:11111/jndi/rmi://localhost:9999/jmxrmi since we will be monitoring BAM it self.
   • username - The username for the JMX server
   • password - The password for the JMX server
4. Click Load MBeans.
5. Click an MBean from the list that loads to see its attributes list. 
6. Add required attributes to the list that is monitored by this profile and save the pofile. You can set an alias to easily identify the data in the Cassandra database.
7. The newly-added JMX profile starts monitoring the attributes and publishing them to the Cassandra database. The data is published to the EVENT_KS with the name in org_wso2_bam_jmx_agent_<PROFILE_NAME> format. If you set an alias for the attribute, it will also be visible here.