Taking trace () to the next level ...

I've had a series of discussions with several DBD authors and others
because I wanted to get better support for Driver-side trace message
handling in a portable way.

My DBD::Unify supports $dbh->{dbd_verbose} since a *long* time, and Tim
never saw the generic value of that, but now that John Scoles has used
it for himself in DBD::Oracle and others showed interest too, it might
be well worth to take the discussion to a wider board.

Here's a summary, '»' marked lines are proposed additions/changes. I
hope I interpreted all opinions correctly.

DBI

	$h->trace ($trace_setting [, $output ]);

   $h may be 'DBI'

   $trace_setting is a (combined) flag, which supports

	1..15	Simple debug level
	"SQL"	All SQL statements executed (not yet implemented)
	"ALL"	All DBI *and* Driver flags
»	"DBD"	All Driver flags

»	   $h->trace ("DBD=7") could be an alternative to set the level

	"1|pglib"	Combinations of a DBI debug level and driver
			flags, which have to be parsed by
			parse_trace_flags ()
»	"1|4"		Combination of a DBI debug level and a
			driver debug level
»	"|4"		Driver-side only debug level, will NOT
			alter the current DBI debug level

	$trace_setting can be stored in $ENV{DBI_TRACE}
»	Driver side $trace_settings can be stored in $ENV{DBD_TRACE}
	(note that this /was/ DBD_VERBOSE in previous discussions, but
	DBD_TRACE is more in line with the above)

	#define DBIc_TRACE_LEVEL_MASK   0x0000000F
	#define DBIc_TRACE_FLAGS_MASK   0xFFFFFF00

	Is 0x00000000F0 supposed to be the Driver *level* mask?

   $output can be a filename or an output handle. The latter is very
   nice in combination with perlIO

	my $trace = "";
	open my $th, ">", \$trace;
	$dbh->trace (4, $th);
	...
	$dbh->trace (0);
	# Trace log now in $trace;

   Handles can get there own (inherited) $trace_setting using the

	$h->{TraceLevel}  = "2|14";
»	$h->{dbd_verbose} = 4;

»  the dbd_verbose attribute is internally implemented as uni_verbose,
»  pg_verbose, ora_verbose, ... but offers a generic alias to
»  dbd_verbose, so that writing cross-database portable scripts will be
»  much easier.

There is no policy regarding DBD tracing. DBD::Unify uses a trace
*level*, which is by default inherited from dbis->debug (XS), but
DBD::Pg uses flags

DBI - Uses trace *level* (flags SQL or ALL set all)
  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.

DBD::Unify - Uses trace *level*
  0 - Trace disabled
  1 - No messages defined (yet)
  2 - Level 1 plus main method entry and exit points:
  3 - Level 2 plus errors and additional return codes and field types
      and values:
  4 - Level 3 plus some content info:
  5 - Level 4 plus internal coding for exchanges and low(er) level
      return codes:
  6 - Level 5 plus destroy/cleanup states:
  7 - No messages (yet) set to level 7 and up.

DBD::Oracle - Uses trace *level*
  Uses level 1..6, but does not document what the output is

DBD::Pg - uses trace *flags* AND *level* from DBI. Level 4 or higher
	  sets all flags
  pglibpq	- Outputs the name of each libpq function (without
		  arguments) immediately before running it.
  pgstart	- Outputs the name of each internal DBD::Pg function,
		  and other information such as the function arguments
		  or important global variables, as each function starts
  pgend		- Outputs a simple message at the very end of
		  each internal DBD::Pg function.
  pgprefix	- Forces each line of trace output to begin with the
		  string "dbdpg: "
  pglogin	- Outputs a message showing the connection string
		  right before a new database connection is attempted
		  (on with level 5 or up)

DBD::MySQL - Cannot find anything in the docs about tracing

DBD::ODBC - Only supports one trace flag
  odbcdev	- flag is used to output development tracing so it
		  should not be relevant in normal use.
  DBD::ODBC outputs tracing at levels 3 and above (as levels 1 and 2
  are reserved for DBI).

Where is it stated that levels 1 and 2 are DBI only?

All of the people I talked to agree that is is often useful to see
Driver-only tracing/debugging, as by now we do trust that DBI is Doing
The Right Thing (TM)

The problem with the current definition of the trace_flags, is that,
even though most drivers still work with a trace *level*, it only
supports trace *flags*. My implementation and suggestion of
$h->{dbd_verbose} is a nice workaround to start with, but it would be
easier to lift it to the trace method, so that Driver-only tracing is
more standardized

http://search.cpan.org/~timb/DBI-1.607/lib/DBI/DBD.pm#Other_database_handle_methods

-- 
H.Merijn Brand          Amsterdam Perl Mongers  http://amsterdam.pm.org/
using & porting perl 5.6.2, 5.8.x, 5.10.x, 5.11.x on HP-UX 10.20, 11.00,
11.11, 11.23, and 11.31, SuSE 10.1, 10.2, and 10.3, AIX 5.2, and Cygwin.
http://mirrors.develooper.com/hpux/           http://www.test-smoke.org/
http://qa.perl.org      http://www.goldmark.org/jeff/stupid-disclaimers/