Editing EventFlow Run Configurations

Open a Run Configuration Dialog

The primary way to open the Run Configuration or Debug Configurations dialogs for an EventFlow project is:

  • In the Project Explorer view, right-click the name of the EventFlow project of interest. From the context menu, select Run As>Run Configurations (or Run As>Debug Configurations)

You can also use one of the following alternative methods:

  • Select Run Configurations from the dropdown arrow next to the Run () button in the Studio toolbar (or next to the Debug () button).

  • Right-click in the EventFlow Editor canvas for your module. From the context menu, select Run As>Run Configurations.

  • In the Project Explorer, right-click the name of your project's EventFlow module. From the context menu, select Run As>Run Configurations.

Run configurations are stored as metadata in your Studio workspace. Thus, although your set of named Run Configurations is common to all your StreamBase projects, an individual Run Configuration includes the path to the individual module or project, so you cannot share Run Configurations between StreamBase or LiveView projects.

The top row of each run configuration dialog contains the Name field, common to all tabs:

Name

A configuration name is generated for you when you first run a fragment. You can change the name according to your site's standards. The name you enter is not reflected in the navigator pane on the left until you click Apply.

Create a New Run Configuration

Studio automatically creates a new Run Configuration for you the first time you run or debug a module, with the configuration taking the name of the top-level module being run. These Run Configurations are created with default settings, and you can edit or copy them to specify custom settings.

You can also create a new Run Configuration from scratch. To do this, open the Run Configurations or Debug Configurations dialog and do one of the following:

  • In the left pane, right-click EventFlow Fragment and choose New in the context menu.

  • In the left pane, select EventFlow Fragment and click the New toolbar button.

  • Select the name of an existing Run Configuration and click the Duplicate toolbar button.

Edit an Existing Run Configuration

A named Run Configuration does not exist for an EventFlow or LiveView project until you have run the fragment for that project at least once.

To edit an existing Run Configuration:

  • Open the Run Configurations or Debug Configurations dialog.

  • Select the name of the configuration to edit.

  • Make changes in the tabs of the wizard and click the Apply button before you leave each tab.

  • Click Revert to undo changes since the last saved version.

Note

The Run Configurations or Debug Configurations dialogs restart showing the last configuration you opened. This is not necessarily the configuration for the EventFlow module or LiveView project whose name was active when you invoked the Configurations dialog.

After applying your edits, you can:

  • Click Close to preserve your edits and exit the dialog.

  • In the Run Configurations dialog, click Run to run the edited Run Configuration.

  • In the Debug Configurations dialog, click Run to run and debug the edited Run Configuration.

Main Tab

The Main tab of an EventFlow Run Configuration configures the primary settings for running this fragment in Studio. This tab is described in two subsections for the upper and lower portions of this dialog page.

Main Tab, Module and Container

Main EventFlow Module

Specifies the path to the EventFlow module file to be run or debugged, using the Browse button. The resulting dialog shows the folder path to all EventFlow modules in your Studio workspace. Select the module of interest and click OK. If your EventFlow project is composed of multiple modules, select the primary module that calls other modules for processing.

Container

Accept the default StreamBase container named default, or specify a custom name to contain the top-level EventFlow module you selected in Main EventFlow Module.

Main Tab, Port Numbers

StreamBase engine port

Specifies the Client API listening port for this EventFlow engine. Choose one of the following options:

Configuration or default

Specifies that the EventFlow listening port is assigned by a configuration file of type sbclientapilistener in the project's src/main/configurations folder. If no configuration file sets the listening port for this project, a random, unused port is assigned.

Any available

Select this control to specify any port not currently in use. This control is the same for Studio as setting portNumber = 0 in a configuration file.

Specified

Select this control to specify a particular listening port number for this fragment's EventFlow engine. This setting can override a port set in a configuration file for the same launch.

Debug port

By default, StreamBase uses 8000 as the default port for EventFlow debugging. You can optionally specify a different debug port number, as required.

Main Tab, Configuration Settings

Specifies which configuration files to use in the next run or debug launch of this EventFlow project. By default, all configuration files in this project's src/main/configurations are selected. If your project contains more than one configuration file of the same HOCON root object, specify only one per root object. For example, if your project experimentally contains two configuration files of type sbengine with the same name and version values, the launch halts with a runtime error. Select which configuration file to use for the next launch from Studio.

You can override the standard load order for configuration files if, for example, one configuration defines a term used by another configuration, and the standard load order would load them out of order.

To do this, click New. This invokes the New Ordering Rule dialog, where you browse your project to specify a dependency order for the desired configuration file pair.

Once configured, load ordering rules appear in the bottom of the Main tab. Use this section to edit, remove, or create additional rules.

Node Tab

Cluster

The default cluster name for Studio-initiated nodes is the system login name in effect when Studio started, and is not specified in a Run Configuration. You can change the default, global cluster name in Studio Preferences.

Alternatively, you can specify a cluster name on a per-run configuration basis in the Use name field.

Node Name

This field specifies a name for the node that Studio creates to contain this fragment. For example, you can specify here the same node name you are using in your test and deployment environment with the epadmin command.

Studio's default node name is generated from a naming pattern generated from a set of variables. Use the Node Name Variables button to select a different set of project-related variables, or use the Other Variables button to specify variables available to Studio as a whole. The naming pattern you assign must include the S(SeqNum) variable, to make sure that a sequence number is assigned to make node names unique.

Node Installation Properties

Use this control to specify one or more parameters for Studio to use when it installs a node to contain this fragment. The valid parameters are the same as can be used with the epadmin install node command; run epadmin help node at the command prompt to see the available parameters.

The feature is best used with parameters such as memorysize to specify a JVM heap size larger than the default 512 MB for certain EventFlow or LiveView fragments.

Note

Do not specify parameters that are already specified in this Run Configuration or elsewhere in Studio.

For example:

  • Do not specify the application parameter, which is already specified in the Main EventFlow Module setting described above

  • Do not use the nodename parameter to name the node, which is already accomplished above.

  • Do not use the producthome parameter to override the location of the current StreamBase installation from which Studio is running.

  • Do not use the substitutions or substitutionsfile parameters. Specify those instead on the Parameters tab for this Run Configuration.

In addition, do not use parameters that change the default adminport, adminhost, discoveryport, or discoveryhost, or this node may fail to appear in Studio's Clusters view or with the epadmin display services command.

Advanced Tab

Intermediate Stream Dequeue

For debugging purposes only, you can dequeue data from intermediate streams in your application, not only from output streams. This debugging feature allows you to examine the value of a tuple at an intermediate point in the stream of tuples flowing left to right, before that tuple has been fully processed, and before it has arrived on an output stream. See Intermediate Stream Dequeuing for configuration options.

StreamBase Engine Logging Level

Select Use Default to specify using Studio's default global logging level, which is usually the INFO level. It is possible to specify a Logback configuration file as part of an EventFlow or LiveView fragment configuration that sets a higher or lower default logging level for the engine that is to run that fragment. It is also possible to use epadmin set commands to change an engine's current default logging level for an engine in a running StreamBase Application.

Also remember that adapters and some operators can set a logging level independent of the containing EventFlow fragment's default level.

Select Specified to override the current global logging level for the engine to be launched with the current configuration. The higher the log level you specify, the more messages and message types are sent to the Console view and/or to an output log file, if specified.

TRACE
DEBUG
INFO
WARN
ERROR

The Logback FATAL logging level is not specified in Studio Run Configurations because Studio handles and reports that condition with its own dialogs and Console messages. See Using StreamBase Logging for more information regarding current and legacy log levels.

VM arguments

Arguments that you specify here are used as command line arguments for the JVM engine that hosts the EventFlow fragment. Click Variables to invoke the Select Variable dialog, from which you can build a VM argument setting using Java standard system property names.

In general, set StreamBase properties with a HOCON configuration file instead of the VM arguments control. Use this feature sparingly, or under the direction of product Support.

Parameters Tab

Engine name

The next EventFlow fragment launch defined by this configuration has a default engine name generated by Studio. The Default setting is appropriate in the great majority of cases. You can see the engine name Studio chooses in the Clusters view at runtime. Select the Engine entry of a started node. The Name entry is near the top of the Properties list.

It is possible for a single node to contain more than one engine. For command-line launches, engines and engine name are specified in a HOCON configuration file of type c.t.e.dtm.c.node. Use the Specified option to direct this Studio Run Configuration to use the same engine name that will be used for command line launches. Valid characters for engine names are letters, digits, underline, hyphen, period, and dollar sign.

Deploy parameters

Set name-value pairs in the Deploy parameters field to pass command options to the deployment mechanism when running or debugging the EventFlow module. Deployment parameter options are shown in the following table.

Note

Deployment parameters are not the same as node installation parameters, which are configured on the Node tab.

Warning

Deployment parameters are an advanced feature, and incorrect settings can cause the next launch to fail. Use these parameters only to deploy to nodes that are local to where it is running.

Option Description
buildtype This option specifies the type of binaries the engine uses. The valid values are PRODUCTION or DEVELOPMENT. If not specified, the engine uses the same binary type as the node it runs in.
debug An enumeration indicating the level of diagnostic output. The valid values are:
  • enable ― a high level description of deployment activity

  • verbose ― detailed description of deployment activity

  • disable ― no diagnostic output

The default is disable.
discoverytimeout The number of seconds to wait while resolving a service name. Sub-second precision is supported, as in 1.25. The default value is 1.
displayversion A boolean flag indicating whether the product version information is to be displayed, defaulting to true. In Studio, this version information display occurs on a line beginning with status (fragment deploy): in the Console view.
exitonfailure A boolean flag that controls multi-node completion behavior. A value of true causes the deployment to return to the caller when any node returns a non-zero exit code. A value of false causes the deployment to not return until all nodes exit. The default value is false.
ignoreoptionsfile A boolean flag to suppress the default reading of the deployment options file. The default value is false. This option is only of interest for StreamBase® internal users.
keepaliveseconds The number of seconds that the node is to wait before terminating a deployed fragment when connectivity between the node and the deployment environment is lost. The default value is 10 seconds.
nodecleanup A boolean flag indicating whether the generated artifacts and state should be removed on engine exit. A value of true removes all generated artifacts and state, a value of false does not. The default value is true.
password The password to use when authenticating the StreamBase Runtime username during connections to the node. See username below.
prefix A boolean option with a value of true causes log output to be prefixed with the nodename. A value of false disables the nodename prefix. The default value is true.
reset This option with a value of true requests that all Java objects and any changed type definitions on the node be deleted before the fragment begins execution. If there is an engine already running, an error is reported and the new engine fails to start. The default value is false.
schedulerpolicy

On Linux, see the man page for sched_setscheduler (2) to understand the context of this parameter.

This parameter sets the scheduling policy and priority for the engine process. The syntax is policy: priority. The valid values for the policy are SCHED_FIFO, SCHED_RR, and SCHED_OTHER. The valid range for priority depends on the policy.

For Linux, the valid values for SCHED_FIFO and SCHED_RR are 1 to 99. If the schedulerPolicy cannot be set, the engine process is not started. In order to use real-time policies, the caller must have the appropriate permissions. On Linux, a security configuration file can be created to allow users to enable real-time policies. As an example, the following command allows the user sbuser to enable either SCHED_FIFO or SCHED_RR with a priority range from 0 to 70.

cat > /etc/security/limits.d/tibco.conf <<EOF
sbuser hard rtprio 70
sbuser soft rtprio 0
EOF
If running as root, you can set the required permission for root with the following command:
ulimit -r 99
Run this immediately before starting the node in the same shell that starts the node.
shutdowntimeoutseconds The maximum number of seconds to wait for an engine to shut down. The default value is 60 seconds.
username The user name in the StreamBase Runtime authentication realm to use when connecting to a node. Note that this is NOT the same user name as the StreamBase, LiveView, LiveView Web, or LDAP user names. The specified value must identify a principal with administrative privileges on the node. Defaults to the user.name system property, which is set as the UID of the user who executed the deploy tool client JVM.
Substitutions

Use this field to define substitution variables, or to specify a file that contains substitution variables. See HOCON Substitution Variables for more information on using substitution variables in configuration files.

Take, for example, a security configuration file that includes the property portNumber = ${LDAP_PORT}. If you include a Name-Value pair in the Substitutions table, where the name is LDAP_PORT and the value is a non-default port such as 5389, then when the project is run and the configuration file is read, the portNumber = line in that security configuration file is read as if the file contains: portNumber = 5389.

Source Tab

Use this tab to specify the location of JAR files or other Java resources needed by the next launch of this EventFlow fragment.

Note

Use this tab only for short-term testing or debugging of your EventFlow fragments.

Best practice to use external JAR files to install the JAR in your local Maven repository, as described in Using External JAR Files.

Environment Tab

Caution

The settings in the Environment tab have a very different meaning for EventFlow fragment Run Configurations than for the usual Java Run Configurations provided by Eclipse. Please read this section carefully.

Environment variables to set

Remember that all EventFlow fragments are launched into StreamBase Runtime nodes, and that nodes are always part of a StreamBase Runtime cluster.

Studio enables the Append environment to operating system environment setting by default. This means the shell environment for the operating system in which Studio runs is passed to and available to fragments running in nodes. Any variables specified in this tab can supplement the system settings, or can modify or override existing system environment variables.

You can select the Use specified environment only control to restrict the launched node's environment settings to those specified in this tab.

A StreamBase Runtime node has its environment set at node installation time. This has the following consequences:

  • Settings made in this tab can only affect the next node that Studio installs and starts. Remember that Studio installs a node and reuses it for the next launch of the same fragment. So even though this tab is part of the configuration for one EventFlow module, if you add or change environment variables in this tab, for them to take effect, you must stop and remove any existing node for this fragment using toolbar buttons in the Clusters view. Then at the next launch of this configuration, Studio installs and starts a new node with the new environment settings.

  • Settings made in this Environment tab only affect nodes installed and started by Studio. These settings are not preserved in any fragment archive you create from this project. Therefore, these settings are not carried into any StreamBase Runtime archive that includes this fragment.

  • Settings made in this tab are independent of command line launches made with the epadmin command. The epadmin command appends the shell environment to the node's environment at node install time. If you have made any custom environment settings in this tab, you must repeat those settings in the shell in which you run the epadmin command, or in configuration substitution values.

The New/Edit Environment Variable dialog contains a Variables button, which is a feature inherited from Eclipse. Use this button to specify the value of an environment variable using one or more Eclipse system variables whose contents are resolved by Eclipse when this configuration is run. Use the Help button on this dialog for further information on each available variable.

The list of variables includes ${sb_home}, which is defined as the absolute file system path of the StreamBase installation directory as currently set in Studio's Preferences dialog.

See Environment Variables for a further discussion of the ways environment variables are used in StreamBase.

Reserved Environment Variables

Fragment launches in Studio cannot set customized values for the TIBCO_EP_HOME or JAVA_HOME environment variables because those have particular meaning for Studio operations. This is true even if these variables are inherited from the system environment.

Studio detects and blocks attempts to use these two variables, whether explicitly specified in this Environment tab, or inherited from the system environment. In this case, Studio displays a warning dialog like the following.

Select the Remember my decision checkbox to suppress this warning dialog for future fragment launches.

Common Tab

The settings in the Common tab are common to all Eclipse Run Configurations. Use Eclipse Help to learn how more about these options.

Save as

This option determines where this Run Configuration is saved. The default setting, Local file, saves configurations in the workspace metadata area. As an alternative, you can select Shared file to save this Run Configuration as a file in one of your project folders. In this case, the Run Configuration is saved as Name.launch, where Name is specified in the Name field. Specify the target project folder using the Browse button.

Display in favorites menu

The favorites menu is a list of Run Configuration names that appears in the second section of the dropdown menu of the Run and Debug buttons on the toolbar. The first section contains a changing list of recently Run Configurations. Add a configuration to the favorites section to keep it in the menu, even when other applications have replaced it in the recently-run section. This option performs the same function as the Organize Favorites option in the Run and Debug drop-down menus.

Encoding

Use this section to specify a non-default character encoding for log messages sent to the Console View (and optionally to a standard output file).

Standard Input and Output

Allocate Console is selected by default. This specifies using the Console view to display logging messages written to standard output and standard error.

Input File is not supported by EventFlow fragment launches.

Output File is unselected by default. To specify that standard output and standard error of your fragment's run are written to a log file, select the Output File check box, and enter a path to a file. If the specified file does not exist, it is created for you. If both Allocate Console and Output File options are selected, log messages are written to both places.

You must designate the path to the file using Eclipse-specific syntax. Rather than typing a path, use the Workspace or File System buttons to navigate to a workspace or file system folder, and specify a file name. These buttons let Eclipse write the syntax for you. If you are familiar with the Eclipse syntax required in this field, you can use the Variables button to build up a path from components.

Append is dimmed unless the Output File option is selected. Select the Append checkbox to have log messages appended to the file specified in the Output File field. If unselected (the default setting), the designated file is overwritten with each run of this configuration.

Launch in background

Use this option to specify that the launching process itself runs in the background. (The StreamBase server that hosts your EventFlow fragment is always run in the background.) Selecting this box returns control to Studio immediately when you launch this configuration, without displaying the usual Starting Server dialogs.

Perspective Change Preferences

By default, running or debugging a StreamBase module with a Run Configuration automatically switches StreamBase Studio to the SB Test/Debug perspective, after prompting you to confirm. You can specify on the prompt dialog to not ask again.

The option to switch perspectives is not stored in the Run Configuration itself, but is a global setting for all StreamBase fragments, specified in Studio Preference Settings.

Back to Top ^