Chapter 12. Management and Monitoring
Prev | Part V. Kodo JDO Reference Guide | Next

## Chapter 12. Management and Monitoring

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

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.13, “JMX Management”.

## 12.1. Configuration

The Management capability is configured via the standard Kodo configuration system using the `kodo.ManagementConfiguration` property (see Section 2.6.28, “kodo.ManagementConfiguration”). This property is also a plugin string (see Section 2.4, “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 14.7.1, “Profiling in an embedded GUI” for more configuration information).

- `profiling-export`: Export profiling data (see Section 14.7.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 14.7.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 14.7.3, “Controlling how the profiler obtains context information” and Section 14.7.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 specication 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 specication 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 14.7.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 specication 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 14.7.3, “Controlling how the profiler obtains context information” and Section 14.7.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 14.7.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 14.7.3, “Controlling how the profiler obtains context information” and Section 14.7.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 14.7.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 14.7.3, “Controlling how the profiler obtains context information” and Section 14.7.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 14.7.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 14.7.3, “Controlling how the profiler obtains context information” and Section 14.7.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 properties:

- `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:

- `kodo.ManagementConfiguration: local-mgmt (EnableLogMBean=true,EnableRuntimeMBean=true)`

### 12.1.2. Optional Parameters in Remote Group

In order to do remote management, a remote JMX adaptor needs to be started. Once the adaptor has started, the GUI needs to be started. 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:

    kodo.ManagementConfiguration: 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), a remote JMX adaptor needs to be started. Once the adaptor has started, the GUI needs to be started. 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 to`service: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:

    kodo.ManagementConfiguration: 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:

    kodo.ManagementConfiguration: 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 com.solarmetric.Manage logging channel.

Prev | Up | Next
11.2. Remote Persistence Managers | Home | 12.2. Kodo Management Console