Name
prof_enable — Control Virtuoso profiling
Synopsis
prof_enable
(
|
in flag integer , |
in
comp_stat
integer default 0
); |
Description
prof_enable is used to enable or disable profiling of
execution times, SQL statements and web requests. When called with
flag = 1, profiling begins — times of statement
executions that start and end while profiling is on are accumulated.
When called with flag = 0, accumulation stops. The
legacy behavior writes results to a file named
virtprof.out in the server's working directory. For
more detail on the file format, see SQL
Execution Profiling in the Performance
Tuning section of the Virtuoso documentation.
The optional second argument comp_stat (default
0) controls whether compilation timings are also
captured. Pass 1 to include them.
Coverage Mode and the cov_store Pipeline
In addition to the legacy flat-text virtprof.out,
Virtuoso provides a structured coverage pipeline offering per-line
execution counts, per-caller statistics and optional source code
excerpts. This is controlled by the
cov_store /
cov_report
functions and requires an INI parameter. See also
Branch Coverage.
Configuration (virtuoso.ini)
Two parameters in the [Parameters] section govern the
coverage pipeline:
[Parameters]
TestCoverage = /path/to/dump-file.xml
DirsAllowed = ., /path/to/, ...
-
TestCoverage -
File path for the coverage XML dump. Setting this enables the coverage bit (
pl_debug_all & 2) which activates per-line execution counting. -
DirsAllowed -
Directories where file writes are permitted. The path passed to
cov_storemust reside under one of these directories, otherwise error FA023 is raised: “Current Virtuoso configuration does not allow write access to given filesystem path. Please see documentation for DirsAllowed directive in virtuoso ini file.”
If TestCoverage is set,
cov_store() is called automatically at server
shutdown, writing the accumulated profile to the configured file — no
manual dump call is needed for the shutdown snapshot.
Coverage Pipeline Functions
cov_store —
Write XML Profile Dump
cov_store(in f varchar, in add_line integer := 0);
Writes an XML <pl_stats> document containing
per-procedure/per-method:
-
@name— procedure name -
@calls— invocation count -
@time— cumulative time (msec) -
@self— self time (msec) -
@file— source file path -
Per-line
<line no="..." ctr="..."/>hit counters -
Per-caller
<caller name="..." ct="..."/>call counts
When add_line = 1, each
<line> element includes the actual source code
in a CDATA section, making the report self-contained.
Important: The file path must be within a
DirsAllowed directory.
cov_load —
Reload a Profile Dump
cov_load(in f varchar);
Reads a cov_store XML file back into the PL debug
statistics tables for further analysis.
cov_report —
Generate Per-File Reports
cov_report(in f varchar, in odir varchar);
Reads the cov_store XML and generates:
-
{filename}.cov -
Per-file coverage report (via
cov_report.xsl) -
profile.prof -
Flat-profile summary by cumulative time and self time (via
cov_time.xsl)
The output directory is created if it does not exist.
Parameters
flag
An INTEGER. Valid values are 1 (start)
or 0 (stop).
comp_stat
An optional INTEGER, default 0. When
1, compilation timing information is captured in
addition to execution timings.
Return Types
None.
Examples
Example 24.271. Simple profiling with cov_store
SQL> prof_enable(1, 1);
SQL> -- ... run workload ...
SQL> cov_store('/tmp/virtuoso-profile.xml', 1);
SQL> prof_enable(0);
SQL> cov_report('/tmp/virtuoso-profile.xml', '/tmp/reports/');
This produces an XML dump with source excerpts in
/tmp/virtuoso-profile.xml and generates per-file
.cov reports and a
profile.prof flat summary in
/tmp/reports/.
Example 24.272. Legacy flat-text prof_enable
Enabling profiling and writing the legacy
virtprof.out file:
SQL> prof_enable(1);
SQL> -- ... run workload ...
SQL> prof_enable(0);
Checking Profiling State
-
sys_stat('prof_on') -
Returns
1if profiling is active,0otherwise -
sys_stat('prof_start_time') -
Timestamp (msec) when profiling was started