view release on metacpan or  search on metacpan

DBI.pm  view on Meta::CPAN

=head1 TRACING

The DBI has a powerful tracing mechanism built in. It enables you
to see what's going on 'behind the scenes', both within the DBI and
the drivers you're using.

=head2 Trace Settings

Which details are written to the trace output is controlled by a
combination of a I<trace level>, an integer from 0 to 15, and a set
of I<trace flags> that are either on or off. Together these are known
as the I<trace settings> and are stored together in a single integer.
For normal use you only need to set the trace level, and generally
only to a value between 1 and 4.

Each handle has its own trace settings, and so does the DBI.
When you call a method the DBI merges the handles settings into its
own for the duration of the call: the trace flags of the handle are
OR'd into the trace flags of the DBI, and if the handle has a higher
trace level then the DBI trace level is raised to match it.
The previous DBI trace settings are restored when the called method
returns.

=head2 Trace Levels

Trace I<levels> are as follows:

  0 - Trace disabled.
  1 - Trace top-level DBI method calls returning with results or errors.
  2 - As above, adding tracing of top-level method entry with parameters.
  3 - As above, adding some high-level information from the driver
      and some internal information from the DBI.
  4 - As above, adding more detailed information from the driver.
      This is the first level to trace all the rows being fetched.
  5 to 15 - As above but with more and more internal information.

Trace level 1 is best for a simple overview of what's happening.
Trace levels 2 thru 4 a good choice for general purpose tracing.
Levels 5 and above are best reserved for investigating a specific
problem, when you need to see "inside" the driver and DBI.

The trace output is detailed and typically very useful. Much of the
trace output is formatted using the L</neat> function, so strings
in the trace output may be edited and truncated by that function.

=head2 Trace Flags

Trace I<flags> are used to enable tracing of specific activities
within the DBI and drivers. The DBI defines some trace flags and
drivers can define others. DBI trace flag names begin with a capital
letter and driver specific names begin with a lowercase letter, as
usual.

Currently the DBI defines these trace flags:

  ALL - turn on all DBI and driver flags (not recommended)
  SQL - trace SQL statements executed
        (not yet implemented in DBI but implemented in some DBDs)
  CON - trace connection process
  ENC - trace encoding (unicode translations etc)
        (not yet implemented in DBI but implemented in some DBDs)
  DBD - trace only DBD messages
        (not implemented by all DBDs yet)
  TXN - trace transactions
        (not implemented in all DBDs yet)

The L</parse_trace_flags> and L</parse_trace_flag> methods are used
to convert trace flag names into the corresponding integer bit flags.

=head2 Enabling Trace

The C<$h-E<gt>trace> method sets the trace settings for a handle
and C<DBI-E<gt>trace> does the same for the DBI.

In addition to the L</trace> method, you can enable the same trace
information, and direct the output to a file, by setting the
C<DBI_TRACE> environment variable before starting Perl.
See L</DBI_TRACE> for more information.

Finally, you can set, or get, the trace settings for a handle using
the C<TraceLevel> attribute.

All of those methods use parse_trace_flags() and so allow you set
both the trace level and multiple trace flags by using a string
containing the trace level and/or flag names separated by vertical
bar ("C<|>") or comma ("C<,>") characters. For example:

  local $h->{TraceLevel} = "3|SQL|foo";

=head2 Trace Output

Initially trace output is written to C<STDERR>.  Both the
C<$h-E<gt>trace> and C<DBI-E<gt>trace> methods take an optional
$trace_file parameter, which may be either the name of a file to be
opened by DBI in append mode, or a reference to an existing writable
(possibly layered) filehandle. If $trace_file is a filename,
and can be opened in append mode, or $trace_file is a writable
filehandle, then I<all> trace output (currently including that from
other handles) is redirected to that file. A warning is generated
if $trace_file can't be opened or is not writable.

Further calls to trace() without $trace_file do not alter where
the trace output is sent. If $trace_file is undefined, then
trace output is sent to C<STDERR> and, if the prior trace was opened with
$trace_file as a filename, the previous trace file is closed; if $trace_file was
a filehandle, the filehandle is B<not> closed.

B<NOTE>: If $trace_file is specified as a filehandle, the filehandle
should not be closed until all DBI operations are completed, or the
application has reset the trace file via another call to
C<trace()> that changes the trace file.

=head2 Tracing to Layered Filehandles

B<NOTE>:

=over 4

=item *
Tied filehandles are not currently supported, as