Skip Headers
Oracle® Fusion Middleware Administrator's Guide for Oracle Event Processing
11g Release 1 (11.1.1.7)

Part Number E14300-09
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

12 Configuring JMX for Oracle Event Processing

This chapter describes how to configure Java Management Extensions (JMX) for use with Oracle Event Processing, including accessing MBeans, JMX configuration objects and programmatically connecting and configuring components with JMX APIs.

This chapter includes the following sections:

12.1 Overview of JMX Support in Oracle Event Processing

Oracle Event Processing provides standards-based interfaces that are fully compliant with the Java Management Extensions (JMX) specification. Software developers can use these interfaces to monitor Oracle Event Processing MBeans, to change the configuration of an Oracle Event Processing domain, and to monitor Oracle Event Processing applications.

For more information, see:

12.1.1 Understanding JMX Configuration

Before you can manage Oracle Event Processing applications, servers, and domains using JMX and Oracle Event Processing MBeans, you must first configure the JMX service on your Oracle Event Processing server.

You configure the Oracle Event Processing JMX service using the following elements in the config.xml file that describes your Oracle Event Processing domain:

For more information, see Section 12.2, "Configuring JMX".

12.1.2 Understanding JMX Management

Oracle Event Processing applications define an event processing network (EPN) that is made up of components such as adapters, channels, and processors. You deploy these applications to an Oracle Event Processing instance that has been started in a domain.

Note:

Components are also sometimes referred to as stages, in particular in the management Javadocs. However, for consistency with the rest of the Oracle Event Processing documentation, this section uses the term components.

You can dynamically configure each component in the EPN using managed beans, or MBeans. Typical configuration tasks include adding and removing Oracle CQL or EPL rules, changing channel max size, subscribing to notifications, and executing operations.

You manipulate the MBeans using any of the following:

This section describes:

For more information, see:

12.1.2.1 Accessing the Oracle Event Processing JMX Server

To access Oracle Event Processing MBeans, you must first connect to the Oracle Event Processing JMX server.

Oracle Event Processing does not support the JRMP protocol. Instead, JMX clients must use the more secure MSA protocol for both local and remote access to the Oracle Event Processing JMX server.

When you connect to the Oracle Event Processing JMX server that is running on localhost or on a remote host, you must copy the following Oracle Event Processing server JAR files to the client classpath of the host from which you want to connect to the Oracle Event Processing server:

  • ORACLE_CEP_HOME\modules\com.bea.core.jmx_8.0.0.0.jar

  • ORACLE_CEP_HOME\modules\com.bea.core.rmi_7.0.0.0.jar

  • ORACLE_CEP_HOME\modules\com.bea.core.jndi.context_8.0.0.0.jar

  • ORACLE_CEP_HOME\modules\com.bea.core.logging_1.8.0.0.jar

  • ORACLE_CEP_HOME\modules\com.bea.core.bootbundle_11.0.0.0.jar

Where ORACLE_CEP_HOME refers to the directory in which you installed Oracle Event Processing (such as d:\oracle_home).

You must launch your JMX client (such as jconsole) using the following command line options and classpath (split for readability; in practice, the command should be on one line):

prompt> java -Djmx.remote.protocol.provider.pkgs=com.bea.core.jmx.remote.provider 
-Dmx4j.remote.resolver.pkgs=com.bea.core.jmx.remote.resolver 
-Djava.naming.factory.initial=com.bea.core.jndi.context.ContextFactory 
-classpath %JAVA_HOME%\lib\jconsole.jar;MODULE_HOME\modules\com.bea.core.jmx_8.0.0.0.jar;
MODULE_HOME\modules\com.bea.core.rmi_7.0.0.0.jar;MODULE_HOME\modules\com.bea.core.jndi.context_7.0.0.0.jar;
MODULE_HOME\modules\com.bea.core.logging_1.5.0.0.jar;MODULE_HOME\modules\com.bea.core.bootbundle_8.0.0.0.jar 
sun.tools.jconsole.JConsole 

Where MODULE_HOME is the directory you copied the Oracle Event Processing server JAR files to.

To connect to the Oracle Event Processing JMX server, you must use the JMX URL service:jmx:msarmi://HOST-NAME:port/jndi/jmxconnector so that you are always using the MSA connector (where HOST-NAME is either localhost or the name of the remote host and port is the Oracle Event Processing server JNDI port).

For more information, see:

12.1.2.2 Accessing Configuration MBeans

You can also perform some configuration and application life cycle management of the server, domain, and deployed applications using MBeans, although this section predominantly describes configuring individual application components. However, because server, domain, and application configuration is also done using MBeans, much of the information in this section is applicable.

Each component in a deployed application (adapter, channel, or processor) has a configuration MBean that manages the underlying configuration of the component. Each type of component has its own set of manageable artifacts. For example, you can dynamically configure the maximum number of threads for a channel or the Oracle CQL rules associated with a processor.

12.1.2.3 Accessing Oracle Event Processing Runtime MBeans

You can also gather monitoring information for each component in the EPN using runtime MBeans. Monitoring information includes throughput (number of events passing through a component) and latency (how long it takes an event to pass through a component).

12.1.3 Understanding Oracle Event Processing MBeans

Oracle Event Processing exposes the following types of MBeans:

  • Configuration MBeans—Contain information about the configuration of components in an EPN, a deployed Oracle Event Processing application, the server and domain configurations. These MBeans have a fixed management interface and represent the information contained in the domain config.xml file and the component configuration XML files. Examples of standard MBeans include CQLProcessorMBean and EventChannelMBean.

  • Runtime MBeans—Contain information about throughput and latency of a component.

For full reference information about Oracle Event Processing MBeans and management in general, see the following classes in the Oracle Fusion Middleware Java API Reference for Oracle Event Processing:

  • com.bea.wlevs.management.configuration

  • com.bea.wlevs.management.runtime

  • com.bea.wlevs.monitor.management

  • com.bea.wlevs.monitor

  • com.bea.wlevs.processor.epl.management

  • com.bea.wlevs.deployment.mbean

This section describes:

12.1.3.1 Oracle Event Processing Configuration MBeans

When you deploy an Oracle Event Processing application, the server automatically creates a configuration MBean for each component in the EPN whose manageability has been enabled, or in other words, for each component registered in the EPN assembly file. If you have extended the configuration of an adapter, then the server deploys a custom configuration MBean for the adapter.

Using JMX, you can dynamically configure the component using its configuration MBean. For example, using the StreamMBean.setMaxSize() method you can set the size of a channel component.

12.1.3.1.1 Configuration MBean Naming

Oracle Event Processing configuration MBeans are arranged in a hierarchy. The object name of each MBean reflects its position in the hierarchy. A typical object naming pattern is as follows:

com.bea.wlevs:Name=name,Type=type,[TypeOfParentMBean=NameOfParentMBean]

where:

  • com.bea.wlevs: is the JMX domain name.

  • Name=name,Type=type,[TypeOfParentMBean=NameOfParentMBean] is a set of JMX key properties.

The order of the key properties is not significant, but the object name must begin with com.bea:wlevs:.

For example, the object name of the MBean corresponding to a processor called myprocessor in the application myapplication in the domain is as follows:

com.bea.wlevs:Name=myprocessor,Type=EPLProcessor,Application=myapplication

Table 12-1 describes the key properties that Oracle Event Processing encodes in its MBean object names.

Table 12-1 Oracle Event Processing MBean Object Name Key Properties

This Key Property Specifies
Name=name

The string that you provided when you created the resource that the MBean represents. This is typically the name of a component.

The name of a particular component is specified in the EPN assembly file using the id attribute of the component registration.

For example, in the case of processors, the entry in the EPN assembly file might look like the following:

<wlevs:processor id="myprocessor" advertise="true" />

In this case, the key property would be Name=myprocessor.

Type=type

The short name of the MBean's type. The short name is the unqualified type name without the MBean suffix.

For example, for an MBean that is an instance of the CQLProcessorMBean, use CQLProcessor. In this case, the key property would be Type=CQLProcessor.

TypeOfParentMBean=NameOfParentMBean

Specifies the type and name of the parent MBean.

For components, this is always Application=application_name, where application_name refers to the name of the application of which the component is a part.

The name of a particular Oracle Event Processing application is specified with the Bundle-SymbolicName header of the MANIFEST.MF file of the application bundle. For example, if an application has the following MANIFEST.MF snippet (only relevant parts are shown):

Manifest-Version: 1.0
Archiver-Version:
Build-Jdk: 1.5.0_06
....
Bundle-SymbolicName: myapplication

then the key property would be Application=myapplication.


Table 12-2 shows examples of configuration MBean objects names that correspond to the component declarations in the HelloWorld sample EPN assembly file. In each example, the application name is helloworld and the domain name is mydomain.

Table 12-2 Component Declaration Example With Corresponding MBean Object Names

EPN Assembly File Component Declaration Corresponding Configuration MBean Object Name
<wlevs:processor id="helloworldProcessor" />
com.bea.wlevs:Name=helloworldProcessor,Type=EPLProcessor,Application=helloworld,Domain=mydomain

EPLProcessor is the standard configuration MBean for processor components. The manageable property is rules.

<wlevs:channel id="helloworldInstream">
  <wlevs:listener ref="helloworldProcessor"/>
  <wlevs:source ref="helloworldAdapter"/>
</wlevs:channel>
com.bea.wlevs:Name=helloworldInstream,Type=Channel,Application=helloworld,Domain=mydomain

Channel is the standard configuration MBean for a channel component. The manageable properties are MaxSize and MaxThreads.


12.1.3.2 Oracle Event Processing Runtime MBeans

You can also gather monitoring information for each component in the EPN using runtime MBeans. Oracle Event Processing server defines the following metrics that you can monitor for each component:

  • Throughput—The number of events processed by the component. The parameters for this metric are: throughput time interval, aggregation time interval, the unit of time for the intervals.

  • Average Latency—The average amount of time it takes an event to pass through a component, or latency. Parameters: aggregation time interval, the unit of time for the interval.

  • Maximum Latency—The maximum amount of time it takes an event to pass through a component. Parameters: aggregation time interval, the unit of time for the interval.

  • Average Latency Threshold—Specifies whether the average latency of events between the start- and end-points of a component crosses a specified threshold. Parameters: aggregation time interval, threshold, the unit of time for the interval.

12.1.3.2.1 Runtime MBean Naming

Runtime MBeans are named using the same pattern as with configuration mbeans except for one extra property: Direction. This property has two valid values: OUTBOUND or INBOUND that refer to the point at which you want to gather the statistic OUTBOUND means that you want to gather throughput or latency as events flow out of the specified component; similarly INBOUND means you want to gather the monitoring information as events flow into a component.

For example, the object name of the runtime MBean corresponding to a processor called myprocessor in the application myapplication, in which events will be monitored as they flow into the component, is as follows:

com.bea.wlevs:Name=myprocessor,Type=EPLProcessor,Application=myapplication,Direction=INBOUND

See Section 12.1.3.1.1, "Configuration MBean Naming" for details about configuration MBean naming.

12.1.3.3 Oracle Event Processing MBean Hierarchy

Figure 12-1 describes the Oracle Event Processing MBean tree.

Figure 12-1 Oracle Event Processing MBean Tree

Description of Figure 12-1 follows
Description of "Figure 12-1 Oracle Event Processing MBean Tree"

All MBeans must be registered in an MBean server under an object name of type javax.management.ObjectName. Oracle Event Processing follows a convention in which object names for child MBeans contain part of its parent MBean object name.

There are two main MBean roots: DomainMBean and DomainRuntimeMBean. The former includes configuration MBeans for the entire domain, the latter contains runtime information, such as statistics, and local services, such as Monitor, that are generally scoped to a single server instance.

ApplicationMBean is a child of the DomainMBean instead of the ServerMBean. This is because an application is unique within a domain, and can span multiple servers.

Figure 12-2 shows the main classes and relationships that make up the object model.

Figure 12-2 Oracle Event Processing MBean Object Model

Description of Figure 12-2 follows
Description of "Figure 12-2 Oracle Event Processing MBean Object Model"

Most MBeans are notification emitters that generate AttributeChangeNotifications. In other words, a JMX client can register to receive attribute change notifications regarding changes to application state, insertion and removal of applications at the domain, channel size and thread changes, insertion and removal of rules, and so on.

12.2 Configuring JMX

You configure the Oracle Event Processing JMX service using the following elements in the config.xml file that describes your Oracle Event Processing domain:

For information on security configuration tasks that affect JMX, see Section 10.8.2, "Configuring JMX Security".

For more information, see:

12.2.1 jmx Configuration Object

Table 12-3 lists the jmx element child elements in the config.xml file that you must configure.

Table 12-3 Configuration Parameters for the jmx Element

Parameter Type Description
rmi-service-name 
String

The name of the RMI service with which the jmx server will register to receive calls.

jndi-service-name
String

The name of the JNDI service to which the jmx server will bind its object.


12.2.2 rmi Configuration Object

The Oracle Event Processing RMI service provides:

  • Ability to register a POJO interface in a server for remote method invocation from a client.

  • Ability to register for any context propagation from the client to the server on a remote method invocation, intercept, and act on this propagated context in the server.

Table 12-4 lists the rmi element child elements in the config.xml file that you use to export server-side objects to remote clients.

Table 12-4 Configuration Parameters for the rmi Element

Parameter Type Description
heartbeat-period
int

The number of failed heartbeat attempts before triggering disconnect notifications to all registered listeners.

http-service-name
String

The name of the HTTP service used to register remote objects (such as Jetty, see Section 11.1, "Overview of Jetty Support in Oracle Event Processing").

heartbeat-interval
int

The amount of time, in milliseconds, between heartbeats.

Once the number of unsuccessful heartbeat attempts has reached the value specified by the HeartbeatPeriod parameter, all registered DisconnectListener instances are notified.

name
String

The name of this configuration object.


12.2.3 jndi-context Configuration Object

The JNDI Factory Manager is responsible for supporting JNDI in an OSGi environment. It allows JNDI providers to be supplied as OSGi bundles, and for code running inside OSGi bundles to have full access to the JNDI environment.

The Factory Manager consists of two components:

  • An OSGi bundle, which provides the OSGi-specific factory management code, to look up JNDI objects using the appropriate OSGi classloader.

  • JNDI "glue code," internal to Oracle Event Processing, that initializes the JNDI environment to support the factory manager bundle.

Table 12-5 lists the jndi-context element child elements in the config.xml file that you must configure.

Table 12-5 Configuration Parameters for the jndi-context Element

Parameter Type Description
default-provider
boolean

If true, the default Oracle Event Processing JNDI provider is used.

Default value is true.

name
String

The name of this configuration object.


12.2.4 exported-jndi-context Configuration Object

Requires a configured Section 12.2.3, "jndi-context Configuration Object."

Use this configuration object to export a remote JNDI service to a client using RMI. A JNDI context is registered with the RMI service to provide remote access to clients that pass a provider URL parameter in their InitialContext object.

Table 12-6 lists the exported-jndi-context element child elements in the config.xml file that you must configure.

Table 12-6 Configuration Parameters for the exported-jndi-context Element

Parameter Type Description
rmi-service-name
String

The name of the RMI service that should be used to serve this JNDI context over the network. It must match an existing <rmi> configuration object. See Section 12.2.2, "rmi Configuration Object."

name
String

The name of this configuration object.

The value of this element must be different from the value of the <name> child element of <jndi-context> in the same config.xml file.


12.2.5 Example of Configuring JMX

Example 12-1 shows a config.xml snippet with JMX configuration; only relevant parts of the file are shown.

Example 12-1 JMX Configuration

<config>
  <netio>
    <name>JettyNetio</name>
    <port>12345</port>
  </netio>
  <work-manager>
    <name>WM</name>
    <fairshare>5</fairshare>
    <min-threads-constraint>1</min-threads-constraint>
    <max-threads-constraint>4</max-threads-constraint>
  </work-manager>
  <jetty>
    <name>TestJetty</name>
    <work-manager-name>WM</work-manager-name>
    <network-io-name>JettyNetio</network-io-name>
  </jetty>
  <rmi>
    <name>RMI</name>
    <http-service-name>TestJetty</http-service-name>
  </rmi>
  <jndi-context>
    <name>JNDI</name>
  </jndi-context>
  <exported-jndi-context>
    <name>exportedJNDI</name>
    <rmi-service-name>RMI</rmi-service-name>
  </exported-jndi-context>
  <jmx>
    <jndi-service-name>JNDI</jndi-service-name>
    <rmi-service-name>RMI</rmi-service-name>
  </jmx>
</config>

12.3 Managing With JMX

This section describes detailed examples of managing Oracle Event Processing components using JMX, including:

Note:

When using JConsole, you must start it with the Oracle Event Processing wlevsjconsole.cmd or wlevsjconsole.sh script. You cannot start jconsole directly.

For more information, see:

12.3.1 How to Programmatically Connect to the Oracle Event Processing JMX Server From a Non-Oracle Event Processing Client

This section describes how to write Java code using the JMX API (http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement) to connect to the Oracle Event Processing JMX server from a non-Oracle Event Processing client. This is the first step to all programmatic JMX management.

For information on connecting to the Oracle Event Processing JMX server from another Oracle Event Processing server, see Section 12.3.2, "How to Programmatically Connect to the Oracle Event Processing JMX Server From an Oracle Event Processing Client".

To programmatically connect to the Oracle Event Processing JMX server from a non-Oracle Event Processing client:

  1. Be sure that the JMX service is configured for your domain.

    For details see Section 12.2, "Configuring JMX".

  2. Write the http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement Java code to configure the component using the appropriate MBean.

    Consider the following JMX programming hints.

    One of the first things you must do in your JMX program is to establish a connection to the JMX server running in the Oracle Event Processing server as Example 12-2 shows.

    Example 12-2 Establishing a Connection to the Oracle Event Processing JMX Server

    public static void initConnection(String hostname, int port, String username, char[] password) 
      throws IOException,MalformedURLException {
    
      Map<String,Object> env = makeSecureEnv();
      env.put("jmx.remote.protocol.provider.pkgs","com.bea.core.jmx.remote.provider");
      env.put("mx4j.remote.resolver.pkgs","com.bea.core.jmx.remote.resolver");
      env.put("java.naming.factory.initial","com.bea.core.jndi.context.ContextFactory");
    
      JMXServiceURL serviceUrl = new JMXServiceURL(
          "MSARMI","localhost",9002,"/jndi/jmxconnector"
      );
    
      System.out.println("Service: " + serviceURL.toString());
    
      JMXConnector connector = JMXConnectorFactory.connect(serviceUrl,env);
    
      MBeanServerConnection connection = connector.getMBeanServerConnection();
    }
    
    // The JMXConnectorFactory.connect() method's second parameter is a Map object that sets up a
    // secure environment using the makeSecureEnv() method, which looks like the following:
    
    private static Map<String,Object> makeSecureEnv() {
        Map<String,Object> env = new HashMap<String,Object>();
        String username = "wlevs" ;
        char[] password = { 'w','l','e','v','s' };
        env.put(JMXConnector.CREDENTIALS, new Serializable[]{username,password});
        env.put("jmx.remote.authenticator", "com.bea.core.jmx.server.CEAuthenticator");
        System.setProperty("jmx.remote.authenticator", "com.bea.core.jmx.server.CEAuthenticator");
        return env;
    }
    

12.3.2 How to Programmatically Connect to the Oracle Event Processing JMX Server From an Oracle Event Processing Client

This section describes how to write Java code using the JMX API (http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement) to connect to the Oracle Event Processing JMX server from another Oracle Event Processing server. This is the first step to all programmatic JMX management.

For information on connecting to the Oracle Event Processing JMX server from a non-Oracle Event Processing client, see Section 12.3.1, "How to Programmatically Connect to the Oracle Event Processing JMX Server From a Non-Oracle Event Processing Client".

To programmatically connect to the Oracle Event Processing JMX server from an Oracle Event Processing client:

  1. Be sure that the JMX service is configured for your domain.

    For details see Section 12.2, "Configuring JMX".

  2. Write the http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement Java code to configure the component using the appropriate MBean.

    Consider the following JMX programming hints.

    One of the first things you must do in your JMX program is to establish a connection to the JMX server running in the Oracle Event Processing server as Example 12-2 shows.

    Example 12-3 Establishing a Connection to the Oracle Event Processing JMX Server

    public static void initConnection(String hostname, int port, String username, char[] password) 
      throws IOException,MalformedURLException {
    
      Map<String,Object> env = makeSecureEnv();
    
      // This is an OSGi necessity
      env.put(
          JMXConnectorFactory.DEFAULT_CLASS_LOADER,
          com.bea.core.jmx.remote.provider.msarmi.ServerProvider.class.getClassLoader()
      );
      env.put(
          JMXConnectorFactory.PROTOCOL_PROVIDER_CLASS_LOADER,
          com.bea.core.jmx.remote.provider.msarmi.ServerProvider.class.getClassLoader()
      );
    
      JMXServiceURL serviceUrl = new JMXServiceURL(
          "MSARMI","localhost",9002,"/jndi/jmxconnector"
      );
    
      System.out.println("Service: " + serviceURL.toString());
    
      env.put(
          JMXConnectorFactory.PROTOCOL_PROVIDER_PACKAGES, 
          "com.bea.core.jmx.remote.provider"
      );
    
      System.setProperty("mx4j.remote.resolver.pkgs", "com.bea.core.jmx.remote.resolver");
     
      JMXConnector connector = JMXConnectorFactory.connect(url, env);
      connector.connect();
     
      MBeanServerConnection connection = connector.getMBeanServerConnection();
      ...
    }
    
    // The JMXConnectorFactory.connect() method's second parameter is a Map object that sets up a
    // secure environment using the makeSecureEnv() method, which looks like the following:
    
    private static Map<String,Object> makeSecureEnv() {
        Map<String,Object> env = new HashMap<String,Object>();
        String username = "wlevs" ;
        char[] password = { 'w','l','e','v','s' };
        env.put(JMXConnector.CREDENTIALS, new Serializable[]{username,password});
        env.put("jmx.remote.authenticator", "com.bea.core.jmx.server.CEAuthenticator");
        System.setProperty("jmx.remote.authenticator", "com.bea.core.jmx.server.CEAuthenticator");
        return env;
    }
    

12.3.3 How to Programmatically Configure an Oracle Event Processing Component Using JMX APIs

This section describes how to write Java code using the JMX API (http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement) to access Oracle Event Processing MBeans.

To programmatically configure an Oracle Event Processing component using JMX APIs:

  1. Acquire a connection to the Oracle Event Processing JMX server.

    For details see Section 12.3.1, "How to Programmatically Connect to the Oracle Event Processing JMX Server From a Non-Oracle Event Processing Client".

  2. Write the http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement Java code to configure the component using the appropriate MBean.

    Consider the following JMX programming hints.

    Example 12-4 shows how to use the connection to start getting information about the domain and its deployed applications by querying MBeans.

    First the code shows how to get all MBeans whose type is Domain; there should only be one. Then, using the DomainMBean, the sample shows how to retrieve a list of all the deployed applications in the domain (using ApplicationMBean):

    Example 12-4 Querying MBeans

    Set domainObjectNames = connection.queryMBeans(
        ObjectName.getInstance(
            ManagementConstants.DOMAIN_NAME + ":" + 
            ManagementConstants.TYPE_PROPERTY + "=" + 
            DomainMBean.MBEAN_TYPE + ",*"
        ), 
        null
    );
    ObjectName domainName =  ((ObjectInstance) domainObjectNames.iterator().next()).getObjectName();
    System.out.println("Domain Name: " + domainName.getKeyProperty(ManagementConstants.NAME_PROPERTY));
    ObjectName [] applicationNames =
         (ObjectName[]) connection.getAttribute(domainName, "ApplicationMBeans");
    ObjectName selectedApplicationObjectName = null ;
    for (ObjectName applicationName : applicationNames) {
       String name = 
         applicationName.getKeyProperty(ManagementConstants.NAME_PROPERTY);
       String status =
         (String) connection.getAttribute(applicationName, "State");
        System.out.println("Application: " + name + " Status: " + status);
        selectedApplicationObjectName = applicationName ;
    }
    

12.3.4 How to Programmatically Monitor the Throughput and Latency of an Oracle Event Processing Component Using JMX APIs

This section describes how to write Java code using the JMX API (http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement) to access Oracle Event Processing MBeans and dynamically monitor the throughput and latency of an Oracle Event Processing component.

To dynamically configure an Oracle Event Processing component using JMX APIs:

  1. Acquire a connection to the Oracle Event Processing JMX server.

    For details see Section 12.3.1, "How to Programmatically Connect to the Oracle Event Processing JMX Server From a Non-Oracle Event Processing Client".

  2. Acquire an instance of a MonitorRuntimeMBean for the component you want to monitor as Example 12-5 shows.

    Example 12-5 Acquiring an Instance of a MonitorRuntimeMBean

    ObjectName processorInbound = ObjectName.getInstance(
        "com.bea.wlevs:Name=myprocessor," +
        "Type=CQLProcessor," +
        "Application=myapplication," +
        "Direction=INBOUND"
    );
    

    Be sure you specify whether you want to monitor incoming events (INBOUND) or outgoing events (OUTBOUND). For example:

  3. Use the MonitorRuntimeMBean to acquire an instance of ProbeRuntimeMBean for the type of statistic you want as Example 12-6 shows.

    Example 12-6 Acquiring an Instance of ProbeRuntimeMBean

    ObjectName monitorName =
        ObjectName.getInstance(
            "com.bea.wlevs:ServerRuntime=localhost," +
            "Name=MonitorRuntime," +
            "Type=MonitorRuntime");
    
    MonitorRuntimeMBean monitorMBean =     (MonitorRuntimeMBean)MBeanServerInvocationHandler.newProxyInstance( 
            connection,
            monitorName,
            MonitorRuntimeMBean.class,
            false);
    
    ObjectName probeName = monitorMBean.monitorAvgThroughput(
        processorInbound,
        1000,
        1000
    );
    
    ProbeRuntimeMBean probeOn = (ProveRuntimeMBean)MBeanServerInvocationHandler.newProxyInstance(
        connection,
        probeName,
        ProbeRuntimeMBean.class,
        false
    );
    

    The MonitorRuntimeMBean has methods for each type of statistic you can gather. For example, you execute monitorAvgLatency() if you want to monitor the average latency, monitorAvgThroughput() to monitor the average throughput, and so on. These methods all return ProbeRuntimeMBean.

  4. Use the ProbeRuntimeMbean instance to get the actual runtime metrics in one of the following ways:

    1. Use the ProbeRuntimeMBean method getMetric() to pull the information.

    2. Use javax.management.NotificationBroadcaster.addNotificationListener() to have the information pushed to you every time there is a change in the metrics.

  5. When you are finished gathering monitoring information, unregister the MBean from the MBean server as Example 12-7 shows.

    Example 12-7 Unregistering the MBean

    probON.terminate();
    

    For additional details about these MBean interfaces and how to use them to monitor throughput and latency, see the com.bea.wlevs.monitor.management package in the Oracle Fusion Middleware Java API Reference for Oracle Event Processing.

12.3.5 How to Connect to a Local or Remote Oracle Event Processing JMX Server Using JConsole With Security Enabled

You can use the wlevsjconsole script to connect to an Oracle Event Processing JMX server running on your local host or on a remote host to browse and manage Oracle Event Processing MBeans with the JDK jconsole.

This procedure describes how to use JConsole when the Oracle Event Processing server has security enabled. This is the default configuration and is recommended for production servers. Alternatively, you can connect to the JMX server with security disabled (see Section 12.3.6, "How to Connect to a Local or Remote Oracle Event Processing JMX Server Using JConsole With Security Disabled").

For more information, see Section 12.1.2.1, "Accessing the Oracle Event Processing JMX Server".

Note:

When using JConsole, you must start it with the Oracle Event Processing wlevsjconsole.cmd or wlevsjconsole.sh script. You cannot start jconsole directly.

To connect to a local or remote Oracle Event Processing JMX server using JConsole with security enabled:

  1. Ensure that the local or remote Oracle Event Processing server is running.

  2. Open a command window and set your environment as described in "Setting Your Development Environment" in the Oracle Fusion Middleware Developer's Guide for Oracle Event Processing for Eclipse.

  3. Launch jconsole using the wlevsjconsole.cmd or wlevsjconsole.sh script located in the ORACLE_CEP_HOME/ocep_11.1/bin directory, where ORACLE_CEP_HOME refers to the directory in which you installed Oracle Event Processing (such as /oracle_home).

    1. To connect to a local Oracle Event Processing server, enter:

      prompt> wlevsjconsole.cmd
      
    2. To connect to a remote Oracle Event Processing server, enter:

      prompt> wlevsjconsole.cmd HOST-NAME:PORT
      

      Where HOST-NAME is the name of the remote host and PORT is the NetIO port as configured in the remote host's ORACLE_CEP_HOME/user_projects/domains/DOMAIN-NAME/defaultserver/config/config.xml file.

    The jconsole browser attempts to log into the JMX server and initially fails as Figure 12-3 shows.

    Figure 12-3 Jconsole Initial Login Attempt

    Description of Figure 12-3 follows
    Description of "Figure 12-3 Jconsole Initial Login Attempt"

  4. Click Cancel.

    The Jconsole New Connection dialog appears as shown in Figure 12-4.

    Figure 12-4 JConsole New Connection Dialog

    Description of Figure 12-4 follows
    Description of "Figure 12-4 JConsole New Connection Dialog"

  5. Configure the New Connection dialog as Table 12-7 describes.

    Table 12-7 JConsole New Connection Attributes

    Attribute Description

    Remote Process

    Enter the following URL:

    service:jmx:msarmi://HOST-NAME:PORT/jndi/jmxconnector
    

    Where HOST-NAME is the name of the local or remote host and PORT is the NetIO port as configured in the remote host's ORACLE_CEP_HOME/user_projects/domains/DOMAIN-NAME/defaultserver/config/config.xml file (default: 9002).

    Username

    Enter an Oracle Event Processing administration password.

    Default: wlevs.

    Password

    Enter the password for the Oracle Event Processing administration password you chose.

    Default: wlevs.


  6. Click Connect.

    The jconsole browser opens and provides access to Oracle Event Processing MBeans as Figure 12-6 shows.

    Figure 12-5 JConsole Browser

    Description of Figure 12-5 follows
    Description of "Figure 12-5 JConsole Browser"

12.3.6 How to Connect to a Local or Remote Oracle Event Processing JMX Server Using JConsole With Security Disabled

You can use the wlevsjconsole script to connect to an Oracle Event Processing JMX server running on your local host or on a remote host to browse and manage Oracle Event Processing MBeans with the JDK jconsole.

This procedure describes how to use JConsole when the Oracle Event Processing server has security disabled. This is a common development configuration and is not recommended for production servers. Alternatively, you can connect to the JMX server with security enabled (see Section 12.3.5, "How to Connect to a Local or Remote Oracle Event Processing JMX Server Using JConsole With Security Enabled").

For more information, see Section 12.1.2.1, "Accessing the Oracle Event Processing JMX Server".

Note:

When using JConsole, you must start it with the Oracle Event Processing wlevsjconsole.cmd or wlevsjconsole.sh script. You cannot start jconsole directly.

To connect to a local or remote Oracle Event Processing JMX server using JConsole with security disabled:

  1. Ensure that the local or remote Oracle Event Processing server is running with security disabled.

    For more information, see Section 10.11, "Disabling Security".

  2. Open a command window and set your environment as described in "Setting Your Development Environment" in the Oracle Fusion Middleware Developer's Guide for Oracle Event Processing for Eclipse.

  3. Launch jconsole using the wlevsjconsole.cmd or wlevsjconsole.sh script located in the ORACLE_CEP_HOME/ocep_11.1/bin directory, where ORACLE_CEP_HOME refers to the directory in which you installed Oracle Event Processing (such as /oracle_home).

    1. To connect to a local Oracle Event Processing server, enter:

      prompt> wlevsjconsole.cmd
      
    2. To connect to a remote Oracle Event Processing server, enter:

      prompt> wlevsjconsole.cmd HOST-NAME:PORT
      

      Where HOST-NAME is the name of the remote host and PORT is the NetIO port as configured in the remote host's ORACLE_CEP_HOME/user_projects/domains/DOMAIN-NAME/defaultserver/config/config.xml file.

    The script automatically connects to the JMX server and the jconsole browser opens and provides access to Oracle Event Processing MBeans as Figure 12-6 shows.

    Figure 12-6 JConsole Browser

    Description of Figure 12-6 follows
    Description of "Figure 12-6 JConsole Browser"