20 Configuring Event Record and Playback

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

20.1 Overview of Configuring Event Record and Playback

Oracle Event Processing 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.

Where ORACLE_CEP_HOME refers to the directory in which you installed Oracle Event Processing (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).

20.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.

20.1.1.3 Persistent Event Store Schema

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

20.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 Event Processing stores the events that flow out of it to the appropriate store along with a timestamp of the time it was recorded.

20.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 Event Processing 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 Event Processing Visualizer or wlevs.Admin). Oracle Event Processing 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 Event Processing records the playback events as well as the "real" events.

20.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 Event Processing. You can also use these APIs to delete old events from the event store.

20.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 Event Processing installation directory, such as d:\oracle_cep.

20.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.

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

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.

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

Table 20-1 Child Elements of bdb-config

Child Element

Description

db-env-path

Specifies the subdirectory in which Oracle Event Processing 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.

20.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.4.2, "Overview of 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.

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:

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 Event Processing 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

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 Event Processing 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 Event Processing 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 Event Processing 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 Event Processing 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 Event Processing 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.

20.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.4.2, "Overview of 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:

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 Event Processing 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

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 Event Processing 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 Event Processing 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 Event Processing 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.

20.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 Event Processing, 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:

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.

20.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 Event Processing 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 20-2 shows.

Example 20-2 Default bdb-config Element

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

If your dataset-name is test1, then Oracle Event Processing 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 Event Processing (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 Event Processing 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.

20.3 Creating a Custom Event Store Provider

Oracle Event Processing 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 Event Processing 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.