15 Debug with Event Record and Playback

You can use the event record and playback feature to debug a running Oracle Stream Analytics 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 Run the Event Record/Playback Example in Getting Started with Event Processing for Oracle Stream Analytics.

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 follows
Description of "Figure 15-1 Configuring Record and Playback in an EPN"

15.2 Berkeley DB

Berkeley DB is a fast, scalable, transactional database with industrial grade reliability and availability.

When you record events, by default the Oracle Stream Analytics server stores them in Berkeley DB, which is a persistent event store that is bundled with the Oracle Stream Analytics server. 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 Analytics 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 Analytics. 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 Analytics 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 Analytics 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 Analytics Visualizer or wlevs.Admin. Oracle Stream Analytics 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 Analytics 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 Analytics server:

  1. Stop the Oracle Stream Analytics server instance, if it is running.
  2. 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.

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

  4. Restart the Oracle Stream Analytics 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 Component Configuration in Schema Reference for Oracle Stream Analyticsfor additional information.

  1. 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>
    
  2. 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 Analytics 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 Analytics 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 Analytics 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 Analytics 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 Analytics 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 Analytics 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 Analytics 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 Component Configuration in Schema Reference for Oracle Stream Analytics for additional information.

  1. 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>
    
  2. 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 Analytics 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 Analytics 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 Analytics 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 Analytics 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 Analytics 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 Analytics, 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 Analytics 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: