blib/lib/DBI/Profile.pm

filter: Statementstmt 91.2% 157 / 172 Branchbran 64.7% 57 / 88 Conditioncond 61.2% 19 / 31 MC/DCmcdc 16.6% 3 / 18 Subroutinesub 88.4% 23 / 26 Podpod 27.2% 3 / 11 totaltotal 75.7% 262 / 346 CC 60 SCAR 21.8
CC
60
Cov
80%
flush_to_disk
20.0
_auto_new
16.8
as_text
11.6
CRAP 8.8
« blib/lib/DBI/W32ODBC.pm ↑ Summary blib/lib/DBD/Gofer/Transport/pipeone.pm »
1 package DBI::Profile;
2  
3 =head1 NAME
4  
5 DBI::Profile - Performance profiling and benchmarking for the DBI
6  
7 =head1 SYNOPSIS
8  
9 The easiest way to enable DBI profiling is to set the DBI_PROFILE
10 environment variable to 2 and then run your code as usual:
11  
12 DBI_PROFILE=2 prog.pl
13  
14 This will profile your program and then output a textual summary
15 grouped by query when the program exits. You can also enable profiling by
16 setting the Profile attribute of any DBI handle:
17  
18 $dbh->{Profile} = 2;
19  
20 Then the summary will be printed when the handle is destroyed.
21  
22 Many other values apart from are possible - see L<"ENABLING A PROFILE"> below.
23  
24 =head1 DESCRIPTION
25  
26 The DBI::Profile module provides a simple interface to collect and
27 report performance and benchmarking data from the DBI.
28  
29 For a more elaborate interface, suitable for larger programs, see
30 L<DBI::ProfileDumper|DBI::ProfileDumper> and L<dbiprof|dbiprof>.
31 For Apache/mod_perl applications see
32 L<DBI::ProfileDumper::Apache|DBI::ProfileDumper::Apache>.
33  
34 =head1 OVERVIEW
35  
36 Performance data collection for the DBI is built around several
37 concepts which are important to understand clearly.
38  
39 =over 4
40  
41 =item Method Dispatch
42  
43 Every method call on a DBI handle passes through a single 'dispatch'
44 function which manages all the common aspects of DBI method calls,
45 such as handling the RaiseError attribute.
46  
47 =item Data Collection
48  
49 If profiling is enabled for a handle then the dispatch code takes
50 a high-resolution timestamp soon after it is entered. Then, after
51 calling the appropriate method and just before returning, it takes
52 another high-resolution timestamp and calls a function to record
53 the information. That function is passed the two timestamps
54 plus the DBI handle and the name of the method that was called.
55 That data about a single DBI method call is called a I<profile sample>.
56  
57 =item Data Filtering
58  
59 If the method call was invoked by the DBI or by a driver then the call is
60 ignored for profiling because the time spent will be accounted for by the
61 original 'outermost' call for your code.
62  
63 For example, the calls that the selectrow_arrayref() method makes
64 to prepare() and execute() etc. are not counted individually
65 because the time spent in those methods is going to be allocated
66 to the selectrow_arrayref() method when it returns. If this was not
67 done then it would be very easy to double count time spent inside
68 the DBI.
69  
70 =item Data Storage Tree
71  
72 The profile data is accumulated as 'leaves on a tree'. The 'path' through the
73 branches of the tree to a particular leaf is determined dynamically for each sample.
74 This is a key feature of DBI profiling.
75  
76 For each profiled method call the DBI walks along the Path and uses each value
77 in the Path to step into and grow the Data tree.
78  
79 For example, if the Path is
80  
81 [ 'foo', 'bar', 'baz' ]
82  
83 then the new profile sample data will be I<merged> into the tree at
84  
85 $h->{Profile}->{Data}->{foo}->{bar}->{baz}
86  
87 But it's not very useful to merge all the call data into one leaf node (except
88 to get an overall 'time spent inside the DBI' total). It's more common to want
89 the Path to include dynamic values such as the current statement text and/or
90 the name of the method called to show what the time spent inside the DBI was for.
91  
92 The Path can contain some 'magic cookie' values that are automatically replaced
93 by corresponding dynamic values when they're used. These magic cookies always
94 start with a punctuation character.
95  
96 For example a value of 'C<!MethodName>' in the Path causes the corresponding
97 entry in the Data to be the name of the method that was called.
98 For example, if the Path was:
99  
100 [ 'foo', '!MethodName', 'bar' ]
101  
102 and the selectall_arrayref() method was called, then the profile sample data
103 for that call will be merged into the tree at:
104  
105 $h->{Profile}->{Data}->{foo}->{selectall_arrayref}->{bar}
106  
107 =item Profile Data
108  
109 Profile data is stored at the 'leaves' of the tree as references
110 to an array of numeric values. For example:
111  
112 [
113 106, # 0: count of samples at this node
114 0.0312958955764771, # 1: total duration
115 0.000490069389343262, # 2: first duration
116 0.000176072120666504, # 3: shortest duration
117 0.00140702724456787, # 4: longest duration
118 1023115819.83019, # 5: time of first sample
119 1023115819.86576, # 6: time of last sample
120 ]
121  
122 After the first sample, later samples always update elements 0, 1, and 6, and
123 may update 3 or 4 depending on the duration of the sampled call.
124  
125 =back
126  
127 =head1 ENABLING A PROFILE
128  
129 Profiling is enabled for a handle by assigning to the Profile
130 attribute. For example:
131  
132 $h->{Profile} = DBI::Profile->new();
133  
134 The Profile attribute holds a blessed reference to a hash object
135 that contains the profile data and attributes relating to it.
136  
137 The class the Profile object is blessed into is expected to
138 provide at least a DESTROY method which will dump the profile data
139 to the DBI trace file handle (STDERR by default).
140  
141 All these examples have the same effect as each other:
142  
143 $h->{Profile} = 0;
144 $h->{Profile} = "/DBI::Profile";
145 $h->{Profile} = DBI::Profile->new();
146 $h->{Profile} = {};
147 $h->{Profile} = { Path => [] };
148  
149 Similarly, these examples have the same effect as each other:
150  
151 $h->{Profile} = 6;
152 $h->{Profile} = "6/DBI::Profile";
153 $h->{Profile} = "!Statement:!MethodName/DBI::Profile";
154 $h->{Profile} = { Path => [ '!Statement', '!MethodName' ] };
155  
156 If a non-blessed hash reference is given then the DBI::Profile
157 module is automatically C<require>'d and the reference is blessed
158 into that class.
159  
160 If a string is given then it is processed like this:
161  
162 ($path, $module, $args) = split /\//, $string, 3
163  
164 @path = split /:/, $path
165 @args = split /:/, $args
166  
167 eval "require $module" if $module
168 $module ||= "DBI::Profile"
169  
170 $module->new( Path => \@Path, @args )
171  
172 So the first value is used to select the Path to be used (see below).
173 The second value, if present, is used as the name of a module which
174 will be loaded and it's C<new> method called. If not present it
175 defaults to DBI::Profile. Any other values are passed as arguments
176 to the C<new> method. For example: "C<2/DBIx::OtherProfile/Foo:42>".
177  
178 Numbers can be used as a shorthand way to enable common Path values.
179 The simplest way to explain how the values are interpreted is to show the code:
180  
181 push @Path, "DBI" if $path_elem & 0x01;
182 push @Path, "!Statement" if $path_elem & 0x02;
183 push @Path, "!MethodName" if $path_elem & 0x04;
184 push @Path, "!MethodClass" if $path_elem & 0x08;
185 push @Path, "!Caller2" if $path_elem & 0x10;
186  
187 So "2" is the same as "!Statement" and "6" (2+4) is the same as
188 "!Statement:!Method". Those are the two most commonly used values. Using a
189 negative number will reverse the path. Thus "-6" will group by method name then
190 statement.
191  
192 The splitting and parsing of string values assigned to the Profile
193 attribute may seem a little odd, but there's a good reason for it.
194 Remember that attributes can be embedded in the Data Source Name
195 string which can be passed in to a script as a parameter. For
196 example:
197  
198 dbi:DriverName(Profile=>2):dbname
199 dbi:DriverName(Profile=>{Username}:!Statement/MyProfiler/Foo:42):dbname
200  
201 And also, if the C<DBI_PROFILE> environment variable is set then
202 The DBI arranges for every driver handle to share the same profile
203 object. When perl exits a single profile summary will be generated
204 that reflects (as nearly as practical) the total use of the DBI by
205 the application.
206  
207  
208 =head1 THE PROFILE OBJECT
209  
210 The DBI core expects the Profile attribute value to be a hash
211 reference and if the following values don't exist it will create
212 them as needed:
213  
214 =head2 Data
215  
216 A reference to a hash containing the collected profile data.
217  
218 =head2 Path
219  
220 The Path value is a reference to an array. Each element controls the
221 value to use at the corresponding level of the profile Data tree.
222  
223 If the value of Path is anything other than an array reference,
224 it is treated as if it was:
225  
226 [ '!Statement' ]
227  
228 The elements of Path array can be one of the following types:
229  
230 =head3 Special Constant
231  
232 B<!Statement>
233  
234 Use the current Statement text. Typically that's the value of the Statement
235 attribute for the handle the method was called with. Some methods, like
236 commit() and rollback(), are unrelated to a particular statement. For those
237 methods !Statement records an empty string.
238  
239 For statement handles this is always simply the string that was
240 given to prepare() when the handle was created. For database handles
241 this is the statement that was last prepared or executed on that
242 database handle. That can lead to a little 'fuzziness' because, for
243 example, calls to the quote() method to build a new statement will
244 typically be associated with the previous statement. In practice
245 this isn't a significant issue and the dynamic Path mechanism can
246 be used to setup your own rules.
247  
248 B<!MethodName>
249  
250 Use the name of the DBI method that the profile sample relates to.
251  
252 B<!MethodClass>
253  
254 Use the fully qualified name of the DBI method, including
255 the package, that the profile sample relates to. This shows you
256 where the method was implemented. For example:
257  
258 'DBD::_::db::selectrow_arrayref' =>
259 0.022902s
260 'DBD::mysql::db::selectrow_arrayref' =>
261 2.244521s / 99 = 0.022445s avg (first 0.022813s, min 0.022051s, max 0.028932s)
262  
263 The "DBD::_::db::selectrow_arrayref" shows that the driver has
264 inherited the selectrow_arrayref method provided by the DBI.
265  
266 But you'll note that there is only one call to
267 DBD::_::db::selectrow_arrayref but another 99 to
268 DBD::mysql::db::selectrow_arrayref. Currently the first
269 call doesn't record the true location. That may change.
270  
271 B<!Caller>
272  
273 Use a string showing the filename and line number of the code calling the method.
274  
275 B<!Caller2>
276  
277 Use a string showing the filename and line number of the code calling the
278 method, as for !Caller, but also include filename and line number of the code
279 that called that. Calls from DBI:: and DBD:: packages are skipped.
280  
281 B<!File>
282  
283 Same as !Caller above except that only the filename is included, not the line number.
284  
285 B<!File2>
286  
287 Same as !Caller2 above except that only the filenames are included, not the line number.
288  
289 B<!Time>
290  
291 Use the current value of time(). Rarely used. See the more useful C<!Time~N> below.
292  
293 B<!Time~N>
294  
295 Where C<N> is an integer. Use the current value of time() but with reduced precision.
296 The value used is determined in this way:
297  
298 int( time() / N ) * N
299  
300 This is a useful way to segregate a profile into time slots. For example:
301  
302 [ '!Time~60', '!Statement' ]
303  
304 =head3 Code Reference
305  
306 The subroutine is passed the handle it was called on and the DBI method name.
307 The current Statement is in $_. The statement string should not be modified,
308 so most subs start with C<local $_ = $_;>.
309  
310 The list of values it returns is used at that point in the Profile Path.
311 Any undefined values are treated as the string "C<undef>".
312  
313 The sub can 'veto' (reject) a profile sample by including a reference to undef
314 (C<\undef>) in the returned list. That can be useful when you want to only profile
315 statements that match a certain pattern, or only profile certain methods.
316  
317 =head3 Subroutine Specifier
318  
319 A Path element that begins with 'C<&>' is treated as the name of a subroutine
320 in the DBI::ProfileSubs namespace and replaced with the corresponding code reference.
321  
322 Currently this only works when the Path is specified by the C<DBI_PROFILE>
323 environment variable.
324  
325 Also, currently, the only subroutine in the DBI::ProfileSubs namespace is
326 C<'&norm_std_n3'>. That's a very handy subroutine when profiling code that
327 doesn't use placeholders. See L<DBI::ProfileSubs> for more information.
328  
329 =head3 Attribute Specifier
330  
331 A string enclosed in braces, such as 'C<{Username}>', specifies that the current
332 value of the corresponding database handle attribute should be used at that
333 point in the Path.
334  
335 =head3 Reference to a Scalar
336  
337 Specifies that the current value of the referenced scalar be used at that point
338 in the Path. This provides an efficient way to get 'contextual' values into
339 your profile.
340  
341 =head3 Other Values
342  
343 Any other values are stringified and used literally.
344  
345 (References, and values that begin with punctuation characters are reserved.)
346  
347  
348 =head1 REPORTING
349  
350 =head2 Report Format
351  
352 The current accumulated profile data can be formatted and output using
353  
354 print $h->{Profile}->format;
355  
356 To discard the profile data and start collecting fresh data
357 you can do:
358  
359 $h->{Profile}->{Data} = undef;
360  
361  
362 The default results format looks like this:
363  
364 DBI::Profile: 0.001015s 42.7% (5 calls) programname @ YYYY-MM-DD HH:MM:SS
365 '' =>
366 0.000024s / 2 = 0.000012s avg (first 0.000015s, min 0.000009s, max 0.000015s)
367 'SELECT mode,size,name FROM table' =>
368 0.000991s / 3 = 0.000330s avg (first 0.000678s, min 0.000009s, max 0.000678s)
369  
370 Which shows the total time spent inside the DBI, with a count of
371 the total number of method calls and the name of the script being
372 run, then a formatted version of the profile data tree.
373  
374 If the results are being formatted when the perl process is exiting
375 (which is usually the case when the DBI_PROFILE environment variable
376 is used) then the percentage of time the process spent inside the
377 DBI is also shown. If the process is not exiting then the percentage is
378 calculated using the time between the first and last call to the DBI.
379  
380 In the example above the paths in the tree are only one level deep and
381 use the Statement text as the value (that's the default behaviour).
382  
383 The merged profile data at the 'leaves' of the tree are presented
384 as total time spent, count, average time spent (which is simply total
385 time divided by the count), then the time spent on the first call,
386 the time spent on the fastest call, and finally the time spent on
387 the slowest call.
388  
389 The 'avg', 'first', 'min' and 'max' times are not particularly
390 useful when the profile data path only contains the statement text.
391 Here's an extract of a more detailed example using both statement
392 text and method name in the path:
393  
394 'SELECT mode,size,name FROM table' =>
395 'FETCH' =>
396 0.000076s
397 'fetchrow_hashref' =>
398 0.036203s / 108 = 0.000335s avg (first 0.000490s, min 0.000152s, max 0.002786s)
399  
400 Here you can see the 'avg', 'first', 'min' and 'max' for the
401 108 calls to fetchrow_hashref() become rather more interesting.
402 Also the data for FETCH just shows a time value because it was only
403 called once.
404  
405 Currently the profile data is output sorted by branch names. That
406 may change in a later version so the leaf nodes are sorted by total
407 time per leaf node.
408  
409  
410 =head2 Report Destination
411  
412 The default method of reporting is for the DESTROY method of the
413 Profile object to format the results and write them using:
414  
415 DBI->trace_msg($results, 0); # see $ON_DESTROY_DUMP below
416  
417 to write them to the DBI trace() filehandle (which defaults to
418 STDERR). To direct the DBI trace filehandle to write to a file
419 without enabling tracing the trace() method can be called with a
420 trace level of 0. For example:
421  
422 DBI->trace(0, $filename);
423  
424 The same effect can be achieved without changing the code by
425 setting the C<DBI_TRACE> environment variable to C<0=filename>.
426  
427 The $DBI::Profile::ON_DESTROY_DUMP variable holds a code ref
428 that's called to perform the output of the formatted results.
429 The default value is:
430  
431 $ON_DESTROY_DUMP = sub { DBI->trace_msg($results, 0) };
432  
433 Apart from making it easy to send the dump elsewhere, it can also
434 be useful as a simple way to disable dumping results.
435  
436 =head1 CHILD HANDLES
437  
438 Child handles inherit a reference to the Profile attribute value
439 of their parent. So if profiling is enabled for a database handle
440 then by default the statement handles created from it all contribute
441 to the same merged profile data tree.
442  
443  
444 =head1 PROFILE OBJECT METHODS
445  
446 =head2 format
447  
448 See L</REPORTING>.
449  
450 =head2 as_node_path_list
451  
452 @ary = $dbh->{Profile}->as_node_path_list();
453 @ary = $dbh->{Profile}->as_node_path_list($node, $path);
454  
455 Returns the collected data ($dbh->{Profile}{Data}) restructured into a list of
456 array refs, one for each leaf node in the Data tree. This 'flat' structure is
457 often much simpler for applications to work with.
458  
459 The first element of each array ref is a reference to the leaf node.
460 The remaining elements are the 'path' through the data tree to that node.
461  
462 For example, given a data tree like this:
463  
464 {key1a}{key2a}[node1]
465 {key1a}{key2b}[node2]
466 {key1b}{key2a}{key3a}[node3]
467  
468 The as_node_path_list() method will return this list:
469  
470 [ [node1], 'key1a', 'key2a' ]
471 [ [node2], 'key1a', 'key2b' ]
472 [ [node3], 'key1b', 'key2a', 'key3a' ]
473  
474 The nodes are ordered by key, depth-first.
475  
476 The $node argument can be used to focus on a sub-tree.
477 If not specified it defaults to $dbh->{Profile}{Data}.
478  
479 The $path argument can be used to specify a list of path elements that will be
480 added to each element of the returned list. If not specified it defaults to a
481 ref to an empty array.
482  
483 =head2 as_text
484  
485 @txt = $dbh->{Profile}->as_text();
486 $txt = $dbh->{Profile}->as_text({
487 node => undef,
488 path => [],
489 separator => " > ",
490 format => '%1$s: %11$fs / %10$d = %2$fs avg (first %12$fs, min %13$fs, max %14$fs)'."\n";
491 sortsub => sub { ... },
492 );
493  
494 Returns the collected data ($dbh->{Profile}{Data}) reformatted into a list of formatted strings.
495 In scalar context the list is returned as a single concatenated string.
496  
497 A hashref can be used to pass in arguments, the default values are shown in the example above.
498  
499 The C<node> and <path> arguments are passed to as_node_path_list().
500  
501 The C<separator> argument is used to join the elements of the path for each leaf node.
502  
503 The C<sortsub> argument is used to pass in a ref to a sub that will order the list.
504 The subroutine will be passed a reference to the array returned by
505 as_node_path_list() and should sort the contents of the array in place.
506 The return value from the sub is ignored. For example, to sort the nodes by the
507 second level key you could use:
508  
509 sortsub => sub { my $ary=shift; @$ary = sort { $a->[2] cmp $b->[2] } @$ary }
510  
511 The C<format> argument is a C<sprintf> format string that specifies the format
512 to use for each leaf node. It uses the explicit format parameter index
513 mechanism to specify which of the arguments should appear where in the string.
514 The arguments to sprintf are:
515  
516 1: path to node, joined with the separator
517 2: average duration (total duration/count)
518 (3 thru 9 are currently unused)
519 10: count
520 11: total duration
521 12: first duration
522 13: smallest duration
523 14: largest duration
524 15: time of first call
525 16: time of first call
526  
527 =head1 CUSTOM DATA MANIPULATION
528  
529 Recall that C<< $h->{Profile}->{Data} >> is a reference to the collected data.
530 Either to a 'leaf' array (when the Path is empty, i.e., DBI_PROFILE env var is 1),
531 or a reference to hash containing values that are either further hash
532 references or leaf array references.
533  
534 Sometimes it's useful to be able to summarise some or all of the collected data.
535 The dbi_profile_merge_nodes() function can be used to merge leaf node values.
536  
537 =head2 dbi_profile_merge_nodes
538  
539 use DBI qw(dbi_profile_merge_nodes);
540  
541 $time_in_dbi = dbi_profile_merge_nodes(my $totals=[], @$leaves);
542  
543 Merges profile data node. Given a reference to a destination array, and zero or
544 more references to profile data, merges the profile data into the destination array.
545 For example:
546  
547 $time_in_dbi = dbi_profile_merge_nodes(
548 my $totals=[],
549 [ 10, 0.51, 0.11, 0.01, 0.22, 1023110000, 1023110010 ],
550 [ 15, 0.42, 0.12, 0.02, 0.23, 1023110005, 1023110009 ],
551 );
552  
553 $totals will then contain
554  
555 [ 25, 0.93, 0.11, 0.01, 0.23, 1023110000, 1023110010 ]
556  
557 and $time_in_dbi will be 0.93;
558  
559 The second argument need not be just leaf nodes. If given a reference to a hash
560 then the hash is recursively searched for leaf nodes and all those found
561 are merged.
562  
563 For example, to get the time spent 'inside' the DBI during an http request,
564 your logging code run at the end of the request (i.e. mod_perl LogHandler)
565 could use:
566  
567 my $time_in_dbi = 0;
568 if (my $Profile = $dbh->{Profile}) { # if DBI profiling is enabled
569 $time_in_dbi = dbi_profile_merge_nodes(my $total=[], $Profile->{Data});
570 $Profile->{Data} = {}; # reset the profile data
571 }
572  
573 If profiling has been enabled then $time_in_dbi will hold the time spent inside
574 the DBI for that handle (and any other handles that share the same profile data)
575 since the last request.
576  
577 Prior to DBI 1.56 the dbi_profile_merge_nodes() function was called dbi_profile_merge().
578 That name still exists as an alias.
579  
580 =head1 CUSTOM DATA COLLECTION
581  
582 =head2 Using The Path Attribute
583  
584 XXX example to be added later using a selectall_arrayref call
585 XXX nested inside a fetch loop where the first column of the
586 XXX outer loop is bound to the profile Path using
587 XXX bind_column(1, \${ $dbh->{Profile}->{Path}->[0] })
588 XXX so you end up with separate profiles for each loop
589 XXX (patches welcome to add this to the docs :)
590  
591 =head2 Adding Your Own Samples
592  
593 The dbi_profile() function can be used to add extra sample data
594 into the profile data tree. For example:
595  
596 use DBI;
597 use DBI::Profile (dbi_profile dbi_time);
598  
599 my $t1 = dbi_time(); # floating point high-resolution time
600  
601 ... execute code you want to profile here ...
602  
603 my $t2 = dbi_time();
604 dbi_profile($h, $statement, $method, $t1, $t2);
605  
606 The $h parameter is the handle the extra profile sample should be
607 associated with. The $statement parameter is the string to use where
608 the Path specifies !Statement. If $statement is undef
609 then $h->{Statement} will be used. Similarly $method is the string
610 to use if the Path specifies !MethodName. There is no
611 default value for $method.
612  
613 The $h->{Profile}{Path} attribute is processed by dbi_profile() in
614 the usual way.
615  
616 The $h parameter is usually a DBI handle but it can also be a reference to a
617 hash, in which case the dbi_profile() acts on each defined value in the hash.
618 This is an efficient way to update multiple profiles with a single sample,
619 and is used by the L<DashProfiler> module.
620  
621 =head1 SUBCLASSING
622  
623 Alternate profile modules must subclass DBI::Profile to help ensure
624 they work with future versions of the DBI.
625  
626  
627 =head1 CAVEATS
628  
629 Applications which generate many different statement strings
630 (typically because they don't use placeholders) and profile with
631 !Statement in the Path (the default) will consume memory
632 in the Profile Data structure for each statement. Use a code ref
633 in the Path to return an edited (simplified) form of the statement.
634  
635 If a method throws an exception itself (not via RaiseError) then
636 it won't be counted in the profile.
637  
638 If a HandleError subroutine throws an exception (rather than returning
639 0 and letting RaiseError do it) then the method call won't be counted
640 in the profile.
641  
642 Time spent in DESTROY is added to the profile of the parent handle.
643  
644 Time spent in DBI->*() methods is not counted. The time spent in
645 the driver connect method, $drh->connect(), when it's called by
646 DBI->connect is counted if the DBI_PROFILE environment variable is set.
647  
648 Time spent fetching tied variables, $DBI::errstr, is counted.
649  
650 Time spent in FETCH for $h->{Profile} is not counted, so getting the profile
651 data doesn't alter it.
652  
653 DBI::PurePerl does not support profiling (though it could in theory).
654  
655 For asynchronous queries, time spent while the query is running on the
656 backend is not counted.
657  
658 A few platforms don't support the gettimeofday() high resolution
659 time function used by the DBI (and available via the dbi_time() function).
660 In which case you'll get integer resolution time which is mostly useless.
661  
662 On Windows platforms the dbi_time() function is limited to millisecond
663 resolution. Which isn't sufficiently fine for our needs, but still
664 much better than integer resolution. This limited resolution means
665 that fast method calls will often register as taking 0 time. And
666 timings in general will have much more 'jitter' depending on where
667 within the 'current millisecond' the start and end timing was taken.
668  
669 This documentation could be more clear. Probably needs to be reordered
670 to start with several examples and build from there. Trying to
671 explain the concepts first seems painful and to lead to just as
672 many forward references. (Patches welcome!)
673  
674 =cut
675  
676  
677 14 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
678 14 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
679 14 ▶use Exporter ();
Subroutine BEGIN: called CC=1 SCAR=0.0
680 14 ▶use UNIVERSAL ();
Subroutine BEGIN: called CC=1 SCAR=0.0
681 14 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
682 14 ▶use Module::Load ();
Subroutine BEGIN: called CC=1 SCAR=0.0
683  
684 14 ▶use DBI qw(dbi_time dbi_profile dbi_profile_merge_nodes dbi_profile_merge);
Subroutine BEGIN: called CC=1 SCAR=0.0
685  
686 14 our $VERSION = "2.015065";
687  
688 14 our @ISA = qw(Exporter);
689 14 our @EXPORT = qw(
690 DBIprofile_Statement
691 DBIprofile_MethodName
692 DBIprofile_MethodClass
693 dbi_profile
694 dbi_profile_merge_nodes
695 dbi_profile_merge
696 dbi_time
697 );
698 14 our @EXPORT_OK = qw(
699 format_profile_thingy
700 );
701  
702 14 ▶use constant DBIprofile_Statement => '!Statement';
Subroutine BEGIN: called CC=1 SCAR=0.0
703 14 ▶use constant DBIprofile_MethodName => '!MethodName';
Subroutine BEGIN: called CC=1 SCAR=0.0
704 14 ▶use constant DBIprofile_MethodClass => '!MethodClass';
Subroutine BEGIN: called CC=1 SCAR=0.0
705  
706 40 ▶our $ON_DESTROY_DUMP = sub { DBI->trace_msg(shift, 0) };
Subroutine __ANON__: called CC=1 SCAR=0.0
707 0 ▶our $ON_FLUSH_DUMP = sub { DBI->trace_msg(shift, 0) };
Subroutine __ANON__: not called CC=1 SCAR=1.2
708  
709 24 ▶sub new {
Subroutine new: called CC=1 SCAR=0.0
Pod undocumented
710 24 my $class = shift;
711 24 my $profile = { @_ };
712 24 return bless $profile => $class;
713 }
714  
715  
716 28 ▶sub _auto_new {
Subroutine _auto_new: called CC=16 SCAR=28.2
717 28 my $class = shift;
718 28 my ($arg) = @_;
719  
720 # This sub is called by DBI internals when a non-hash-ref is
721 # assigned to the Profile attribute. For example
722 # dbi:mysql(RaiseError=>1,Profile=>!Statement:!MethodName/DBIx::MyProfile/arg1:arg2):dbname
723 # This sub works out what to do and returns a suitable hash ref.
724  
725 28 ▶ $arg =~ s/^DBI::/2\/DBI::/
Branch: 1 branch
BranchTrueFalseTotal
$arg =~ s[^DBI::][2/DBI::] and carp("Automatically changed old-style DBI::Profile specification to $arg") 0 28 28
726 and carp "Automatically changed old-style DBI::Profile specification to $arg";
727  
728 # it's a path/module/k1:v1:k2:v2:... list
729 28 my ($path, $package, $args) = split /\//, $arg, 3;
730 28 ▶ my @args = (defined $args) ? split(/:/, $args, -1) : ();
Branch: 1 branch
BranchTrueFalseTotal
defined $args ? : 6 22 28
731 28 my @Path;
732  
733 28 for my $element (split /:/, $path) {
734 28 ▶ if (DBI::looks_like_number($element)) {
Branch: 2 branches
BranchTrueFalseTotal
if (DBI::looks_like_number($element)) { } 22 6 28
elsif ($element =~ /^&(\w.*)/) { } 2 4 6
735 22 ▶ my $reverse = ($element < 0) ? ($element=-$element, 1) : 0;
Branch: 1 branch
BranchTrueFalseTotal
$element < 0 ? : 0 22 22
736 22 my @p;
737 # a single "DBI" is special-cased in format()
738 22 ▶ push @p, "DBI" if $element & 0x01;
Branch: 1 branch
BranchTrueFalseTotal
if $element & 1 0 22 22
739 22 ▶ push @p, DBIprofile_Statement if $element & 0x02;
Branch: 1 branch
BranchTrueFalseTotal
if $element & 2 18 4 22
740 22 ▶ push @p, DBIprofile_MethodName if $element & 0x04;
Branch: 1 branch
BranchTrueFalseTotal
if $element & 4 12 10 22
741 22 ▶ push @p, DBIprofile_MethodClass if $element & 0x08;
Branch: 1 branch
BranchTrueFalseTotal
if $element & 8 0 22 22
742 22 ▶ push @p, '!Caller2' if $element & 0x10;
Branch: 1 branch
BranchTrueFalseTotal
if $element & 16 2 20 22
743 22 ▶ push @Path, ($reverse ? reverse @p : @p);
Branch: 1 branch
BranchTrueFalseTotal
$reverse ? : 0 22 22
744 }
745 elsif ($element =~ m/^&(\w.*)/) {
746 2 my $name = "DBI::ProfileSubs::$1"; # capture $1 early
747 2 require DBI::ProfileSubs;
748 14 ▶ my $code = do { no strict; *{$name}{CODE} };
Subroutine BEGIN: called CC=1 SCAR=0.0
749 2 ▶ if (defined $code) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $code) { } 2 0 2
750 2 push @Path, $code;
751 }
752 else {
753 0 warn "$name: subroutine not found\n";
754 0 push @Path, $element;
755 }
756 }
757 else {
758 4 push @Path, $element;
759 }
760 }
761  
762 28 eval {
763 28 ▶ Module::Load::load $package if $package; # silently ignores errors
Branch: 1 branch
BranchTrueFalseTotal
if $package 16 12 28
764 };
765 28 ▶ $package ||= $class;
Condition66%2/3
$package ||= $class
l!l&&r!l&&!r
16120
MC/DC0%0/2
$package ||= $class
$package $class
Truth table66%2/3
A ||= B
A= $packageB= $class
ABresult
1X1
011
000
766  
767 28 return $package->new(Path => \@Path, @args);
768 }
769  
770  
771 48 ▶sub empty { # empty out profile data
Subroutine empty: called CC=2 SCAR=7.1
Pod undocumented
772 48 my $self = shift;
773 48 ▶ DBI->trace_msg("profile data discarded\n",0) if $self->{Trace};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"Trace"} 0 48 48
774 48 $self->{Data} = undef;
775 }
776  
777 0 ▶sub filename { # baseclass method, see DBI::ProfileDumper
Subroutine filename: not called CC=1 SCAR=6.9
Pod undocumented
778 0 return undef;
779 }
780  
781 0 ▶sub flush_to_disk { # baseclass method, see DBI::ProfileDumper & DashProfiler::Core
Subroutine flush_to_disk: not called CC=4 SCAR=30.0
Pod undocumented
782 0 my $self = shift;
783 0 ▶ return unless $ON_FLUSH_DUMP;
Branch: 1 branch
BranchTrueFalseTotal
unless $DBI::Profile::ON_FLUSH_DUMP 0 0 0
784 0 ▶ return unless $self->{Data};
Branch: 1 branch
BranchTrueFalseTotal
unless $self->{"Data"} 0 0 0
785 0 my $detail = $self->format();
786 0 ▶ $ON_FLUSH_DUMP->($detail) if $detail;
Branch: 1 branch
BranchTrueFalseTotal
if $detail 0 0 0
787 }
788  
789  
790 84 ▶sub as_node_path_list {
Subroutine as_node_path_list: called CC=6 SCAR=18.1
Pod documented
791 84 my ($self, $node, $path) = @_;
792 # convert the tree into an array of arrays
793 # from
794 # {key1a}{key2a}[node1]
795 # {key1a}{key2b}[node2]
796 # {key1b}{key2a}{key3a}[node3]
797 # to
798 # [ [node1], 'key1a', 'key2a' ]
799 # [ [node2], 'key1a', 'key2b' ]
800 # [ [node3], 'key1b', 'key2a', 'key3a' ]
801  
802 84 ▶ $node ||= $self->{Data} or return;
Branch: 1 branch
BranchTrueFalseTotal
$node ||= $self->{"Data"} or return 84 0 84
Condition66%2/3
$node ||= $self->{"Data"}
l!l&&r!l&&!r
7680
MC/DC0%0/2
$node ||= $self->{"Data"}
$node $self->{"Data"}
Truth table66%2/3
A ||= B
A= $nodeB= $self->{"Data"}
ABresult
1X1
011
000
803 84 ▶ $path ||= [];
Condition100%2/2
$path ||= []
l!l
786
MC/DC100%1/1
$path ||= []
$path
Truth table100%2/2
A
A= $path
Aresult
11
00
804 84 ▶ if (ref $node eq 'HASH') { # recurse
Branch: 1 branch
BranchTrueFalseTotal
if (ref $node eq "HASH") 48 36 84
805 48 $path = [ @$path, undef ];
806 return map {
807 48 $path->[-1] = $_;
808 76 ▶ ($node->{$_}) ? $self->as_node_path_list($node->{$_}, $path) : ()
Branch: 1 branch
BranchTrueFalseTotal
$node->{$_} ? : 76 0 76
809 } sort keys %$node;
810 }
811 36 return [ $node, @$path ];
812 }
813  
814  
815 6 ▶sub as_text {
Subroutine as_text: called CC=11 SCAR=24.6
Pod documented
816 6 my ($self, $args_ref) = @_;
817 6 ▶ my $separator = $args_ref->{separator} || " > ";
Condition100%2/2
$args_ref->{'separator'} || ' > '
l!l
42
MC/DC100%1/1
$args_ref->{'separator'} || ' > '
$args_ref->{'separator'}
Truth table100%2/2
A
A= $args_ref->{'separator'}
Aresult
11
00
818 my $format_path_element = $args_ref->{format_path_element}
819 6 ▶ || "%s"; # or e.g., " key%2$d='%s'"
Condition50%1/2
$args_ref->{'format_path_element'} || '%s'
l!l
06
MC/DC0%0/1
$args_ref->{'format_path_element'} || '%s'
$args_ref->{'format_path_element'}
Truth table50%1/2
A
A= $args_ref->{'format_path_element'}
Aresult
11
00
820 my $format = $args_ref->{format}
821 6 ▶ || '%1$s: %11$fs / %10$d = %2$fs avg (first %12$fs, min %13$fs, max %14$fs)'."\n";
Condition100%2/2
$args_ref->{'format'} || "%1\$s: %11\$fs / %10\$d = %2\$fs avg (first %12\$fs, min %13\$fs, max %14\$fs)\n"
l!l
42
MC/DC100%1/1
$args_ref->{'format'} || "%1\$s: %11\$fs / %10\$d = %2\$fs avg (first %12\$fs, min %13\$fs, max %14\$fs)\n"
$args_ref->{'format'}
Truth table100%2/2
A
A= $args_ref->{'format'}
Aresult
11
00
822  
823 6 my @node_path_list = $self->as_node_path_list(undef, $args_ref->{path});
824  
825 6 ▶ $args_ref->{sortsub}->(\@node_path_list) if $args_ref->{sortsub};
Branch: 1 branch
BranchTrueFalseTotal
if $args_ref->{"sortsub"} 2 4 6
826  
827 6 my $eval = "qr/".quotemeta($separator)."/";
828 6 ▶ my $separator_re = eval($eval) || quotemeta($separator);
Condition33%1/3
eval $eval || quotemeta $separator
l!l&&r!l&&!r
600
MC/DC0%0/2
eval $eval || quotemeta $separator
eval $eval quotemeta $separator
Truth table33%1/3
A || B
A= eval $evalB= quotemeta $separator
ABresult
1X1
011
000
829 #warn "[$eval] = [$separator_re]";
830 6 my @text;
831 6 my @spare_slots = (undef) x 7;
832 6 for my $node_path (@node_path_list) {
833 20 my ($node, @path) = @$node_path;
834 20 my $idx = 0;
835 20 for (@path) {
836 56 s/[\r\n]+/ /g;
837 56 s/$separator_re/ /g;
838 56 ++$idx;
839 56 ▶ if ($format_path_element eq "%s") {
Branch: 1 branch
BranchTrueFalseTotal
if ($format_path_element eq '%s') { } 56 0 56
840 56 $_ = sprintf $format_path_element, $_;
841 } else {
842 0 $_ = sprintf $format_path_element, $_, $idx;
843 }
844 }
845 20 ▶ push @text, sprintf $format,
Branch: 1 branch
BranchTrueFalseTotal
$node->[0] ? : 20 0 20
846 join($separator, @path), # 1=path
847 ($node->[0] ? $node->[1]/$node->[0] : 0), # 2=avg
848 @spare_slots,
849 @$node; # 10=count, 11=dur, 12=first_dur, 13=min, 14=max, 15=first_called, 16=last_called
850 }
851 6 ▶ return @text if wantarray;
Branch: 1 branch
BranchTrueFalseTotal
if wantarray 0 6 6
852 6 return join "", @text;
853 }
854  
855  
856 42 ▶sub format {
Subroutine format: called CC=10 SCAR=23.8
Pod documented
857 42 my $self = shift;
858 42 ▶ my $class = ref($self) || $self;
Condition33%1/3
ref $self || $self
l!l&&r!l&&!r
4200
MC/DC0%0/2
ref $self || $self
ref $self $self
Truth table33%1/3
A || B
A= ref $selfB= $self
ABresult
1X1
011
000
859  
860 42 my $prologue = "$class: ";
861 my $detail = $self->format_profile_thingy(
862 42 $self->{Data}, 0, " ",
863 my $path = [],
864 my $leaves = [],
865 )."\n";
866  
867 42 ▶ if (@$leaves) {
Branch: 1 branch
BranchTrueFalseTotal
if (@$leaves) 40 2 42
868 40 dbi_profile_merge_nodes(my $totals=[], @$leaves);
869 40 my ($count, $time_in_dbi, undef, undef, undef, $t1, $t2) = @$totals;
870 40 (my $progname = $0) =~ s:.*/::;
871 40 ▶ if ($count) {
Branch: 1 branch
BranchTrueFalseTotal
if ($count) 40 0 40
872 40 $prologue .= sprintf "%fs ", $time_in_dbi;
873 40 ▶ my $perl_time = ($DBI::PERL_ENDING) ? time() - $^T : $t2-$t1;
Branch: 1 branch
BranchTrueFalseTotal
$DBI::PERL_ENDING ? : 0 40 40
874 40 ▶ $prologue .= sprintf "%.2f%% ", $time_in_dbi/$perl_time*100 if $perl_time;
Branch: 1 branch
BranchTrueFalseTotal
if $perl_time 23 17 40
875 40 my @lt = localtime(time);
876 40 my $ts = sprintf "%d-%02d-%02d %02d:%02d:%02d",
877 1900+$lt[5], $lt[4]+1, @lt[3,2,1,0];
878 40 $prologue .= sprintf "(%d calls) $progname \@ $ts\n", $count;
879 }
880 40 ▶ if (@$leaves == 1 && ref($self->{Data}) eq 'HASH' && $self->{Data}->{DBI}) {
Branch: 1 branch
BranchTrueFalseTotal
if (@$leaves == 1 and ref $self->{"Data"} eq "HASH" and $self->{"Data"}{"DBI"}) 0 40 40
Condition83%5/6
@$leaves == 1 and ref $self->{"Data"} eq "HASH" and $self->{"Data"}{"DBI"}
!ll&&!rl&&r
29110
@$leaves == 1 and ref $self->{"Data"} eq "HASH"
!ll&&!rl&&r
27211
MC/DC0%0/3
@$leaves == 1 and ref $self->{"Data"} eq "HASH" and $self->{"Data"}{"DBI"}
@$leaves == 1 ref $self->{"Data"} eq "HASH" $self->{"Data"}{"DBI"}
Truth table75%3/4
A and B and C
A= @$leaves == 1B= ref $self->{"Data"} eq "HASH"C= $self->{"Data"}{"DBI"}
ABCresult
0XX0
10X0
1100
1111
881 0 $detail = ""; # hide the "DBI" from DBI_PROFILE=1
882 }
883 }
884 42 ▶ return ($prologue, $detail) if wantarray;
Branch: 1 branch
BranchTrueFalseTotal
if wantarray 0 42 42
885 42 return $prologue.$detail;
886 }
887  
888  
889 108 ▶sub format_profile_leaf {
Subroutine format_profile_leaf: called CC=5 SCAR=16.6
Pod undocumented
890 108 my ($self, $thingy, $depth, $pad, $path, $leaves) = @_;
891 108 ▶ croak "format_profile_leaf called on non-leaf ($thingy)"
Branch: 1 branch
BranchTrueFalseTotal
unless UNIVERSAL::isa($thingy, "ARRAY") 0 108 108
892 unless UNIVERSAL::isa($thingy,'ARRAY');
893  
894 108 ▶ push @$leaves, $thingy if $leaves;
Branch: 1 branch
BranchTrueFalseTotal
if $leaves 108 0 108
895 108 my ($count, $total_time, $first_time, $min, $max, $first_called, $last_called) = @$thingy;
896 108 ▶ return sprintf "%s%fs\n", ($pad x $depth), $total_time
Branch: 1 branch
BranchTrueFalseTotal
if $count <= 1 72 36 108
897 if $count <= 1;
898 36 ▶ return sprintf "%s%fs / %d = %fs avg (first %fs, min %fs, max %fs)\n",
Branch: 1 branch
BranchTrueFalseTotal
$count ? : 36 0 36
899 ($pad x $depth), $total_time, $count, $count ? $total_time/$count : 0,
900 $first_time, $min, $max;
901 }
902  
903  
904 112 ▶sub format_profile_branch {
Subroutine format_profile_branch: called CC=3 SCAR=11.0
Pod undocumented
905 112 my ($self, $thingy, $depth, $pad, $path, $leaves) = @_;
906 112 ▶ croak "format_profile_branch called on non-branch ($thingy)"
Branch: 1 branch
BranchTrueFalseTotal
unless UNIVERSAL::isa($thingy, "HASH") 0 112 112
907 unless UNIVERSAL::isa($thingy,'HASH');
908 112 my @chunk;
909 112 my @keys = sort keys %$thingy;
910 112 ▶ while ( @keys ) {
Branch: 1 branch
BranchTrueFalseTotal
if (@keys) 180 112 292
911 180 my $k = shift @keys;
912 180 my $v = $thingy->{$k};
913 180 push @$path, $k;
914 180 push @chunk, sprintf "%s'%s' =>\n%s",
915 ($pad x $depth), $k,
916 $self->format_profile_thingy($v, $depth+1, $pad, $path, $leaves);
917 180 pop @$path;
918 }
919 112 return join "", @chunk;
920 }
921  
922  
923 222 ▶sub format_profile_thingy {
Subroutine format_profile_thingy: called CC=4 SCAR=14.1
Pod undocumented
924 222 my ($self, $thingy, $depth, $pad, $path, $leaves) = @_;
925 222 ▶ return "undef" if not defined $thingy;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $thingy 2 220 222
926 220 ▶ return $self->format_profile_leaf( $thingy, $depth, $pad, $path, $leaves)
Branch: 1 branch
BranchTrueFalseTotal
if UNIVERSAL::isa($thingy, "ARRAY") 108 112 220
927 if UNIVERSAL::isa($thingy,'ARRAY');
928 112 ▶ return $self->format_profile_branch($thingy, $depth, $pad, $path, $leaves)
Branch: 1 branch
BranchTrueFalseTotal
if UNIVERSAL::isa($thingy, "HASH") 112 0 112
929 if UNIVERSAL::isa($thingy,'HASH');
930 0 return "$thingy\n";
931 }
932  
933  
934 54 ▶sub on_destroy {
Subroutine on_destroy: called CC=4 SCAR=14.0
Pod undocumented
935 54 my $self = shift;
936 54 ▶ return unless $ON_DESTROY_DUMP;
Branch: 1 branch
BranchTrueFalseTotal
unless $DBI::Profile::ON_DESTROY_DUMP 0 54 54
937 54 ▶ return unless $self->{Data};
Branch: 1 branch
BranchTrueFalseTotal
unless $self->{"Data"} 14 40 54
938 40 my $detail = $self->format();
939 40 ▶ $ON_DESTROY_DUMP->($detail) if $detail;
Branch: 1 branch
BranchTrueFalseTotal
if $detail 40 0 40
940 40 $self->{Data} = undef;
941 }
942  
943 60 ▶sub DESTROY {
Subroutine DESTROY: called CC=5 SCAR=20.9
944 60 my $self = shift;
945 60 local $@;
946 DBI->trace_msg("profile data DESTROY\n",0)
947 60 ▶ if (($self->{Trace}||0) >= 2);
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"Trace"} || 0) >= 2 0 60 60
Condition50%1/2
$self->{'Trace'} || 0
l!l
060
MC/DC0%0/1
$self->{'Trace'} || 0
$self->{'Trace'}
Truth table50%1/2
A
A= $self->{'Trace'}
Aresult
11
00
948 60 eval { $self->on_destroy };
949 60 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 60 60
950 0 chomp $@;
951 0 ▶ my $class = ref($self) || $self;
Condition0%0/3
ref $self || $self
l!l&&r!l&&!r
000
MC/DC0%0/2
ref $self || $self
ref $self $self
Truth table0%0/3
A || B
A= ref $selfB= $self
ABresult
1X1
011
000
952 0 DBI->trace_msg("$class on_destroy failed: $@", 0);
953 }
954 }
955  
956 14 1;
« blib/lib/DBI/W32ODBC.pm ↑ Summary blib/lib/DBD/Gofer/Transport/pipeone.pm »