Launching Projects

Running Apama projects

Apama Plugin for Eclipse uses a project’s launch configuration to start the application. You can use the project’s default launch configuration or you can define one or more configurations for launching your Apama project in different ways.

Default launch configuration

An application’s default launch configuration starts the default correlator and uses all the monitors and events defined in the project. A project’s default launch configuration is available in both the Workbench and Developer perspectives.

To start an Apama project with the project’s default configuration, click (). This icon is enabled only if an Apama project is selected in the Project Explorer. When you run the Apama project, the project is started with default configuration. If the Apama project does not contain any configuration, a default configuration is applied before starting the project.

To stop an Apama project, click (). This icon is enabled only if a running Apama application is selected in the Project Explorer.

The Apama project must contain a .deploy file to run the Apama project. If a .deploy file is missing, the Apama project fails to start with incomplete configuration and you have to reset the configuration. To reset the launch configuration, right-click the Apama project and select Run as > Run Configurations. The .deploy file is created.

Apama validates the launch configuration before the correlator is started. If the launch configuration validation fails, the Run Configuration dialog displays an error indicating the configuration that has invalid entries, and an error icon appears on the tab that has invalid entries.

See also Troubleshooting connection problems in Apama Plugin for Eclipse.

Workbench perspective

To start the default launch configuration for the current project from the Workbench perspective

1. In the Workbench Project view, click the Start button (). This starts the default correlator with all the project’s monitors and events. Information about the running application is shown in the Console view.

2. To restart the application, click the Restart button () in the Workbench Project view.

3. To stop the click the Stop button () in the Workbench Project view.

Developer perspective

To start the default launch configuration for a project from the Developer perspective

1. In the Project Explorer view, select the project you want to run.

2. Select Run > Run from the menu. This starts the default correlator with all the project’s monitors and events. Information about the running application is shown in the Console view.

3. To stop a running application click the Terminate button () in the Console view.

Defining custom launch configurations

In many cases, you may want to create custom launch configurations, for example to run your applications with a subset of the monitors in your project or if your application relies on an IAF adapter. Note that the Apama Workbench perspective is targeted at creation of simple applications and so does not provide much support for projects with multiple launch configurations. If you need the power of multiple launch configurations, use the Apama Developer perspective.

When you create a new shared custom launch configuration, two files are created and are placed in the directory specified by Shared file. The names of these files have the following format and the launch configuration information is split between them:

• launch_config_name.deploy
• launch_config_name.launch

Any changes you make to the launch configuration will be reflected in the .deploy file. However, if you export a launch configuration to an Ant deployment script and then the shared location changes, then you must re-export the launch configuration to a new Ant deployment script. If you do not, the old Ant deployment script fails because it cannot find the .deploy file.

To create a launch configuration

1. In the Project Explorer view, select the project you want.

2. Do one of the following:

   • If you are using the Apama Developer perspective, select Run > Run Configurations from the menu. The Create, manage, and run configurations wizard starts. The wizard has four tabs, the Apama Project tab, the Components tab, the Environment tab, and the Common tab.
   • If you are using the Apama Workbench perspective, select the project of interest in the Workbench Project view and then click the Edit button just above the Start, Stop, and Restart buttons in the launch control panel. This allows the default launch configuration for the project to be edited. Creating multiple launch configurations is not recommended for Workbench perspective users.

3. In the wizard’s Name field, assign a name to the launch configuration.

4. On the Apama Project tab, fill in the following information:

   • Project — Specifies the project to launch.

5. The Components tab lists the components that are needed by the project such as additional correlators or external processes. You can add and remove components, edit their specifications, change the order in which they are started, or specify connections between correlators. Components are started in the order in which they appear in the Components tab from top to bottom. However, there is no waiting for one component to finish its startup before the next component is started. In other words, you cannot depend on startup for one component to already be complete when a subsequent component is started.

   You can use the following buttons:

   • Up — Moves the selected component up in the order in which it starts.
   • Down — Moves the selected component down in the order in which it starts.
   • Edit — Allows you to modify the settings for the selected component.
   • Remove — Removes the selected component from the launch configuration.
   • Add — Adds a correlator or an external process to the launch configuration. To add a component, click the Add button and select the type of component you want to add.
   • Restore Default — Sets the launch configuration to use the default launch configuration.
   • Connections — Displays the Connections dialog, which lets you add and remove connections between correlators. See Connecting correlators.

6. The Environment tab lists any additional environment variables needed to run any of the processes started by this launch configuration.

   You can use the following buttons:

   • New — Specifies a new environment variable.
   • Select — Selects an environment variable from the list of Eclipse environment variables.
   • Edit — Modifies the value of an environment variable.
   • Remove — Removes an environment variable from this configuration. Apama recommends that you append new environment settings to the native environment as otherwise it will be necessary to manually specify the standard Apama environment variables in order for the process to start correctly.

   Note that to add a suffix or prefix to an existing environment variable, a new environment variable of that name should be created, and the existing value specified as part of the variable’s value, for example, PATH=${env_var:PATH};C:\my path.

7. The Common tab specifies additional attributes for running this launch configuration.

   You can specify the following information:

   • Save as

     • Local file

     • Shared file — This is the default selection and the default path is the config\launch folder in your project directory. Click Browse to navigate to and select another location that is available to all users sharing this project.

       When Shared file is selected, two launch configuration files are created and placed in the directory specified by Shared file. The names of these files have the following format and the launch configuration information is split between them:

       • launch_config_name.deploy
       • launch_config_name.launch Any changes you make to the launch configuration will be reflected in the .deploy file. However, if you export a launch configuration to an Ant deployment script and then the shared location changes then you must re-export the launch configuration to a new Ant deployment script. If you do not, the old Ant deployment script fails because it cannot find the .deploy file.

   • Display in favorites menu — Select the appropriate checkbox to display this configuration as a choice in the drop-down menu of the Debug or Run button in the toolbar.

   • Console encoding — The default encoding for output to the console is Cp1252. To encode console output in a different format, click Other and select the encoding you want. For example, UTF-8.

   • Standard Input and Output

     • Allocate console (necessary for input) — For correlator launch configurations, there are no reasons not to allocate a console. Allocating a console does not affect performance.
     • File — If you want to capture correlator output in a file, navigate to and select a file to contain the correlator output.
     • Append — When you capture correlator output in a file, indicate whether you want to append the output to the specifies file.

   • Launch in background — The default is that the correlator runs as a background process.

Adding a correlator

When you add a correlator to the launch configuration, the Correlator Configuration dialog appears. The Correlator Configuration includes the following tabs:

• Correlator Arguments
• Persistence Options
• Connectivity
• Injections
• Event Files

Correlator arguments

The Correlator Arguments tab specifies the options and arguments that Apama Plugin for Eclipse uses to start the correlator.

You can accept the default values or change one or more arguments. You can also add arguments. In addition, you can also control the behavior with the following options:

• Hostname — localhost. The name of the correlator host machine.

• Port — This is the port on which the correlator listens for monitoring and management requests.

• Log level — Default is INFO.

• Log to file — Default is ${LAUNCH_CONFIG_NAME}_${CORRELATOR_NAME}.output.log. This is the main correlator log file.

• Input log — Default is Correlator_1_${START_TIME}_${ID}.input.log. This log contains all incoming messages. See Replaying an input log to diagnose problems.

• Configuration — Select this option to provide additional configurations to the correlator using the CorrelatorConfig.yaml file in the projectdir\config\ directory. For example, per-package logging settings. See Configuring the correlator.

• Reuse correlator — Select this option to use an already running correlator.

• Clear correlator — Select this option to delete all the correlator contents when the launch starts.

• Java support — Select this option to provide Java support for EPL plug-ins written in Java or JMon applications. Normally this is automatically selected when creating either in Apama Plugin for Eclipse.

  Info

  Apama’s in-process API for Java (JMon) is deprecated and will be removed in a future release.

• JMS support — Select this option to provide JMS support for correlator-integrated messaging. Normally this is automatically selected when the correlator-integrated adapter for JMS is added to an Apama application. This feature is deprecated and will be removed in a future release.

• Distributed MemoryStore support — Select this option to provide support for distributed MemoryStore. With the distributed MemoryStore, you can create distributed stores that provide access to data that will be shared among Apama applications running in separate correlators. This feature is deprecated and will be removed in a future release.

• Maximum Java heap size in MB (-Xmx). Default is 512.

• Maximum Java off-heap storage in MB (-XX:MaxDirectMemorySize). Default is 16384.

• Extra command line arguments. Specify any additional arguments for starting the correlator. See Starting the correlator.

Persistence options

The Persistence Options tab specifies the correlator persistence settings Apama Plugin for Eclipse will use when it runs this launch configuration.

• Enable correlator persistence — When set, this tells the correlator to start with the persistence option.
• Directory location — This specifies the location on disk of the persistent store used to preserve correlator state.
• Startup options — These options specify the startup behavior of the correlator with respect to how it handles its persistent store.
  • Clear state and re-inject — Specifies that you want to clear the contents of the recovery datastore.
  • Resume from persistent state — Specifies that the correlator will restart using the state from its persistent store as of the last committed snapshot.
  • Prompt for startup options dialog during correlator launch — Specifies that Apama Plugin for Eclipse will present a dialog when launching the application. The dialog asks whether to clear the correlator state information and re-inject the application code or to resume from the state information stored in the last committed snapshot.

For more information on correlator persistence, see Using correlator persistence.

For more information on persistence options for starting the correlator, see Starting the correlator.

Connectivity

The Connectivity tab lists all the valid user connectivity instances that will be injected or sent into the correlator when Apama Plugin for Eclipse runs this launch configuration.

Injections

The Injections tab lists the files, except event files, that will be injected or sent into the correlator when Apama Plugin for Eclipse runs this launch configuration. This includes the files that are in your project as well as additional files that have been added to the project build path. See Defining custom launch configurations.

By default the Injections tab lists all EPL files in the project. The files are listed in dependency order. This is the order in which Apama Plugin for Eclipse will load the files. Apama Plugin for Eclipse determines the dependency order when it builds the project. In almost all projects, you do not need to change the order. However, if necessary, you use the Injections tab to change the order in which Apama Plugin for Eclipse injects the EPL files.

Select Automatic Ordering to exclude files from the launch configuration by clearing the check mark. When you run this project the cleared files are not injected.

Select Manual Ordering:

• To arrange the files in the required order.
• To see the invalid entries in the launch configuration. For example, if a monitor file is missing, the error icon appears on the Components tab and the Injections tab. You can remove the invalid entries by clicking Remove Missing.

All selected EPL files are injected and then all selected .evt files (on the Event Files tab) will be injected.

Event Files

The Event Files tab lists the event files that will be injected or sent into the correlator when Apama Plugin for Eclipse runs this launch configuration. This includes event files that are in your project as well as additional event files that have been added to the project build path. See Defining custom launch configurations.

By default the Event Files tab lists all .evt files in the project. The files are listed in lexicographic order by file name. This is the order in which the files will be injected.

If necessary, you use this tab to change the order in which the project’s event files are to be injected. Select the file whose position you want to change and click the Up or Down button as many times as needed. It is up to you to ensure that the files are injected in the correct order.

If you uncheck a check box, the corresponding event file remains in the list, but will not be injected during this launch configuration.

All selected EPL files (listed on the Injections tab) are injected and then all selected .evt files will be injected.

Configuring correlator log settings in Designer

When you create a new Apama project, a file called CorrelatorConfig.yaml is created in the projectdir\config\ directory. You can use this file to customize the correlator settings such as log levels and log files that are used for each part of your EPL application. For more information about how to use this file to configure logging, see Setting EPL log files and log levels in a YAML configuration file.

If you want to use this file, you must edit the launch configuration and select the Configuration check box on the Correlator Arguments tab.

Connecting correlators

When you are creating a custom launch configuration you can specify connections between correlators. This is similar to connecting correlators with the engine_connect correlator utility.

Each connection you add goes in only one direction. For example, suppose you define a connection from correlatorA to correlatorB. This connection lets correlatorA send events to correlatorB. If you want correlatorA to receive events from correlatorB you must add a second connection that specifies correlatorB as the source of the connection and correlatorA as the target of the connection.

To connect correlators

1. In the Run Configurations dialog, select the Components tab and ensure that the correlators you want to connect are listed as components. See Adding a correlator.

2. Click Connections.

3. In the Connections dialog, click Add, which activates a row in the connections table.

4. In the activated row, in the From field, select the name of the correlator that is the source of this connection. If the name of the correlator you want to connect does not appear, click Cancel to return to the Components tab and then select Add > Add Correlator.

5. In the To field, select the name of the correlator that is the target of this connection.

6. In the Channel field, specify one or more channels to be used by this connection. Use a comma as a separator. For example,channelA, channelB.

7. In the Flags field, specify any options that are supported by the engine_connect utility.

   See Correlator pipelining.

After adding the desired connections, click OK to return to the Components tab.

To remove a connection, select the row that defines the connection and click Remove.

Adding an external process

When you add an external process to the launch configuration, the External Process Configuration dialog appears.

This dialog allows you to add and edit an external process associated with the launcher. You can enter the relevant information in the following fields:

• Name — The name is a unique name in the launcher.
• Command — This is the command line string that is used to invoke the external process. This command string can use the variables from the Workspace, File System, or Variables configured in Eclipse. These variables are replaced with their corresponding values when launched.

Testing a subset of your Apama application

In a large Apama application, you might want to test a subset instead of the entire application. The best way to do this is to define a launch configuration that injects only the monitors you want to test. Use this configuration only to test the subset. Create a different launch configuration to test the entire application.

The reason you want a separate configuration for testing the subset is that you must disable the monitors in your project that are not in the subset you want to test.

To disable a file in a launch configuration

1. Define the launch configuration as you normally would. See Defining custom launch configurations.

2. In the Create, manage, and run configurations dialog, on the Components tab, select the correlator in which you want to perform the testing and click Edit. Or, click Add > Add Correlator to add the correlator on which you want to do the testing.

3. In the Correlator Configuration dialog that appears, on the Initialization tab, deselect the file(s) you do not want to inject.

4. Click OK, Apply, and then Run or Close.

Troubleshooting connection problems in Apama Plugin for Eclipse

If you have a proxy configuration, ensure that the proxy is bypassed for localhost and any hosts that the proxy cannot access. An incorrect proxy configuration can prevent Apama Plugin for Eclipse to connect to a correlator when a project is started. It is recommended to set Window > Preferences > General > Network Connections > Active Provider to Direct if you experience issues connecting to a correlator from Apama Plugin for Eclipse.

In the case of a network timeout, a warning message is written to the correlator log indicating that the connection timed out communicating with host:port after a timeout of n seconds. If this occurs, check the status of the network and ensure that this machine, and any other machines it is connected to, have sufficient CPU or memory resources.

Monitoring Apama applications

Apama Plugin for Eclipse provides various ways to monitor a running Apama application:

• Console view
• Engine Information view
• Engine Receive view
• Engine Status view
• Scenario Browser

Note that in the Apama Developer perspective, it is possible to launch multiple projects at any one time. By default, the Console view and the Scenario Browser view will display information about the most recently launched correlator. To monitor a different correlator, select Window > Show View > Other > Debug from the menu and select the Debug view — this lists all running launches. Select the correlator that you wish to monitor from this list.

Opening the Apama Runtime perspective (see The Apama Runtime perspective) results in a convenient layout of all the available Apama Runtime views. This is the recommended way to make use of these views. You can switch back to the Apama Developer or Apama Workbench perspective at any time.

Console view

The Console view displays information concerning a running Apama application. An application can have several consoles:

• Correlator — Displays output from the correlator.
• Engine Inject —Displays initialization information injected to the correlator.
• Engine Send — Displays information from Apama components that stream data to the correlator.
• Correlator Initialization — Displays information about the correlator initialization including the Java files, and the .mon files (monitors) that have been injected and the .evt files (events) that have been sent and whether the actions succeeded or failed.

To view one of these consoles, click the drop-down arrow of the Display Selected Console button () and select the console you want.

Using the Engine Information view

• Sending an event from the Engine Information view.

The Engine Information view inspects a running correlator and displays defined contents of the correlator. It displays the same information as the Apama command line tool engine_inspect.

The information is grouped as follows (click on the right-facing triangle to view the contents of each group):

Aggregates — The names of custom (user-defined) aggregate functions that have been injected. You use aggregate functions in stream queries. Apama built-in aggregate functions are not listed.

Contexts — The names of any user-defined contexts, how many monitor instances are running in each context, how many entries are on each context’s input queue, and the names of any channels each context is subscribed to.

Events — The names of all event types in the correlator, and the number of templates of each type, as defined in listener specifications.

Java Monitors — The names of all Java applications in the correlator and the number of event listeners each Java application has created.

Monitors — The names of all monitors in the correlator and the number of monitor instances each monitor has spawned.

Plugin Receivers — The names of any plug-in receivers, the channels each plug-in receiver is subscribed to, and the number of items on each plug-in receiver’s input queue. A plug-in receiver is an EPL plug-in that is subscribed to one or more channels.

Receivers — The names of any external receivers, the address of each external receiver, the channels each external receiver is subscribed to, and the number of entries on the output queue of each external receiver.

Timers — Displays the current EPL timers active within the system. The four types of timers that might be displayed here are wait, within, at, and stream. The stream timers are those set up to support the operation of a stream network.

Displaying information in the Engine Information view can slow performance, so you may want to close the view if Apama Plugin for Eclipse is not very responsive.

The following actions are available:

• () Delete button — Direct deletion of the defined named entities. You can also delete the entity by right clicking the entity and selecting Delete from the drop down menu. A confirmation message appears after you click Delete. If the entity has dependencies on it, a confirmation message appears asking if you want allow a forced deletion.
• () Send button — Send an event from this view. For information on sending an event from this view, see Sending an event from the Engine Information view.

Sending an event from the Engine Information view

You can send an event from the Engine Information view using the Send Event dialog. You can also send the events using the engine_send tool. See Sending events to correlators.

To send an event

1. In the Engine Information view, expand Events.

2. Double-click the event that you want to send or click the () icon to specify the events to send.

   The Send Event dialog appears. If you have clicked the () icon, you must provide the event in the Event field.

   For example, the following event definition has been defined in a.mon file:

   event Measurement {
       string deviceId;
       sequence<any> measurements;
       optional<location> loc;
   }
   event Temperature {
          string unit;
          integer value;
   }
   event Speed {
          string unit;
          integer value;
   }
   

   With the above event definitions, you can specify one of the following events in the Event field:

   • Temperature("celcius",23)
   • Measurement("Carrera_4",[any(Speed,Speed("mph",20)),any(Temperature, Temperature ("celcius",23))],optional((15.23,24.24,19.132,28.83)))
     Info

     Using the Send Event dialog, you can only send a single event at a time.

3. Optionally, in the Channel field, specify the channel on which monitors are subscribed. An empty string in the Channel field goes to all public contexts.

4. Click OK.

Using the Engine Receive view

The Engine Receive view shows all events generated from the connected correlator. Each batch of events is separated with an optional separator.

You can also change whether to display the separator line and change how it appears by clicking the drop down arrow at the top right of the view to display the menu and select Options. See Engine Receive Viewer preferences.

• Select All — Select all text in the console.
• Clear — Clear all text in the console.
• Copy — Copy all selected text to the clipboard
• Show Separator — Show a separator line in each event batch.
• Show Date/Time of batch — Show a date/time of each event batch

Click the Toggle Connection button () to temporarily disconnect the Engine Receive view from the correlator.

When the Toggle Connection button is pressed, the console will not update any further events from correlator. The background of the console will be changed to indicate the temporary disconnect mode. The Select All, Clear, and Copy actions will still work in this mode.

To resume from the temporary disconnect mode, simply click on the Toggle Connection button again to resume the connection. The console will be cleared and new events will be shown in the console again.

Engine Receive Viewer preferences

You can change the display options of the Engine Receive view by clicking the drop down arrow at the top right of the view. From the menu select Options, which displays the Engine Receive Viewer Preferences dialog. This dialog contains settings that specify how information appears in the Engine Receive view.

Display a separator — Toggles whether each batch of events is visually separated.

Display date/time for batch — Toggles whether the date and time for each batch of events appears.

Custom text for separator — Specifies the characters composing the separator.

Max window size (KB) — Select a setting between 100 and 10000.

Specifying channels for the Engine Receive View

In the Engine Receive view, click the drop down arrow at the top right of the view to display the menu and select Set channels….

The Channel configuration dialog lists the channels on Engine Receive listens.

For channels already listed, enable or disable them by checking or unchecking the check box next to the channel name.

• New — Add a new channel to listen on.
• Edit — Modify the name of the selected channel.
• Delete — Removes the selected channel.
• Select All — Enable listening on all listed channels.
• Unselect All — Disable listening on all listed channels.

Using the Engine Status view

The Engine Status view displays the information about the correlator status. The information is the same as the output of Apama command line tool engine_watch. See the meanings of the standard status messages in List of correlator status statistics for detailed information.

Using the Scenario Browser view

Apama’s Scenario Browser view displays the DataView and query definitions loaded into the correlator along with the metadata for the DataViews and queries. For queries, Scenario Browser displays parameterized and non-parameterized queries that are running along with the query parameter values. In the Scenario Browser, you can add, edit, and delete the parameterized query instances.

A non-parameterized query contains a single default instance. You cannot edit or delete the default instance. Editing and deleting options are disabled for the default instance.

If you want to add or delete a DataView item, you must use EPL, that is, you have to send another event to the EPL which will then issue the creation or deletion.

Displaying the Scenario Browser

By default, in the Apama Workbench perspective, the Scenario Browser is opened when you launch an application. In the Apama Developer perspective, you need to display the Scenario Browser view manually by selecting Window > Show View > Scenario Browser from the menu.

Apama Developer perspective users may find it more convenient to switch to the Apama Runtime perspective (see The Apama Runtime perspective). You can switch back to the Apama Developer perspective at any time. The details of the selected correlator are shown in the right pane.

Browsing query definitions

To examine a query definition, click the name of the query definition in the left pane. The Scenario Browser displays the information in two tabs in the right pane:

• The Details tab displays the metadata of the selected query.

To choose which columns to display

1. Click the drop down arrow next to the Options button () near the top right of the Scenario Browser.
2. Select the Choose Columns menu item.
3. In the Summary Table Column Selector dialog, add checks to the columns you want to display or remove checks from those you do not want to display.
4. Click OK.

To apply a filter to limit the rows to display

1. Click the drop down arrow next to the Options button () near the top right of the Scenario Browser.
2. Select the Filter menu item.
3. In the Summary Table Filter Selector dialog, add checks to the filter you want to apply. You can filter by Owner or Status.
4. Click OK.

Creating a new instance a parameterized query

In the Scenario Browser view, you can create new instances of a parameterized query that is running in the application.

1. In the Scenario Browser’s left pane, select the query for which you want to create a new instance.

2. Click the Create a new instance of this scenario button (()). The Add scenario instance dialog displays the details including the input and output variables that make up the query definition in the left-hand column. The right-hand column displays the values of those variables.

3. To create an instance of a parameterized query, you must specify values for the input fields in the right-hand column. Fields with default values are already filled in. You can add or edit values in cells that have a white background. To specify a value, double click in the empty cell and enter the information.

4. Click OK.

Viewing the instances of a scenario

You can display the details of a scenario instance (query or DataView) in the Scenario Browser.

• In the Scenario Browser, select the instance ID of the scenario. In the right pane, the names of the variables are shown in the left column and the current values of the variables in the right column. The values of the output variables are continuously updated.

  You can expand and collapse the display in the right pane by clicking the plus and minus symbols.

Editing an instance of a parameterized query

To edit the input values of a parameterized query instance

1. In the left pane of the Scenario Browser, select the instance ID of the query you want to edit.

2. Click the Edit button (). The Edit scenario instance dialog appears. While you are editing the values in the dialog, Apama Plugin for Eclipse suspends the display of output information.

3. Edit the values for the input fields in the right-hand column by double clicking in the desired cell and entering the new value.

4. Click OK. Apama Plugin for Eclipse resumes displaying output values.

Deleting an instance of a parameterized query

To delete a parameterized query instance

1. In the left pane of the Scenario Browser, select the instance ID of the query you want to delete.

2. Click the Delete button ().

Deleting all instances of a parameterized query

To delete all instances of a parameterized query

1. In the left pane of the Scenario Browser, select the name of the query for which you want to delete all the instances.

2. Click the Delete All button ().