13 Configuring Event Record and Playback

This chapter describes how to configure event recording and playback for debugging Oracle Complex Event Processing (Oracle CEP) event processing networks, including how to specify an event persistence store and query the store.

13.1 Overview of Configuring Event Record and Playback

Oracle CEP event repository feature allows you to persist the events that flow out of a component of the event processing network (EPN) to a store, such as a database table, and then play them back at a later stage or explicitly query the events from a component such as an event bean.

A typical use case of this feature is the ability to debug a problem with a currently running application. If you have been recording the events at a node in the EPN when the problem occurred, you can later playback the same list of events to recreate the problem scenario for debugging purposes.

The following graphic shows the EPN of the Event Record and Playback example and demonstrates at what point events are recorded and where they are played back. The simpleEventSource adapter has been configured to record events; as indicated, the record happens as events flow out of the adapter. The eventStream channel has been configured to playback events; as indicated, the playback happens at the point where events flow into the channel.

Figure 13-1 Configuring Record and Playback in an EPN

Description of Figure 13-1 follows
Description of "Figure 13-1 Configuring Record and Playback in an EPN"

This section describes:

13.1.1 Storing Events in the Persistent Event Store

When you record events, Oracle CEP server stores them in a persistent event store. You can use the persistent event store that Oracle CEP server provides or define your own:

13.1.1.1 Default Persistent Event Store

By default, Oracle CEP uses a Berkeley DB instance bundled with the Oracle CEP server to store recorded events.

Berkeley DB is a fast, scalable, transactional database engine with industrial grade reliability and availability. For more information, see:

By default, Oracle CEP server creates the Berkeley DB instance in:

ORACLE_CEP_HOME/user_projects/domains/domainname/servername/bdb

Where ORACLE_CEP_HOME refers to the directory in which you installed Oracle CEP (such as /oracle_home), domainname refers to the name of your domain, and servername refers to the name of your server (For example, /oracle_cep/user_projects/domains/mydomain/myserver).

You can change this default by configuring the bdb-config element db-env-path child element as Section 13.2.1, "Configuring an Event Store for Oracle CEP Server" describes.

13.1.1.2 Custom Persistent Event Store

Optionally, you can create a custom persistent event store provider to store recorded events. For example, you could specify a Relational Database Management System such as Oracle Database or Derby as your persistent event store.

For more information, see Section 13.3, "Creating a Custom Event Store Provider."

13.1.1.3 Persistent Event Store Schema

You do not create the actual database schema used to store the recorded events. Oracle CEP server automatically does this for you after you deploy an application that uses the record and playback feature and recording begins.

For more information, see Section 13.2.5, "Description of the Berkeley Database Schema".

13.1.2 Recording Events

You can configure recording for any component in the event processing network (EPN) that produces events: processors, adapters, streams, and event beans. Processors and streams always produce events; adapters and event beans must implement the EventSource interface. Additionally, you can configure that events from different components in the EPN be stored in different persistent stores, or that all events go to the same store. Note that only events that are outputted by the component are recorded.

You enable the recording of events for a component by updating its configuration file and adding the record-parameters element. Using the child elements of record-parameters, you specify the event store to which the events are recorded, an initial time period when recording should take place, the list of event types you want to store, and so on.

After you deploy the application and events start flowing through the network, recording begins either automatically because you configured it to start at a certain time or because you dynamically start it using administration tools. For each component you have configured for recording, Oracle CEP stores the events that flow out of it to the appropriate store along with a timestamp of the time it was recorded.

13.1.3 Playing Back Events

You can configure playback for any component in the event processing network (EPN): processors, adapters, streams, and event beans. Typically the playback component is a node later in the network than the node that recorded the events.

You enable the playback of events for a component by updating its configuration file and adding the playback-parameters element. Using the child elements of playback-parameters, you specify the event store from which the events are played back, the list event types you want to play back (by default all are played back), the time range of the recorded events you want to play back, and so on. By default, Oracle CEP plays back the events in a time accurate manner; however, you can also configure that the events get played back either faster or slower than they originally flowed out of the component from which they were recorded.

After you deploy the application and events start flowing through the network, you must start the playback by using the administration tools (Oracle CEP Visualizer or wlevs.Admin). Oracle CEP reads the events from the appropriate persistent store and inserts them into the appropriate place in the EPN.

It is important to note that when a component gets a playback event, it looks exactly like the original event. Additionally, a component later in the network has been configured to record events, then Oracle CEP records the playback events as well as the "real" events.

For more information, see:

13.1.4 Querying Stored Events

You can use the event store API to query a store for past events given a record time range and the component from which the events were recorded. The actual query you use depends on the event repository provider; for example, you would use Oracle CQL or EPL for the default persistent event store provider included with Oracle CEP. You can also use these APIs to delete old events from the event store.

13.1.5 Record and Playback Example

The sample code in this section is taken from the event record and playback example, located in the ORACLE_CEP_HOME\ocep_11.1\samples\source\applications\recplay directory, where ORACLE_CEP_HOME refers to the main Oracle CEP installation directory, such as d:\oracle_cep.

For details about running and building the example, see "Event Record and Playback Example" in the Oracle Fusion Middleware Getting Started Guide for Oracle Complex Event Processing.

13.2 Configuring Event Record and Playback in Your Application

Depending on how you are going to use the event repository, there are different tasks that you must perform, as described in the following procedure that in turn point to sections with additional details.

Note:

It is assumed in this section that you have already created an Oracle CEP application along with its component configuration file(s) and that you want to update the application so that components record or playback events. If you have not, refer to Chapter 1, "Overview of Creating Oracle CEP Applications," for details.

To configure record and playback of events in your application:

  1. Optionally configure the Berkeley database event store for your Oracle CEP server instance.

    You may use the default Berkeley database configuration as is. You only need to make configuration changes to customize the location of the Berkeley database instance or to tune performance.

    See Section 13.2.1, "Configuring an Event Store for Oracle CEP Server."

  2. Configure a component in your EPN to record events by updating the component's configuration file.

    The component can be a processor, adapter, channel, or event bean. Only events flowing out of the component are recorded.

    See Section 13.2.2, "Configuring a Component to Record Events."

  3. Configure a component in your EPN to playback events by updating the component's configuration file.

    The component can be a processor, adapter, channel, or event bean. Only components that are also event sinks can playback events; events are played to the input side of the component.

    See Section 13.2.3, "Configuring a Component to Playback Events."

  4. Redeploy your application for the changes to take effect.

  5. If you have not specified an explicit start and end time for recording events, you must use Oracle CEP Visualizer or wlevs.Admin to start recording. You must always use these administration tools to start and end the playback of events.

    See Section 13.2.4, "Starting and Stopping the Record and Playback of Events."

13.2.1 Configuring an Event Store for Oracle CEP Server

You may use the default Berkeley database configuration as is. You only need to make configuration changes to customize the location of the Berkeley database instance or to tune performance.

For more information, see Section 13.3, "Creating a Custom Event Store Provider".

To configure an event store for Oracle CEP server:

  1. Stop your Oracle CEP server instance, if it is running.

  2. Using your favorite XML editor, open the server's config.xml file for edit.

    The config.xml file is located in the DOMAIN_DIR/servername/config directory of your server, where DOMAIN_DIR refers to the domain directory, such as /oracle_cep/user_projects/domains/myDomain and servername refers to the name of your server, such as defaultserver.

  3. Edit the bdb-config element to the config.xml file.

    Example 13-1 shows a fully configured bdb-config element.

    Example 13-1 bdb-config Element

    <bdb-config>
    <db-env-path>bdb</db-env-path>
    <cache-size>1000</cache-size>
</bdb-config>

    Table 13-1 lists the child elements of bdb-config that you can specify.

    Table 13-1 Child Elements of bdb-config

    Child Element Description

    db-env-path

    Specifies the subdirectory in which Oracle CEP server creates Berkeley database instances relative to the DOMAIN_DIR/servername/config directory of your server, where DOMAIN_DIR refers to the domain directory, such as /oracle_cep/user_projects/domains/myDomain and servername refers to the name of your server, such as defaultserver.

    Default: bdb

    cache-size

    Specifies the amount of memory, in bytes, available for Berkeley database cache entries. You can adjust the cache size to tune Berkeley database performance.

    For more information, see:

    Default: je.maxMemoryPercent * JVM maximum memory

  4. Restart your Oracle CEP server instance.

13.2.2 Configuring a Component to Record Events

You can configure any processor, adapter, channel, or event bean in your application to record events. As with all other component configuration, you specify that a component records events by updating its configuration file. For general information about these configuration files, see Section 1.1.5, "Component Configuration Files."

This section describes the main steps to configure a component to record events. For simplicity, it is assumed in the procedure that you are configuring an adapter to record events and that you have already created its component configuration file.

See Section B.2, "Component Configuration Schema wlevs_application_config.xsd" for the complete XSD Schema that describes the event recording configuration file elements.

Using your favorite XML editor, open the component configuration XML file and add a record-parameters child element to the component you want to configure to record events. For example, to configure an adapter called simpleEventSource:

<?xml version="1.0" encoding="UTF-8"?>
  <n1:config xmlns:n1="http://www.bea.com/ns/wlevs/config/application"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <adapter>
        <name>simpleEventSource</name>
        <record-parameters>
          ...
       </record-parameters>
        ...
    </adapter>
    ...
</n1:config>

Add child elements to record-parameters to specify the name of the event store provider, the events that are stored, the start and stop time for recording, and so on. For example:

<adapter>
      <name>simpleEventSource</name>
      <record-parameters>
        <dataset-name>recplay_sample</dataset-name>
        <event-type-list>
            <event-type>SimpleEvent</event-type>
        </event-type-list>
        <batch-size>1</batch-size>
        <batch-time-out>10</batch-time-out>
      </record-parameters>
</adapter>

Table 13-2 lists the child elements of record-parameters that you can specify. Only dataset-name is required.

Table 13-2 Child Elements of record-parameters

Child Element Description

dataset-name

Specifies the group of data that the user wants to group together.

In the case of BDB provider, the dataset name will be used as the database environment in Berkeley database.

In the case of the Oracle RDBMS-based provider, it specifies the database area, or schema, in which the tables that store the recorded events are created.

When configuring the Oracle RDBMS-based provider, you are required to specify this element.

event-type-list

Specifies the event types that are recorded to the event store. If this element is not specified, then Oracle CEP records all event types that flow out of the component.

Use the event-type child component to list one or more events, such as:

  <event-type-list>
      <event-type>EventOne</event-type>
      <event-type>EventTwo</event-type>
  </event-type-list>

When configuring the Oracle RDBMS-based provider, you are required to specify this element.

time-range

Specifies the time period during which recording should take place using a start and end time.

The time period is configured by using a start child element to specify a start time and an end child element to specify the end time.

Express the start and end time as XML Schema dateTime values of the form:

yyyy-mm-ddThh:mm:ss

For example, to specify that recording should start on January 20, 2010, at 5:00am and end on January 20, 2010, at 6:00 pm, enter the following:

  <time-range>
    <start>2010-01-20T05:00:00</start>
    <end>2010-01-20T18:00:00</end>
  </time-range>

For complete details of the XML Schema dateTime format, see http://www.w3.org/TR/xmlschema-2/#dateTime-lexical-representation.

If you do not specify a time period, then no events are recorded when the application is deployed and recording will only happen after you explicitly start it using Oracle CEP Visualizer or wlevs.Admin.

You can specify time-range or time-range-offset, but not both.

time-range-offset

Specifies the time period during which recording should take place, using a start time and a duration.

The time period is configured by using a start child element to specify a start time and duration child element to specify the amount of time after the start time that recording should stop.

Express the start time as an XML Schema dateTime value of the form:

yyyy-mm-ddThh:mm:ss

Express the duration in the form:

hh:mm:ss

For example, to specify that recording should start on January 20, 2010, at 5:00am and continue for 3 hours, enter the following

  <time-range-offset>
    <start>2010-01-20T05:00:00</start>
    <duration>03:00:00</duration>
  </time-range-offset>

For complete details of the XML Schema dateTime format, see http://www.w3.org/TR/xmlschema-2/#dateTime-lexical-representation.

If you do not specify a time period, then no events are recorded when the application is deployed and recording will only happen after you explicitly start it using Oracle CEP Visualizer or wlevs.Admin.

You can specify time-range or time-range-offset, but not both.

batch-size

Specifies the number of events that Oracle CEP picks up in a single batch from the event buffer to write the event store.

Default value is 1000.

batch-time-out

Specifies the number of seconds that Oracle CEP waits for the event buffer window to fill up with the batch-size number of events before writing to the event store.

Default value is 60

max-size

If specified, Oracle CEP uses a stream when writing to the event store, and this element specifies the size of the stream, with non-zero values indicating asynchronous writes.

Default value is 1024.

max-threads

If specified, Oracle CEP uses a stream when writing to the event store, and this element specifies the maximum number of threads that will be used to process events for this stream. Setting this value has no effect when max-size is 0.

The default value is 1.

13.2.3 Configuring a Component to Playback Events

You can configure any processor, adapter, channel, or event bean in your application to playback events, although the component must be a node downstream of the recording component so that the playback component will actually receive the events and play them back. As with all other component configuration, you specify that a component plays back events by updating its configuration file. For general information about these configuration files, see Section 1.1.5, "Component Configuration Files."

This section describes the main steps to configure a component to play back events. For simplicity, it is assumed in the procedure that you are configuring a channel to playback events from a node upstream in the EPN that has recorded events, and that you have already created the channel's configuration file.

See for the complete XSD Schema that describes the event playback configuration file elements.

Using your favorite XML editor, open the component configuration XML file and add a playback-parameters child element to the component you want to configure to playback events. For example, to configure a channel called eventStream:

<?xml version="1.0" encoding="UTF-8"?>
  <n1:config xmlns:n1="http://www.bea.com/ns/wlevs/config/application"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <channel>
      <name>eventStream</name>
      <playback-parameters>
        ...
      </playback-parameters>
    </channel>
    ...
</n1:config>

Add child elements to playback-parameters to specify the name of the event store provider, the events that are played back, and so on. For example:

    <channel>
      <name>eventStream</name>
      <playback-parameters>
          <dataset-name>recplay_sample</dataset-name>
          <event-type-list>
              <event-type>SimpleEvent</event-type>
          </event-type-list>
      </playback-parameters>
    </channel>

Table 13-3 lists the child elements of playback-parameters that you can specify. Only dataset-name is required.

Table 13-3 Child Elements of playback-parameters

Child Element Description

dataset-name

Specifies the group of data that the user wants to group together.

In the case of BDB provider, the dataset name will be used as the database environment in Berkeley database.

In the case of the Oracle RDBMS-based provider, it specifies the database area, or schema, in which the tables that store the recorded events are queried for the playback events.

When configuring the Oracle RDBMS-based provider, you are required to specify this element.

event-type-list

Specifies the event types that are played back from the event store. If this element is not specified, then Oracle CEP plays back all event types.

Use the event-type child component to list one or more events, such as:

  <event-type-list>
      <event-type>EventOne</event-type>
      <event-type>EventTwo</event-type>
  </event-type-list>

When configuring the Oracle RDBMS-based provider, you are required to specify this element.

time-range

Specifies the time period during which play back should take place using a start and end time.

The time period is configured by using a start child element to specify a start time and an end child element to specify the end time.

Express the start and end time as XML Schema dateTime values of the form:

yyyy-mm-ddThh:mm:ss

For example, to specify that play back should start on January 20, 2010, at 5:00am and end on January 20, 2010, at 6:00 pm, enter the following:

  <time-range>
    <start>2010-01-20T05:00:00</start>
    <end>2010-01-20T18:00:00</end>
  </time-range>

For complete details of the XML Schema dateTime format, see http://www.w3.org/TR/xmlschema-2/#dateTime-lexical-representation.

If you do not specify a time period, then no events are played back when the application is deployed and play back will only happen after you explicitly start it using Oracle CEP Visualizer or wlevs.Admin.

You can specify time-range or time-range-offset, but not both.

time-range-offset

Specifies the time period during which play back should take place, using a start time and a duration.

The time period is configured by using a start child element to specify a start time and duration child element to specify the amount of time after the start time that play back should stop.

Express the start time as an XML Schema dateTime value of the form:

yyyy-mm-ddThh:mm:ss

Express the duration in the form:

hh:mm:ss

For example, to specify that play back should start on January 20, 2010, at 5:00am and continue for 3 hours, enter the following

  <time-range-offset>
    <start>2010-01-20T05:00:00</start>
    <duration>03:00:00</duration>
  </time-range-offset>

For complete details of the XML Schema dateTime format, see http://www.w3.org/TR/xmlschema-2/#dateTime-lexical-representation.

If you do not specify a time period, then no events are played back when the application is deployed and play back will only happen after you explicitly start it using Oracle CEP Visualizer or wlevs.Admin.

You can specify time-range or time-range-offset, but not both.

playback-speed

Specifies the playback speed as a positive float.

The default value is 1, which corresponds to normal speed. A value of 2 means that events will be played back 2 times faster than the original record speed. Similarly, a value of 0.5 means that events will be played back at half the speed.

repeat

Specifies whether to playback events again after the playback of the specified time interval is over.

Valid values are true and false. Default value is false. A value of true means that the repeat of playback continues an infinite number of times until it is deliberately stopped. False means that events will be played back only once.

max-size

If specified, Oracle CEP uses a stream when playing back events from the event store, and this element specifies the size of the stream, with non-zero values indicating asynchronous writes.

Default value is 1024.

max-threads

If specified, Oracle CEP uses a stream when playing back events from the event store, and this element specifies the maximum number of threads that will be used to process events for this stream. Setting this value has no effect when max-size is 0.

The default value is 1.

13.2.4 Starting and Stopping the Record and Playback of Events

After you configure the record and playback functionality for the components of an application, and you deploy the application to Oracle CEP, the server starts to record events only if you specified an explicit start/stop time in the initial configuration.

For example, if you included the following element in a component configuration:

<time-range>
    <start>2010-01-20T05:00:00</start>
    <end>2010-01-20T18:00:00</end>
</time-range>

then recording will automatically start on January 20, 2010 at 5:00 am.

The only way to start the playback of events, however, is by using Oracle CEP Visualizer or wlevs.Admin. You also use these tools to dynamically start and stop the recording of events.

For more information, see:

Visualizer and wlevs.Admin use managed beans (MBeans) to dynamically start and stop event recording and playback, as well as manage the event store configuration. A managed bean is a Java bean that provides a Java Management Extensions (JMX) interface. JMX is the Java EE solution for monitoring and managing resources on a network. You can create your own administration tool and use JMX to manage event store functionality by using the com.bea.wlevs.management.configuration.StageMBean.

For more information, see:

13.2.5 Description of the Berkeley Database Schema

When you configure a stage for event record and playback, you specify a dataset-name to identify the recorded data.

Oracle CEP server creates a subdirectory with this name below the db-env-path you specify in your bdb-config element.

For example, consider the bdb-config element is as Example 13-2 shows.

Example 13-2 Default bdb-config Element

<bdb-config>
    <db-env-path>bdb</db-env-path>
</bdb-config>

If your dataset-name is test1, then Oracle CEP server stores recorded data in directory:

ORACLE_CEP_HOME/user_projects/domains/domainname/servername/bdb/test1

Where ORACLE_CEP_HOME refers to the directory in which you installed Oracle CEP (such as /oracle_home), domainname refers to the name of your domain, and servername refers to the name of your server (For example, /oracle_cep/user_projects/domains/mydomain/myserver).

Within the data-set subdirectory, Oracle CEP creates a Berkeley database environment that contains a separate database for each event type you record. The database name is the same as the event type name as specified in the event type repository.

The database key is record time plus sequence number.

13.3 Creating a Custom Event Store Provider

Oracle CEP provides an event store API that you can use to create a custom event store provider. Oracle provides an RDBMS-based implementation for storing events in a relational database, or one that supports JDBC connections. If you want to store events in a different kind of database, or for some reason the Oracle RDBMS provider is not adequate for your needs, then you can create your own event store provider using the event store API.

The event store API is in the com.bea.wlevs.eventstore package; the following list describes the most important interfaces:

  • EventStore—Object that represents a single event store. The methods of this interface allow you to persist events to the store and to query the contents of the store using a provider-specific query.

  • EventStoreManager—Manages event stores. Only one instance of the EventStoreManager ever exists on a given Oracle CEP server, and this instance registers itself in the OSGi registry so that event store providers can in turn register themselves with the event store manager. You use this interface to find existing event stores, create new ones, get the provider for a given event store, and register an event provider. The event store manager delegates the actual work to the event store provider.

  • EventStoreProvider—Underlying repository that provides event store services to clients.

For more information, see the Oracle Fusion Middleware Java API Reference for Oracle Complex Event Processing.