Model MBean Naming and Descriptor Data

Topics marked with * relate to features available only in vFabric Hyperic.

This page specifies the descriptors that ModelMBeans must expose to enable a Hyperic Agent to discover and manage Java application resources.

For information about Java service discovery feature and associated requirements, see Java Applications.

Key Facts About ModelMBeans and Service Discovery

  • Hyperic translates ModelMBeanInfo into service metadata, ModelMBeanAttributeInfo into custom property or metric metadata, and ModelMBeanOperationInfo into control action metadata.

  • All MBean instances with the same type must have the same attributes, metrics, and operations. If the metadata for a service type changes the type will be updated in Hyperic and any existing service instances will be deleted and redeployed.

  • A service type cannot be deleted from Hyperic.

ModelMBean ObjectName Format

An ModelMBean's ObjectName must have this format:

spring.application:application=%application%,type=%type%,name=%name%*

where:

  • application - (Optional) The name of the application that contains the resource. If defined, forms a portion of the service name in Hyperic.

  • type - (Required) The Hyperic service type for the resource. When Hyperic creates the service to add to inventory, this is the service type it will have. The value of type also forms a portion of the service name in Hyperic.

  • name - (Required) An identifier that forms a portion of the name of the service in Hyperic. The service name also includes: name of the platform (machine) where the service runs, value of application if specified, and the Hyperic server type where the service runs. The order in which these components are concatenated into a name varies by the type of server where the service runs.

For an MBean whose ObjectName is:

spring.application:application=swf-booking-mvc,type=MessageListener,name=bookingMessageListener

the Hyperic Agent creates a service in Hyperic whose:

  • Service type is "MessageListener"

  • Name is "Platform Name Apache Tomcat 6.0 swf-booking-mvc bookingMessageListener MessageListener"

ModelMBeanInfo Descriptors

ModelMBean Field

Description

Type

Requirements

Default Value

ModelMBeanInfo.
getDescription()

The friendly description of the service

String

Must not be null

N/A

ModelMBeanInfo.
getMBeanDescriptor().
getField("typeName")

If supplied, supplies the service type for the service to be created in Hyperic, overriding the default value - the value of type from the service's ObjectName.

String

Optional

Value of the type property in the resource's ObjectName, described in ModelMBean ObjectName Format

ModelMBeanInfo.
getMBeanDescriptor().
getField("export")

Can be used to prevent the Hyperic Agent from creating a service for the MBean in Hyperic inventory.

String

Set to "true" or "false"

"true"

ModelMBeanAttributeInfo Descriptors

The Hyperic Agent interprets ModelMBeanAttributeInfo as property or metric data. If the "metricType" descriptor is defined, Hyperic interprets the data as a metric.

An attribute that represents a property must be JMX SimpleType or an array of JMX SimpleTypes.

An attribute that represents a  metric must be numeric JMX SimpleType.

ModelMBean Field 

Description

Type

Expected Format

Default Value

ModelMBeanAttributeInfo.
getDescription()

Description of the property or metric.  

Note:  In the Hyperic user interface, a property is identified by its Description.

String

Must not be null.
 

N/A

ModelMBeanAttributeInfo.
getDescriptor().
getField("metricCategory")

Category of a Metric

String

Allowable values:

PERFORMANCE - a metric that provides time-related information. For example, average elapsed time per method call.

UTILIZATION - a metric that indicates resource usage. For example, memory usage, cache size, thread pool size.

THROUGHPUT - a metric that indicates the amount of work done over a period of time. For example, transactions per second.

UTILIZATION

ModelMBeanAttributeInfo.
getDescriptor().
getField("displayName")

Name that uniquely identifies the metric for a service type.    

String

This value is used to uniquely identify the metric per service type.

Defaults to the name of the ModelMBean attribute.

getDescriptor().
getField("indicator")

Designates a metric as an Indicator in Hyperic. 

Indicators are presented on a resource's Indicator page in Hyperic.

String

If set to "true", the metric is an Indicator, and is collected by default.

NOTE: If "false" metric will NOT be collected by default.

"true"

ModelMBeanAttributeInfo.
getDescriptor().
getField("metricType")

Indicates how the value of the metric changes over time.  

The presence of this field indicates the MBeanAttribute is a metric. If not set, the attribute will be considered a custom property.

Hyperic sets the collection interval for a metric based on the value of metricType.

"counter" metrics are collected every 10 minutes.

"gauge" metrics arecollected every 5 minutes.

String

The JMX specification requires metricType have a value of either:

  • "counter" - a metric whose value does not decrease unless it is reset to a starting value. "Number of requests received" is an example of a counter metric. Counter metrics usually have a positive integer value.

  • "gauge" - a metric whose value can either increase or decrease. "Cache Hit Rate" is an example of a gauge metric.

"gauge"

ModelMBeanAttributeInfo.
getDescriptor().
getField("units")

The unit in which an metric is measured.

String

Hyperic specifies these allowable values:

  • B - Bytes

  • KB - Kilobytes

  • MB -  Megabytes

  • GB - Gigabytes

  • TB - Terabytes

  • epoch-millis - Time since January 1, 1970 in milliseconds.

  • epoch-seconds - Time since January 1, 1970 in seconds.

  • ns - Nanoseconds

  • mu - Microseconds

  • ms - Milliseconds

  • jiffys - Jiffies (1/100 sec)

  • s - Seconds

  • cents - Cents (1/100 of 1 US Dollar)

  •  none

Defaults to "none" if not specified or if set to an unrecognized unit.

ModelMBeanOperationInfo Descriptors

ModelMBean Operation return values and parameters should be JMX SimpleType or arrays of JMX SimpleTypes.

ModelMBean Field

Description

Type

Expected Format

Default Value

ModelMBeanOperationInfo.
getDescription()

The friendly description of the Operation

String

Must not be null.

N/A