Apama 10.3 | Apama Documentation | Deploying and Managing Apama Applications | Correlator Utilities Reference | Generating code coverage information about EPL files | Recording code coverage information
Recording code coverage information
The recording of code coverage information can be enabled and written (dumped) to disk using management requests, or using an environment variable that automatically writes out a coverage file when the correlator is shut down or when code is deleted from the correlator.
The epl_coverage tool can then be used to merge together the coverage files that have been produced by the correlator and produce summary statistics about how much of each source file is covered, as well as an HTML report where each source line is shown annotated with different colors to indicate which lines are not being covered. For detailed information, see Creating code coverage reports.
Enabling the code coverage feature will disable the compiled runtime, and it will also enable the debugger (Using the command-line debugger ) and CPU profiler (see Using the CPU profiler).
Dumping code coverage information using management requests
One way to enable and dump code coverage information is via the -r codeCoverage option of the engine_management tool (see also Shutting down and managing components). You can send the following requests:
codeCoverage on
Enables the recording of code coverage information. This also disables optimizations for any subsequently injected files, disables use of the compiled runtime and enables the EPL debugger. Code coverage must be enabled before injecting EPL to record code coverage information. EPL injected before code coverage is enabled will be omitted from the coverage report (unless using the environment variable as described below).
Note: This option is not suitable for production use.
codeCoverage off
Disables the recording of code coverage information. This also removes any in-memory coverage information stored so far, but does not reset any features changed by codeCoverage on such as optimizations and possibly the compiled runtime.
codeCoverage dump [filename]
Returns the code coverage information either for all EPL files in the correlator or just for the (optional) source EPL filename provided. The output format is suitable for input to the epl_coverage tool, and is encoded as a UTF-8 string.
Automatically writing code coverage information using an environment variable
It is also possible to start the correlator in a mode where it automatically writes code coverage information to disk when it is shut down or is given an engine_delete --all request (see also Deleting code from a correlator).
This mode is enabled by setting the AP_EPL_COVERAGE_FILE environment variable to the path of a file to which coverage information is to be written. If you do this, the correlator starts in code coverage collection mode with debugging enabled, the compiled runtime disabled and optimizations disabled. On shutdown, it writes the code coverage information to the path specified in the environment variable.
The environment variable can contain replacement tokens in the same format as the correlator log file (see Specifying log filenames). Given that the coverage file is not subject to log rotation, only the ${PID} and ${START_TIME} tags are appropriate.
Example (for Windows):
set AP_EPL_COVERAGE_FILE=c:\mypath\mycorrelator.${PID}.eplcoverage
start correlator
(run application, etc.)
engine_management --shutdown "Clean correlator shutdown from command line"
Of course, the correlator must be cleanly shut down for this to work, as no coverage information is written if the process is terminated without warning. If a dump is triggered by engine_delete --all and more EPL is then injected before the correlator is shut down, all coverage information written by engine_delete is overwritten by later coverage information and is thus lost. However, if engine_delete is immediately followed by a clean shutdown, there will be no new coverage information when the shutdown occurs. Therefore, the file will not be overwritten.
Code coverage and deletion of monitors
If you delete an event or monitor, or if the monitor has died or was transient, then this will remove all coverage information associated with that monitor or event, and nothing will be returned by a codeCoverage dump request or written to disk automatically on shutdown. You must dump coverage information before the associated code is deleted from the correlator (except when using engine_delete --all with the AP_EPL_COVERAGE_FILE environment variable, which is a special case that triggers an automatic dump to prevent the information being lost).
Common usage patterns
*Enable code coverage, inject your application and send typical events into the correlator. Then dump a coverage report. This gives you a complete list of code covered by initialization and events being processed in the system.
*Set the AP_EPL_COVERAGE_FILE environment variable before running your test suite. Then collate all the coverage reports. This lets you check that your tests exercise all the code paths.
*Enable code coverage and inject your application. Then disable and enable code coverage (to clear the reporting data). Then send a single event through and dump a coverage report. This lets you see what code is run by a single event.

Copyright © 2013-2018 | Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors.