15 Debug with Event Record and Playback

You can use the event record and playback feature to debug a running Oracle Stream Explorer application. While the application runs, you record the events that flow out of an EPN component into a persistent store. You play the events back at a later stage in the application such as in an event bean. In the event bean, you query the events and make fixes to your application based on your findings.

The sample code in this chapter is from the event record and playback example in /Oracle/Middleware/my_oep/examples/source/applications/recplay. For details about running and building the example, see Getting Started with Event Processing for Oracle Stream Explorer.

This chapter includes the following sections:

15.1 Event Flow

The following graphic shows the EPN of the event record and playback example to demonstrate where you can record events and where you can play events back. The simpleEventSource adapter is configured to record events. The recording happens as events flow out of the adapter. The eventStream channel is configured to play back events. The playback happens where events flow into the channel.

Figure 15-1 Configuring Record and Playback in an EPN

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

15.2 Berkeley DB

When you record events, by default the Oracle Stream Explorer server stores them in Berkeley DB, which is a persistent event store that is bundled with the Oracle Stream Explorer server. Berkeley DB is a fast, scalable, transactional database with industrial grade reliability and availability. For more information about Berkeley DB, see:

http://www.oracle.com/technetwork/database/database-technologies/berkeleydb/overview/index.html.

When you deploy an application that is configured to use the record and playback feature, the Oracle Stream Explorer server creates the database schema and an instance of Berkeley DB in the following directory.

/Oracle/Middleware/my_oep//user_projects/domains/domainname/servername/bdb

Note:

The database key is the record time plus the sequence number.

You can 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 Configure Berkeley DB for information about how to configure Berkeley DB.

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 for the default persistent event store provider included with Oracle Stream Explorer. You can also use these APIs to delete old events from the event store.

15.3 Record Events

You can configure recording for any component in the EPN that produces events, such as processors, adapters, channels, and event beans. Processors and channels always produce events. Adapters and event beans must implement the EventSource interface.

You can configure events from different components in the EPN to be stored in different persistent stores, or that all events go to the same store. Only events that are output 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 Stream Explorer stores the events that flow out of it to the appropriate store along with a time stamp of the time it was recorded.

15.4 Play Back Events

You can configure playback for any component in the EPN: processors, adapters, streams, and event beans. Typically the playback component is a stage later in the network than the stage 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 of 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 Stream Explorer plays back the events in a time accurate manner. However, you can 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 with Oracle Stream Explorer Visualizer or wlevs.Admin. Oracle Stream Explorer reads the events from the persistent store and inserts them into the appropriate place in the EPN.

When a component receives a playback event, the playback event looks exactly like the original event. If a downstream component is configured to record events, then Oracle Stream Explorer records the arriving playback events and real-time events.

For more information, see:

15.5 Configure Berkeley DB

You can use the default Berkeley DB configuration as is. You only need to make configuration changes to customize the location of the Berkeley database instance or to set the cache size to tune performance.

To configure an event store for Oracle Stream Explorer server:

Stop the Oracle Stream Explorer server instance, if it is running.
Open the server config.xml file for editing.
The file is located in /Oracle/Middleware/my_oep/user_projects/ domains/<domain_name>/<server_name>/config.

Edit the bdb-config element in the config.xml file.

The following example shows a fully configured bdb-config element.

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

Table 15-1 lists the bdb-config child elements.

Table 15-1 Child Elements of bdb-config

Child Element Description

db-env-path

Specifies the subdirectory in which OracleEvent Processing server creates the Berkeley DB instances relative to the config directory of your server.

Default: bdb

cache-size

Specifies the amount of memory, in bytes, available for Berkeley DB cache entries. You can adjust the cache size to tune Berkeley database performance. The cache size must be a power of 2, but it is otherwise limited only by available memory and performance considerations.

Default: je.maxMemoryPercent * JVM maximum memory.

Restart the Oracle Stream Explorer server.

15.6 Configure a Component to Record Events

You can configure any processor, adapter, channel, or event bean in your application to record events. This section updates an adapter configuration to record events. See Schema Reference for Oracle Stream Explorer for the complete XSD Schema that describes the event recording configuration file elements.

Open the component configuration file and add a record-parameters child element to the component you want to configure to record events, as follows:

    <csv-adapter>
      <name>StockTradeCSVAdapter</name>
      <record-parameters>
          ...
      </record-parameters>
    </csv-dapter>

Add child elements to record-parameters to specify a data set name, the list of one or more events to be stored, the recording start and stop times, and so on:

<csv-adapter>
  <name>StockTradeCSVAdapter/name>
  <record-parameters>
    <dataset-name>recplay_sample</dataset-name>
    <event-type-list>
      <event-type>TradeEvent</event-type>
    </event-type-list>

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

  </record-parameters>
</csv-adapter>

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

Table 15-2 Child Elements of record-parameters

Child Element	Description
`dataset-name`	Berkeley DB: Identifies the recorded data and places it in a directory of this name below the directory specified by the `db-env-path` setting in the server `config.xml` file. Oracle RDBMS-based provider: Specifies the database area, or schema, in which the tables that store the recorded events are created. When you configure the Oracle RDBMS-based provider, you must specify this element.
`event-type-list`	Berkeley DB: Specifies the event types that are recorded to the event store. If this element is not specified, then Oracle Stream Explorer records all event types that flow out of the component. Oracle RDBMS-based provider: You must specify this element.
`time-range`	Specifies the time period during which recording takes place. Configure the time period with 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 have recording start on January 20, 2010, at 5:00 am 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 happens only after you explicitly start it with Oracle Stream Explorer 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 takes place. Configure the time period with a `start` child element to specify a start time, and a `duration` child element to specify the length of time to run the recording. 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 have recording start on January 20, 2010, at 5:00 am 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 happens only after you explicitly start it with Oracle Stream Explorer 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 Stream Explorer 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 Stream Explorer 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`	When specified, Oracle Stream Explorer uses a stream when writing to the event store, and this element specifies the size of the stream. Non-zero values indicate asynchronous writes. Default value is 1024.
`max-threads`	When specified, Oracle Stream Explorer uses a stream when writing to the event store, and this element specifies the maximum number of threads to be used to process events for this stream. Setting this value has no effect when `max-size` is 0. The default value is 1.

15.7 Configure a Component to Play Back Events

You can configure any processor, adapter, channel, or event bean in your application to play back events. The component must downstream from the recording component so that the playback component can receive the events and play them back. This section updates a channel configuration to play back events.

See Schema Reference for Oracle Stream Explorer for the complete XSD Schema that describes the event playback configuration file elements.

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:
```
<channel>
  <name>eventStream</name>
  <playback-parameters>
   ...
  </playback-parameters>
</channel>
```

Add child elements to playback-parameters to specify a data set, one or more events to be 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 15-3 lists the child elements of playback-parameters that you can specify. Only dataset-name is required.

Table 15-3 Child Elements of playback-parameters

Child Element	Description
`dataset-name`	Berkeley DB: Identifies the recorded data and places it in a directory of this name below the directory specified by the `db-env-path` setting in the server `config.xml` file. Oracle RDBMS-based provider: Specifies the database area, or schema, in which the tables that store the recorded events are created. When you configure the Oracle RDBMS-based provider, you must specify this element. When you configure the Oracle RDBMS-based provider, you must specify this element.
`event-type-list`	Berkeley DB: Specifies the event types that are played back from the event store. If this element is not specified, then Oracle Stream Explorer plays back all event types. Oracle RDBMS-based provider: You must specify this element.
`time-range`	Specifies the time period during which play back takes place with a start and end time. Configure the time period with 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 to 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 happens only after you explicitly start it using Oracle Stream Explorer 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 takes place with a start time and a duration. Configure the time period with a `start` child element to specify a start time and a `duration` child element to specify the length of time to play back events. 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 playback happens after you explicitly start it using Oracle Stream Explorer 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 are played back 2 times faster than the original record speed. 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 completes. 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 are played back once.
`max-size`	If specified, Oracle Stream Explorer uses a stream when playing back events from the event store. This element specifies the size of the stream with non-zero values indicating asynchronous writes. Default value is 1024.
`max-threads`	If specified, Oracle Stream Explorer uses a stream to play back events from the event store. This element specifies the maximum number of threads to use to process events for the stream. This value has no effect when `max-size` is 0. The default value is 1.

15.8 Start and Stop 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 Stream Explorer, the server starts to record events only when you have configured explicit star and stop information in the configuration file. For example, if you included the following element in a component configuration, then recording starts on January 20, 2010 at 5:00 am:

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

To enable the recording and playback of events, use Oracle Stream Explorer Visualizer or wlevs.Admin. Once recording and playback are enabled, they start and stop according to their configuration settings.

For more information, see:

Visualizer and wlevs.Admin use managed beans (MBeans) to dynamically start and stop event recording and playback and 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 with com.bea.wlevs.management.configuration.StageMBean.

For more information, see: