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”.
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”.
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)
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)
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)
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")