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

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:

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):

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.

The code coverage information for transient monitors, monitors which have died, and monitors which were deleted by name is retained. This enables you to later call codeCoverage dump to get the coverage information.

An engine_delete --all, however, resets all the coverage information. When you set the AP_EPL_COVERAGE_FILE environment variable, the coverage information is automatically dumped during an engine_delete --all.

If you delete a monitor and then reinject the EPL file, then all coverage information for that EPL file is reset for the newly injected file.