Chapter 12. Management and Monitoring

Chapter 12. Management and Monitoring
Prev	Part 6. Kodo JPA/JDO Reference Guide	Next

12.1. Configuration
12.2. Kodo Management Console
12.3. Accessing the MBeanServer from Code
12.4. MBeans

The management and monitoring capability uses the Java Management Extensions (JMX) standard to allow for both local and remote management of key:

Attributes
Operations
Notifications / Performance Statistics

	Important
	This feature requires Kodo Enterprise Edition or Kodo Standard Edition with the Performance Pack.

The unit of management in JMX is the Managed Bean (MBean). Kodo provides a number of MBeans that allow management of key components. For example, the connection pool MBean provides statistics on the numbers of active and idle connections, and allows modification of the attributes controlling the maximum number of active connections.

The default JMX implementation used by Kodo is MX4J version 1.1.1 (see mx4j.sourceforge.net). The MX4J jar, mx4j-jmx.jar, is included in the Kodo distribution, and is covered under the MX4J license, which can be found in the lib directory. To use a different implementation, simply remove the mx4j-jmx.jar file from your CLASSPATH and insert the appropriate jars for your JMX implementation.

Note that the resource archive kodo.rar provided with Kodo does not include MX4J. This is because most application servers provide their own JMX implementation. However, a small subset of the MX4J implementation is included.

The management and monitoring capability can be run both locally and remotely. An example of its use can be found in the management sample described in Section 1.2.2, “JMX Management”.

12.1. Configuration

12.1.1. Optional Parameters in Management Group
12.1.2. Optional Parameters in Remote Group
12.1.3. Optional Parameters in JSR 160 Group
12.1.4. Optional Parameters in WebLogic 8.1 Group
12.1.5. Configuring Logging for Management / Monitoring

The Management capability is configured via the standard Kodo configuration system using the kodo.ManagementConfiguration property. This property is a plugin string (see Section 2.5, “Plugin Configuration”), so you can also set it to the full class name of a custom ManagementConfiguration. Pre-defined values are:

none: No management or profiling turned on. This is the default.
profiling-gui: Turn on the local profiling GUI (see Section 13.1, “Profiling in an Embedded GUI” for more configuration information).
profiling-export: Export profiling data (see Section 13.2, “Dumping Profiling Data to Disk from a Batch Process” for more configuration information).
profiling: Enable profiling without export or GUI. Useful when trying to access the ProfilingAgent programmatically.
mgmt: Enable management. Suitable for use in JBoss and other environments where all MBeans should be registered with a JMX MBeanServer for either management via a user defined mechanism, or via a mechanism defined by the MBeanServer. Supports optional parameters in the Management Group (see Section 12.1.1, “Optional Parameters in Management Group”).
mgmt-prof: Enable management, including profiling. Suitable for use in JBoss and other environments where all MBeans should be registered with a JMX MBeanServer for either management via a user defined mechanism, or via a mechanism defined by the MBeanServer. Supports optional parameters in the Management Group (see Section 12.1.1, “Optional Parameters in Management Group”). Also supports optional parameters described in Section 13.3, “Controlling How the Profiler Obtains Context Information”.
mgmt-export: Enable management, and enable a profiling export. Suitable for use in JBoss and other environments where all MBeans should be registered with a JMX MBeanServer for either management via a user defined mechanism, or via a mechanism defined by the MBeanServer. Supports optional parameters in the Management Group (see Section 12.1.1, “Optional Parameters in Management Group”). Also supports optional parameters described in Section 13.3, “Controlling How the Profiler Obtains Context Information” and Section 13.2, “Dumping Profiling Data to Disk from a Batch Process”.
mx4j1-remote-mgmt: Enable remote management via MX4J v.1.x implementations (supporting versions of the JMX specification prior to 1.2). Supports optional parameters in the Management Group (see Section 12.1.1, “Optional Parameters in Management Group”) and the Remote Group (see Section 12.1.2, “Optional Parameters in Remote Group”).
mx4j1-remote-mgmt-prof: Enable remote management, including remote profiling via MX4J v.1.x implementations (supporting versions of the JMX specification prior to 1.2). Supports optional parameters in the Management Group (see Section 12.1.1, “Optional Parameters in Management Group”) and the Remote Group (see Section 12.1.2, “Optional Parameters in Remote Group”). Also supports optional parameters described in Section 13.3, “Controlling How the Profiler Obtains Context Information”.
mx4j1-remote-mgmt-export: Enable remote management, and enable a profiling export via MX4J v.1.x implementations (supporting versions of the JMX specification prior to 1.2). Supports optional parameters in the Management Group (see Section 12.1.1, “Optional Parameters in Management Group”) and the Remote Group (see Section 12.1.2, “Optional Parameters in Remote Group”). Also supports optional parameters described in Section 13.3, “Controlling How the Profiler Obtains Context Information” and Section 13.2, “Dumping Profiling Data to Disk from a Batch Process”.
jmx2-remote-mgmt: Enable remote management via JMX v.1.2 implementations (supporting JSR 160 for remote management). Supports optional parameters in the Management Group (see Section 12.1.1, “Optional Parameters in Management Group”) and the JSR 160 Group (see Section 12.1.3, “Optional Parameters in JSR 160 Group”).
jmx2-remote-mgmt-prof: Enable remote management, including remote profiling via JMX v.1.2 implementations (supporting JSR 160 for remote management). Supports optional parameters in the Management Group (see Section 12.1.1, “Optional Parameters in Management Group”) and the JSR 160 Group (see Section 12.1.3, “Optional Parameters in JSR 160 Group”). Also supports optional parameters described in Section 13.3, “Controlling How the Profiler Obtains Context Information”.
jmx2-remote-mgmt-export: Enable remote management, and enable a profiling export via JMX v.1.2 implementations (supporting JSR 160 for remote management). Supports optional parameters in the Management Group (see Section 12.1.1, “Optional Parameters in Management Group”) and the JSR 160 Group (see Section 12.1.3, “Optional Parameters in JSR 160 Group”). Also supports optional parameters described in Section 13.3, “Controlling How the Profiler Obtains Context Information” and Section 13.2, “Dumping Profiling Data to Disk from a Batch Process”.
local-mgmt: Enable management, bringing up the JMX management console in the local JVM. Supports optional parameters in the Management Group (see Section 12.1.1, “Optional Parameters in Management Group”).
local-mgmt-prof: Enable management, including profiling, bringing up the JMX management console in the local JVM. Supports optional parameters in the Management Group (see Section 12.1.1, “Optional Parameters in Management Group”). Also supports optional parameters described in Section 13.3, “Controlling How the Profiler Obtains Context Information”.
local-mgmt-export: Enable management, bringing up the JMX management console in the local JVM, and enable a profiling export. Supports optional parameters in the Management Group (see Section 12.1.1, “Optional Parameters in Management Group”). Also supports optional parameters described in Section 13.3, “Controlling How the Profiler Obtains Context Information” and Section 13.2, “Dumping Profiling Data to Disk from a Batch Process”.
wl81-mgmt: Enable WebLogic 8.1 management. Supports optional parameters in the Management Group (see Section 12.1.1, “Optional Parameters in Management Group”) and the WebLogic 8.1 Group (see Section 12.1.4, “Optional Parameters in WebLogic 8.1 Group”).
wl81-mgmt-prof: Enable WebLogic 8.1 management, including remote profiling. Supports optional parameters in the Management Group (see Section 12.1.1, “Optional Parameters in Management Group”) and the WebLogic 8.1 Group (see Section 12.1.4, “Optional Parameters in WebLogic 8.1 Group”). Also supports optional parameters described in Section 13.3, “Controlling How the Profiler Obtains Context Information”.
wl81-mgmt-export: Enable WebLogic 8.1 management, and enable a profiling export. Supports optional parameters in the Management Group (see Section 12.1.1, “Optional Parameters in Management Group”) and the WebLogic 8.1 Group (see Section 12.1.4, “Optional Parameters in WebLogic 8.1 Group”). Also supports optional parameters described in Section 13.3, “Controlling How the Profiler Obtains Context Information” and Section 13.2, “Dumping Profiling Data to Disk from a Batch Process”.

12.1.1. Optional Parameters in Management Group

Those kodo.ManagementConfiguration plugins that provide JMX based management have three optional parameters, described in this section.

If JMX based management is desired, Kodo needs to either find an existing MBeanServer or create a new one. Appropriate plugins for the configuration property kodo.ManagementConfiguration have an optional parameter MBeanServerStrategy that allows for configuration of this process. The following options are available:

any-create: Attempt to find an existing MBeanServer. If multiple are found, use the first one. If none are found, create a new server. This is the default.
create: Do not attempt to find an existing MBeanServer. Always create a new server.
agentId:<agent id>: Attempt to find an existing MBeanServer with the given agent id. If such a server is not found, create a new server.

For example, in order to force creation of a new MBeanServer when doing remote management, include the following line in your configuration:

JPA XML format:

<property name="kodo.ManagementConfiguration" value="remote-mgmt(MBeanServerStrategy=create)"/>

JDO properties format:

kodo.ManagementConfiguration: remote-mgmt(MBeanServerStrategy=create)

The other optional parameters are: EnableLogMBean and EnableRuntimeMBean.

EnableLogMBean: When set to true, indicates that the LogMBean should be registered.
EnableRuntimeMBean: When set to true, indicates that the RuntimeMBean should be registered.

For example, to register both the RuntimeMBean and the LogMBean, set kood.ManagementConfiguration to:

local-mgmt(EnableLogMBean=true,EnableRuntimeMBean=true)

12.1.2. Optional Parameters in Remote Group

In order to do remote management, you need to start a remote JMX adaptor. Once the adaptor has started, you need to start the GUI. See Section 12.2, “Kodo Management Console” for more information. The Remote Group enables configuration of the remote management adaptor. For adaptors other than the mx4j-jrmp adaptor, a custom ManagementConfiguration must be defined. By default, the mx4j-jrmp adaptor sets up an RMI registry naming service on rmi://localhost:1099 and registers an MX4J JRMP JMX adaptor under the JNDI name jrmp. To change the host, port and JNDI name used, the following optional parameters are available on those kodo.ManagementConfiguration plugins that support the Remote Group.

JNDIName: The JNDI name under which to register the remote JMX adaptor. Defaults to jrmp.
Host: The hostname on which the RMI registry naming service will listen. Defaults to localhost.
Port: The port on which the RMI registry naming service will listen. Defaults to 1099.

For example, to listen on port 2345, set kodo.ManagementConfiguration to:

remote-mgmt(Port=2345)

12.1.3. Optional Parameters in JSR 160 Group

In order to do remote management using the JSR 160 standard (supported by JMX implementations supporting JMX 1.2 and higher), you need to start a remote JMX adaptor. Once the adaptor has started, you need to start the GUI. See Section 12.2, “Kodo Management Console” for more information. The JSR 160 Group enables configuration of the remote management adaptor.

For convenience, the JSR 160 adaptor sets up an RMI registry naming service on rmi://localhost:1099 and registers the JMX Connector Server with it, by default. To change the host, port and service URL used, the following optional parameters are available on those kodo.ManagementConfiguration plugins that support the JSR 160 Group.

ServiceURL: The JMX service URL name under which to register the JMX Connector Server. Defaults toservice:jmx:rmi://localhost/jndi/jmxservice, indicating that the RMI connector will be used and registered under the JNDI name jmxsevice.
NamingImpl: The classname of the naming service implementation to start in order to register the RMI connector with a JNDI name. Defaults to mx4j.tools.naming.NamingService, which is appropriate for MX4J v. 2.x. If set to the empty string, no naming service will be started. This is appropriate if a naming service is already running, or if a non-RMI connector is used.
Host: The hostname on which the RMI registry naming service will listen. Defaults to localhost. This parameter is ignored for connectors that do not register with a naming service.
Port: The port on which the RMI registry naming service will listen. Defaults to 1099. This parameter is ignored for connectors that do not register with a naming service.

For example, to have the RMI registry naming service listen on port 2345, set kodo.ManagementConfiguration to:

jmx2-remote-mgmt(Port=2345)

12.1.4. Optional Parameters in WebLogic 8.1 Group

The following parameters must be set on those kodo.ManagementConfiguration plugins that support the WebLogic 8.1 Group. Once WebLogic has started, the GUI needs to be started. See Section 12.2, “Kodo Management Console” for more information. For additional requirements in order to do remote management, please see Section 12.2.1.1, “Connecting to Kodo under WebLogic 8.1”.

UserName: The username that Kodo should use to access the WebLogic MBeanServer. This must be set.
Password: The password that Kodo should use to access the WebLogic MBeanServer. This must be set.
ServerName: The server name of the server whose MBeanServer to which Kodo should connect. This must be set.
URL: The URL to which Kodo should connect to access the WebLogic MBeanServer. Defaults to t3://localhost:7001.

For example, set kodo.ManagementConfiguration to:

wl81-mgmt(UserName=admin,Password=admin,ServerName=myserver,URL="t3://localhost:7001")

12.1.5. Configuring Logging for Management / Monitoring

Logging for the management and monitoring API is on the kodo.Manage logging channel.

Prev	Up	Next
11.3. Remote Event Notification Framework	Home	12.2. Kodo Management Console