Chapter 13 BusinessEvents Performance Profiler : Working With the Profiler

Working With the Profiler
This section explains the different ways you can turn the profiler on and off.
To Turn Profiler On and Off Using Engine Properties
Set the following properties in the be-engine.tra file of the node or nodes of inference agent or agents whose RTC performance you want to profile.
be.engine.profile.BAR_Name.enable
If set to true, enables profiler for the specified rule session (BAR_Name) when the rule session initializes. A rule session is also known as an inference agent.
If set to true, enables the profiler for all rule sessions when each rule session initializes, even when a specified rule session profiler is disabled.
be.engine.profile.BAR_Name.file
Optional, if be.engine.profile.*.file is specified.
If be.engine.profile.*.file is specified and be.engine.profile.BAR_Name.file is not specified, then the file name is the value of be.engine.profile.*.file, with the BAR_Name appended.
If the properties be.engine.profile.*.file and be.engine.profile.BAR_Name.files are not specified the following occurs:
The file name is be-profile.csv, followed by an underbar, followed by the BAR_Name: be-profile_BAR_Name.csv
Spaces in a BAR name are replaced in the file name by the underbar character. For example my bar becomes my_bar.
The default (prefix for the) name of the output file that the profiler writes to. In all cases, the appropriate BAR_Name is appended.
Default name is be-profile.csv and it is located under the current working directory, if file name is not specified.
be.engine.profile.BAR_Name.duration
When the duration period ends, the profiler continues to collect statistics for the current RTC until the RTC is completed, then outputs data and stops. So the RTC in progress is always completed, even if the profiler is directed to stop during an RTC.
If you set duration to a value of zero or less (<= 0), then profiling continues until rule session ends or profiler is explicitly turned of using a function or Hawk method.
When the duration period ends, the profiler continues to collect statistics for the current RTC until the RTC is completed, then outputs data and stops. So the RTC in progress is always completed, even if the profiler is directed to stop during an RTC.
If you set duration to a value of zero or less (<= 0), then profiling continues until the rule sessions end or profiler is explicitly turned of using a function or Hawk method.
When be.engine.profile.BAR_Name.duration and be.engine.profile.*.duration are both present, the duration specified in be.engine.profile.BAR_Name.duration takes precedence.
be.engine.profile.BAR_Name.level
When be.engine.profile.BAR_Name.level and be.engine.profile.*.level are both present, the duration specified in be.engine.profile.BAR_Name.level takes precedence.
To Turn Profiler On and Off Using Functions
This section assumes you understand how to use BusinessEvents functions. It tells you which functions to use and the effect of each function.
You can turn the profiler on using the engine properties, and turn it off using a function or Hawk method, as desired. See notes for be.engine.BAR_Name.profile.duration and be.engine.*.profile.duration in Table 17, Profiler Configuration Properties (Sheet 1 of 3).
To turn the profiler on  In your rule or rule function, use the following function to turn on the profiler:

 
Engine.Profiler.startCollectingToFile(String fileName, int level, long duration)

 
The above function turns on the BusinessEvents Profiler and starts collecting data for the specified duration for the rule session (inference agent) in which the rule or rule function that calls this function is executed. The profiler starts collecting data at the beginning of next RTC.
Profile data is output to the specified file in comma-separated value format at the end of the duration period, unless the profiler is turned off before the end of the duration, in which case it is output at the end of the RTC that completes after the profiler is turned off.
Input arguments are the same as the engine properties show in Table 17, Profiler Configuration Properties (Sheet 1 of 3):
String fileName: See be.engine.profile.BAR_Name.file
int level: See be.engine.profile.BAR_Name.level
long duration: See be.engine.profile.BAR_Name.duration (Here BAR_Name is the current rule session in which the rule or rule function that calls this function is executed.)
To turn the profiler off  In your rule or rule function, use the following function to turn off the profiler:

 
Engine.Profiler.stopCollecting()

 
The above function turns off the BusinessEvents profiler and writes the profile data to a file for the rule session in which the rule or rule function that calls this function is included (the file is output at the end of the RTC that completes after the profiler is turned off). There is no effect if the profiler is not on.
To Turn Profiler On and Off Using TIBCO Hawk Methods
This section assumes you understand how to use TIBCO Hawk methods. It tells you which methods to use and the effect of each method
Before you Begin  Ensure that the property hawk.enabled is set to true in be-engine.tra or your deployed application TRA file before the BusinessEvents engine starts.
To turn the profiler on  Use the following method to turn on the profiler:

 
StartFileBasedProfiler(String session, String fileName, int level, long duration)

 
The above method turns on the BusinessEvents profiler for the specified rule session (inference agent). The profiler starts collecting data at the beginning of next RTC for the specified duration.
This method works the same way as the Engine.Profiler.startCollectingToFile() function (see To Turn Profiler On and Off Using Functions), except that it requires you to specify a rule session (inference agent).
Input arguments are the same as the engine properties shown in Table 17, Profiler Configuration Properties (Sheet 1 of 3):
String session: If you want to monitor multiple rule sessions (inference agents) execute the method once for each, specifying the BAR file name of the rule session in each case. If there is only one rule session, the session parameter is optional.
String fileName: See be.engine.profile.BAR_Name.file
int level: See be.engine.profile.BAR_Name.level
long duration: See be.engine.profile.BAR_Name.duration
If you attempt to turn on the profiler when it is already running, an error is returned, but the running profiler is not affected.
To turn the profiler off  In your rule or rule function, use the following function to turn off the profiler:

 
StopFileBasedProfiler(String session)

 
The above method turns off the BusinessEvents profiler and writes the profile data into a file for the specified rule session when the current RTC has completed. You must execute the method once for each session, as needed.
If you attempt to turn off the profiler when it is already off, an error is returned, but there is no effect on the profiler.