Chapter 30. General Tasks
30.1. Setting up a Custom JVM for Discovery
The Generic JMX Plug-in detects Java processes. This is a very simple plug-in; aside from the ability to exclude some types of JVMs, the plug-in detects any properly-configured Java process and imports it is as a JMX server. For a generic JMX server, all of its subsystems — logging, threads, memory, and others — are also imported as children of the JMX server.
All of this background information is covered in the JMX resource documentation in the Resource Reference: Monitoring, Operation, and Configuration Options. Writing a custom plugin is covered in Writing Custom Plug-ins.
A JVM resource itself has to be configured in a certain way for JBoss ON to be able to discover the resource to add it to the inventory.
30.1.1. Required JVM Configuration for Discovery
The agent discovers and subsequently manages a resource by identifying the resource based on certain parameters and then connecting to the agent over those discovered settings. For a Java process to be discovered using the Generic JMX Plug-in, it has to be configured to be connected to in one of two ways:
- Sun JMX remoting is enabled, with a port system property specified in the command line.
-Dcom.sun.management.jmxremote.port=12345 com.xyz.MyAppMain
- A Sun/Oracle-compatible Java process is accessible through the
com.sun.tools.attachAPI, and the resource key is specified as a system property in the command line.-Dorg.rhq.resourceKey=KEY com.xyz.MyAppMain
30.1.2. Excluding Java Processes from Discovery
The Generic JMX Plug-in is designed to be extended so that custom plug-ins can be based off it to detect and manage specific types of Java processes. For example, the JBoss ON agent, as a Java process, would normally be detected by the Generic JMX Plug-in, but it is discovered by the Agent Plug-in, which trumps the Generic JMX Plug-in. Similarly, JBoss EAP and Tomcat servers are also discovered by server-specific plug-ins, not the generic plug-in.
Resources which can be discovered by another plug-in should be excluded from the Generic JMX Server discovery, or there could be (spurious) conflict errors recorded in the agent log.
The Java processes to exclude from the discovery scan are defined in the JBoss ON agent configuration. There is a Java option for the agent,
rhq.jmxplugin.process-filters, which lists strings to ignore specifically from the Generic JMX Plug-in discovery scan. If a Java process contains any of the strings in the filter, it is excluded from discovery as a JMX server[6].
The default agent configuration filters out the classes for the agent, the JBoss ON server, and Tomcat servers:
RHQ_AGENT_ADDITIONAL_JAVA_OPTS="-Drhq.jmxplugin.process-filters=org.rhq.enterprise.agent.AgentMain,org.jboss.Main,catalina.startup.Bootstrap"
To add excludes filters:
- Open the agent configuration file.
[jbosson-agent@server ~]$ vim agentRoot/rhq-agent/conf/agent-configuration.xml
- In the
RHQ_AGENT_ADDITIONAL_JAVA_OPTSlink, add the string to exclude to therhq.jmxplugin.process-filtersoption. This can be the classname or any other identifying string which is in the command line for the given process.For example:RHQ_AGENT_ADDITIONAL_JAVA_OPTS="-Drhq.jmxplugin.process-filters=org.rhq.enterprise.agent.AgentMain,org.jboss.Main,catalina.startup.Bootstrap
,com.abc.OtherAppMain"Therhq.jmxplugin.process-filtersvalue is a comma-separated list of strings. - Restart the agent with the
--configoption to load the new configuration.[jbosson-agent@server ~]$ agentRoot/rhq-agent/bin/rhq-agent.sh --config
30.1.3. Manually Importing a JVM Resource
As Section 30.1.1, “Required JVM Configuration for Discovery” describes, there are only two connection configurations that can be used for a Java process for it to be discovered automatically by the agent. Specifically, those two connection settings both use a Sun management API, for remoting or for attach.
Any Java process can be imported into the inventory manually, even if it does not use the expected configuration for autodiscovery, as long as it enables JMX remoting in a supported form, meaning Sun or IBM remoting.
Note
The JVM instance has to be running for the resource to be discovered and imported.
- Click the Inventory tab in the top menu.
- Select the platform resource.
- Click the Inventory tab of the platform.
- Click the Import button in the bottom of the Inventory tab, and select the JMX server resource type.
- Select the type of JVM, and set all of the connection properties correctly, depending on the type of JVM selected.
- Fill in the connection information for the JVM. This varies depending on the JVM type, but it includes options like a URL and port, directory paths for client libraries, directory paths for classes, and login credentials.
- Click the to import the instance.
