Specific fields for Java Management Extensions (JMX) MBeans

The syntax of the metric name for a JMX Attribute group consists of tokens separated by a period. The tokens form primary values and optionally secondary values:

• Primary value: a value obtained directly from the MBean or Notification in a given row of the table. Primary values from an MBean are obtained either from an MBean attribute or from the invocation of an MBean operation (method call). Primary values from a Notification are obtained from a field or invocation of a method on the Notification object. Primary values can be primitive types, or can be Java objects.
• Secondary value: a value obtained by further processing a primary value or other secondary value. Secondary values are processed internally to the engine and do not involve calls to the JMX server. If the primary (or other secondary value) is a Java object, a secondary value is the result of fetching a public field from that object, or the result of a method call on that object. Such secondary values are obtained using Java introspection of the primary (or other secondary) Java object. If the primary (or other secondary) value is a Java String in the form of an MBean name, the secondary value can also be the domain or any of the properties that make up the MBean name.

The following syntax describes the format for the Metric name field:

Metric Name	=	PrimaryValue [ .SecondaryValue ]
PrimaryValue	=	Attribute.attributeName |
		Method.methodName |
		Domain |
		Property.propertyName |
		Field.fieldName |
		Name
SecondaryValue	=	Field.fieldName |
		Method.methodName |
		Domain |
		Property.propertyName |
		Explode |
		ElementCount

propertyName	=	the name of a key property in an MBean ObjectName
attributeName	=	the name of an MBean attribute
methodName	=	a zero-argument operation of an MBean or a zero-argument method 
of a Notification or other Java object. 
methodName(argument) = A single-argument operation of an MBean or a 
single-argument method of a Notification or other Java object. The 
argument will be passed to the method as a string.
fieldName	=	the name of a public instance variable in a Notification or 
other Java object
notificationMethod	=	the name of a public zero-argument method of a 
Notification object

By including only a primary value in the metric name definition, the data collected can be any of the following items:

• MBean domain
• MBean string value
• Key property from the MBean name
• Numeric or string attribute value on an MBean attribute (including the full name of another MBean) a numeric or string return value from one of an MBean operations
• Value of a numeric or string public instance variable in a Notification object
• Numeric or string return value from one of a Notification's operations

By adding a secondary value to the metric's definition, you can drill down into a Java object's primary value, and invoke a public method or fetch a public instance variable.

By adding a secondary value to another secondary value in the metric's definition, you can drill down into a secondary value object. This can continue as deeply as objects are nested inside an MBean or a Notification.

Tokens that make up primary and secondary values are either keywords or names. In most cases, a keyword token is followed by a name token. The following table shows some examples:

Metric name sample	Attribute group type	Description of the data returned
Domain	MBean	The domain portion of the MBean (the part before the colon).
Name	MBean	The full string representation of the MBean.
Attribute.serverVendor	MBean	MBean attribute serverVendor.
Method.getHeapSize	MBean	The value returned by the getHeapSize() on the MBean.
Property.j2eeType	MBean	The value of j2eeType is extracted from the MBean name.
Field.Message	Event (Notification)	The Message field in a notification.

The keywords Attribute, Method, and Field can return Java objects which contain other data. You can perform operations on those objects by appending secondary value definitions. More examples:

Metric name sample	Attribute group type	Description of the data returned
Attribute.deployedObject. Method.getName	MBean	Takes the deployedObject attribute from the MBean and gets the result of the getName() method.
Attribute.eventProvider. Method.getException. Method.getDescription	MBean	This goes three deep: an attribute named eventProvider is presumed to be an object which has a getException() method. This method returns an object with a getDescription() method. That method is called and the return value is put in the column.
Attribute.HeapMemoryUsage. Method.get(used)	MBean	Takes the HeapMemoryUsage attribute from the MBean and gets the result of the get(String value) method. The string used is passed to the method as the argument. Only one argument can be provided and it must be a literal string value. Shows how you can collect data from an open MBean composite data structure.

Note that Domain and Property can be used as keywords in secondary values if the previous value returned a String in the format of an MBean name. For example:

Metric name sample	Attribute group type	Description of the data returned
Attribute.jdbcDriver. Property.name	MBean	The attribute jdbcDriver returns an MBean name, and the key property, name, is extracted from the MBean name.
Attribute.jdbcDriver.Domain	MBean	The attribute jdbcDriver returns an MBean name, and the domain is extracted from the MBean name.

The ElementCount and Explode keywords perform operations on arrays or collections of data.

• ElementCount - returns the number of elements in an array.
• Explode - this explodes a row into several rows, one new row for each element of an array.

Examples of each of the above:

Metric name sample	Attribute group type	Description of the data returned
Attribute.deployedObjects. ElementCount	MBean	The MBean attribute deployedObjects is an array, and this column will contain the number of elements in the array.
Attribute.deployedObjects. Explode.MBean.Property. j2eeType	MBean	This causes the table to have one row for each element in deployed objects. This column contains the deployed Object's j2eeType.
Attribute.SystemProperties. Method.values.Explode. Method.get(key)	MBean	Causes you to get one new row for each entry in an open MBean tabular data structure. Each tabular data structure contains a composite data structure with an item named key, which is returned.