blib/lib/DBI/ProfileDumper.pm

filter: Statementstmt 98.9% 94 / 95 Branchbran 66.6% 28 / 42 Conditioncond 52.6% 10 / 19 MC/DCmcdc 27.2% 3 / 11 Subroutinesub 100% 13 / 13 Podpod 28.5% 2 / 7 totaltotal 80.2% 150 / 187 CC 28 SCAR 22.0
CC
28
Cov
85%
flush_to_disk
17.7
write_data
5.1
new
4.9
CRAP 9.1
« blib/lib/DBI/ProfileData.pm ↑ Summary blib/lib/DBI/W32ODBC.pm »
1 package DBI::ProfileDumper;
2 4 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 4 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 =head1 NAME
6  
7 DBI::ProfileDumper - profile DBI usage and output data to a file
8  
9 =head1 SYNOPSIS
10  
11 To profile an existing program using DBI::ProfileDumper, set the
12 DBI_PROFILE environment variable and run your program as usual. For
13 example, using bash:
14  
15 DBI_PROFILE=2/DBI::ProfileDumper program.pl
16  
17 Then analyze the generated file (F<dbi.prof>) with L<dbiprof|dbiprof>:
18  
19 dbiprof
20  
21 You can also activate DBI::ProfileDumper from within your code:
22  
23 use DBI;
24  
25 # profile with default path (2) and output file (dbi.prof)
26 $dbh->{Profile} = "!Statement/DBI::ProfileDumper";
27  
28 # same thing, spelled out
29 $dbh->{Profile} = "!Statement/DBI::ProfileDumper/File:dbi.prof";
30  
31 # another way to say it
32 use DBI::ProfileDumper;
33 $dbh->{Profile} = DBI::ProfileDumper->new(
34 Path => [ '!Statement' ],
35 File => 'dbi.prof' );
36  
37 # using a custom path
38 $dbh->{Profile} = DBI::ProfileDumper->new(
39 Path => [ "foo", "bar" ],
40 File => 'dbi.prof',
41 );
42  
43  
44 =head1 DESCRIPTION
45  
46 DBI::ProfileDumper is a subclass of L<DBI::Profile|DBI::Profile> which
47 dumps profile data to disk instead of printing a summary to your
48 screen. You can then use L<dbiprof|dbiprof> to analyze the data in
49 a number of interesting ways, or you can roll your own analysis using
50 L<DBI::ProfileData|DBI::ProfileData>.
51  
52 B<NOTE:> For Apache/mod_perl applications, use
53 L<DBI::ProfileDumper::Apache|DBI::ProfileDumper::Apache>.
54  
55 =head1 USAGE
56  
57 One way to use this module is just to enable it in your C<$dbh>:
58  
59 $dbh->{Profile} = "1/DBI::ProfileDumper";
60  
61 This will write out profile data by statement into a file called
62 F<dbi.prof>. If you want to modify either of these properties, you
63 can construct the DBI::ProfileDumper object yourself:
64  
65 use DBI::ProfileDumper;
66 $dbh->{Profile} = DBI::ProfileDumper->new(
67 Path => [ '!Statement' ],
68 File => 'dbi.prof'
69 );
70  
71 The C<Path> option takes the same values as in
72 L<DBI::Profile>. The C<File> option gives the name of the
73 file where results will be collected. If it already exists it will be
74 overwritten.
75  
76 You can also activate this module by setting the DBI_PROFILE
77 environment variable:
78  
79 $ENV{DBI_PROFILE} = "!Statement/DBI::ProfileDumper";
80  
81 This will cause all DBI handles to share the same profiling object.
82  
83 =head1 METHODS
84  
85 The following methods are available to be called using the profile
86 object. You can get access to the profile object from the Profile key
87 in any DBI handle:
88  
89 my $profile = $dbh->{Profile};
90  
91 =head2 flush_to_disk
92  
93 $profile->flush_to_disk()
94  
95 Flushes all collected profile data to disk and empties the Data hash. Returns
96 the filename written to. If no profile data has been collected then the file is
97 not written and flush_to_disk() returns undef.
98  
99 The file is locked while it's being written. A process 'consuming' the files
100 while they're being written to, should rename the file first, then lock it,
101 then read it, then close and delete it. The C<DeleteFiles> option to
102 L<DBI::ProfileData> does the right thing.
103  
104 This method may be called multiple times during a program run.
105  
106 =head2 empty
107  
108 $profile->empty()
109  
110 Clears the Data hash without writing to disk.
111  
112 =head2 filename
113  
114 $filename = $profile->filename();
115  
116 Get or set the filename.
117  
118 The filename can be specified as a CODE reference, in which case the referenced
119 code should return the filename to be used. The code will be called with the
120 profile object as its first argument.
121  
122 =head1 DATA FORMAT
123  
124 The data format written by DBI::ProfileDumper starts with a header
125 containing the version number of the module used to generate it. Then
126 a block of variable declarations describes the profile. After two
127 newlines, the profile data forms the body of the file. For example:
128  
129 DBI::ProfileDumper 2.003762
130 Path = [ '!Statement', '!MethodName' ]
131 Program = t/42profile_data.t
132  
133 + 1 SELECT name FROM users WHERE id = ?
134 + 2 prepare
135 = 1 0.0312958955764771 0.000490069389343262 0.000176072120666504 0.00140702724456787 1023115819.83019 1023115819.86576
136 + 2 execute
137 1 0.0312958955764771 0.000490069389343262 0.000176072120666504 0.00140702724456787 1023115819.83019 1023115819.86576
138 + 2 fetchrow_hashref
139 = 1 0.0312958955764771 0.000490069389343262 0.000176072120666504 0.00140702724456787 1023115819.83019 1023115819.86576
140 + 1 UPDATE users SET name = ? WHERE id = ?
141 + 2 prepare
142 = 1 0.0312958955764771 0.000490069389343262 0.000176072120666504 0.00140702724456787 1023115819.83019 1023115819.86576
143 + 2 execute
144 = 1 0.0312958955764771 0.000490069389343262 0.000176072120666504 0.00140702724456787 1023115819.83019 1023115819.86576
145  
146 The lines beginning with C<+> signs signify keys. The number after
147 the C<+> sign shows the nesting level of the key. Lines beginning
148 with C<=> are the actual profile data, in the same order as
149 in DBI::Profile.
150  
151 Note that the same path may be present multiple times in the data file
152 since C<format()> may be called more than once. When read by
153 DBI::ProfileData the data points will be merged to produce a single
154 data set for each distinct path.
155  
156 The key strings are transformed in three ways. First, all backslashes
157 are doubled. Then all newlines and carriage-returns are transformed
158 into C<\n> and C<\r> respectively. Finally, any NULL bytes (C<\0>)
159 are entirely removed. When DBI::ProfileData reads the file the first
160 two transformations will be reversed, but NULL bytes will not be
161 restored.
162  
163 =head1 AUTHOR
164  
165 Sam Tregar <sam@tregar.com>
166  
167 =head1 COPYRIGHT AND LICENSE
168  
169 Copyright (C) 2002 Sam Tregar
170  
171 This program is free software; you can redistribute it and/or modify
172 it under the same terms as Perl 5 itself.
173  
174 =cut
175  
176 # inherit from DBI::Profile
177 4 ▶use DBI::Profile;
Subroutine BEGIN: called CC=1 SCAR=0.0
178  
179 4 our @ISA = ("DBI::Profile");
180  
181 4 our $VERSION = "2.015325";
182  
183 4 ▶use Carp qw(croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
184 4 ▶use Fcntl qw(:flock);
Subroutine BEGIN: called CC=1 SCAR=0.0
185 4 ▶use Symbol;
Subroutine BEGIN: called CC=1 SCAR=0.0
186  
187 my $HAS_FLOCK = (defined $ENV{DBI_PROFILE_FLOCK})
188 ? $ENV{DBI_PROFILE_FLOCK}
189 4 ▶ : do { local $@; eval { flock STDOUT, 0; 1 } };
Branch: 1 branch
BranchTrueFalseTotal
defined $ENV{'DBI_PROFILE_FLOCK'} ? : 0 4 4
190  
191 4 my $program_header;
192  
193  
194 # validate params and setup default
195 6 ▶sub new {
Subroutine new: called CC=4 SCAR=15.9
Pod undocumented
196 6 my $pkg = shift;
197 6 my $self = $pkg->SUPER::new(
198 LockFile => $HAS_FLOCK,
199 @_,
200 );
201  
202 # provide a default filename
203 6 ▶ $self->filename("dbi.prof") unless $self->filename;
Branch: 1 branch
BranchTrueFalseTotal
unless $self->filename 0 6 6
204  
205 0 DBI->trace_msg("$self: @{[ %$self ]}\n",0)
206 6 ▶ if $self->{Trace} && $self->{Trace} >= 2;
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"Trace"} and $self->{"Trace"} >= 2 0 6 6
Condition33%1/3
$self->{"Trace"} and $self->{"Trace"} >= 2
!ll&&!rl&&r
600
MC/DC0%0/2
$self->{"Trace"} and $self->{"Trace"} >= 2
$self->{"Trace"} $self->{"Trace"} >= 2
Truth table33%1/3
A and B
A= $self->{"Trace"}B= $self->{"Trace"} >= 2
ABresult
0X0
100
111
207  
208 6 return $self;
209 }
210  
211  
212 # get/set filename to use
213 56 ▶sub filename {
Subroutine filename: called CC=3 SCAR=11.3
Pod documented
214 56 my $self = shift;
215 56 ▶ $self->{File} = shift if @_;
Branch: 1 branch
BranchTrueFalseTotal
if @_ 0 56 56
216 56 my $filename = $self->{File};
217 56 ▶ $filename = $filename->($self) if ref($filename) eq 'CODE';
Branch: 1 branch
BranchTrueFalseTotal
if ref $filename eq "CODE" 0 56 56
218 56 return $filename;
219 }
220  
221  
222 # flush available data to disk
223 50 ▶sub flush_to_disk {
Subroutine flush_to_disk: called CC=16 SCAR=28.8
Pod documented
224 50 my $self = shift;
225 50 my $class = ref $self;
226 50 my $filename = $self->filename;
227 50 my $data = $self->{Data};
228  
229 50 if (1) { # make an option
230 50 ▶ if (not $data or ref $data eq 'HASH' && !%$data) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $data or ref $data eq "HASH" and not %$data) 2 48 50
Condition50%3/6
not $data or ref $data eq "HASH" and not %$data
l!l&&r!l&&!r
2048
ref $data eq "HASH" and not %$data
!ll&&!rl&&r
0480
MC/DC33%1/3
not $data or ref $data eq "HASH" and not %$data
not $data ref $data eq "HASH" not %$data
Truth table50%2/4
not(A) or B and not(C)
A= not $dataB= ref $data eq "HASH"C= not %$data
ABCresult
1XX1
0111
00X0
0100
231 2 ▶ DBI->trace_msg("flush_to_disk skipped for empty profile\n",0) if $self->{Trace};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"Trace"} 0 2 2
232 2 return undef;
233 }
234 }
235  
236 48 my $fh = gensym;
237 48 ▶ if (($self->{_wrote_header}||'') eq $filename) {
Branch: 1 branch
BranchTrueFalseTotal
if (($self->{'_wrote_header'} || '') eq $filename) { } 42 6 48
Condition100%2/2
$self->{'_wrote_header'} || ''
l!l
426
MC/DC100%1/1
$self->{'_wrote_header'} || ''
$self->{'_wrote_header'}
Truth table100%2/2
A
A= $self->{'_wrote_header'}
Aresult
11
00
238 # append more data to the file
239 # XXX assumes that Path hasn't changed
240 42 ▶ open($fh, ">>", $filename)
Branch: 1 branch
BranchTrueFalseTotal
open $fh, ">>", $filename or croak("Unable to open '${filename}' for $class output: $!") 42 0 42
241 or croak("Unable to open '$filename' for $class output: $!");
242 } else {
243 # create new file (or overwrite existing)
244 6 ▶ if (-f $filename) {
Branch: 1 branch
BranchTrueFalseTotal
if (-f $filename) 2 4 6
245 2 my $bak = $filename.'.prev';
246 2 unlink($bak);
247 2 ▶ rename($filename, $bak)
Branch: 1 branch
BranchTrueFalseTotal
rename $filename, $bak or warn "Error renaming $filename to ${bak}: $!\n" 2 0 2
248 or warn "Error renaming $filename to $bak: $!\n";
249 }
250 6 ▶ open($fh, ">", $filename)
Branch: 1 branch
BranchTrueFalseTotal
open $fh, ">", $filename or croak("Unable to open '${filename}' for $class output: $!") 6 0 6
251 or croak("Unable to open '$filename' for $class output: $!");
252 }
253 # lock the file (before checking size and writing the header)
254 48 ▶ flock($fh, LOCK_EX) if $self->{LockFile};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"LockFile"} 48 0 48
255 # write header if file is empty - typically because we just opened it
256 # in '>' mode, or perhaps we used '>>' but the file had been truncated externally.
257 48 ▶ if (-s $fh == 0) {
Branch: 1 branch
BranchTrueFalseTotal
if (-s $fh == 0) 6 42 48
258 6 ▶ DBI->trace_msg("flush_to_disk wrote header to $filename\n",0) if $self->{Trace};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"Trace"} 0 6 6
259 6 $self->write_header($fh);
260 6 $self->{_wrote_header} = $filename;
261 }
262  
263 48 my $lines = $self->write_data($fh, $self->{Data}, 1);
264 48 ▶ DBI->trace_msg("flush_to_disk wrote $lines lines to $filename\n",0) if $self->{Trace};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"Trace"} 0 48 48
265  
266 48 ▶ close($fh) # unlocks the file
Branch: 1 branch
BranchTrueFalseTotal
close $fh or croak("Error closing '${filename}': $!") 48 0 48
267 or croak("Error closing '$filename': $!");
268  
269 48 $self->empty();
270  
271  
272 48 return $filename;
273 }
274  
275  
276 # write header to a filehandle
277 6 ▶sub write_header {
Subroutine write_header: called CC=4 SCAR=13.9
Pod undocumented
278 6 my ($self, $fh) = @_;
279  
280 # isolate us against globals which effect print
281 6 local($\, $,);
282  
283 # $self->VERSION can return undef during global destruction
284 6 ▶ my $version = $self->VERSION || $VERSION;
Condition33%1/3
$self->VERSION || $DBI::ProfileDumper::VERSION
l!l&&r!l&&!r
600
MC/DC0%0/2
$self->VERSION || $DBI::ProfileDumper::VERSION
$self->VERSION $DBI::ProfileDumper::VERSION
Truth table33%1/3
A || B
A= $self->VERSIONB= $DBI::ProfileDumper::VERSION
ABresult
1X1
011
000
285  
286 # module name and version number
287 6 print $fh ref($self)." $version\n";
288  
289 # print out Path (may contain CODE refs etc)
290 6 ▶ my @path_words = map { escape_key($_) } @{ $self->{Path} || [] };
Condition100%2/2
$self->{'Path'} || []
l!l
42
MC/DC100%1/1
$self->{'Path'} || []
$self->{'Path'}
Truth table100%2/2
A
A= $self->{'Path'}
Aresult
11
00
291 6 print $fh "Path = [ ", join(', ', @path_words), " ]\n";
292  
293 # print out $0 and @ARGV
294 6 ▶ if (!$program_header) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($program_header) 4 2 6
295 # XXX should really quote as well as escape
296 $program_header = "Program = "
297 4 . join(" ", map { escape_key($_) } $0, @ARGV)
298 . "\n";
299 }
300 6 print $fh $program_header;
301  
302 # all done
303 6 print $fh "\n";
304 }
305  
306  
307 # write data in the proscribed format
308 140 ▶sub write_data {
Subroutine write_data: called CC=5 SCAR=16.3
Pod undocumented
309 140 my ($self, $fh, $data, $level) = @_;
310  
311 # XXX it's valid for $data to be an ARRAY ref, i.e., Path is empty.
312 # produce an empty profile for invalid $data
313 140 ▶ return 0 unless $data and UNIVERSAL::isa($data,'HASH');
Branch: 1 branch
BranchTrueFalseTotal
unless $data and UNIVERSAL::isa($data, "HASH") 0 140 140
Condition33%1/3
$data and UNIVERSAL::isa($data, "HASH")
!ll&&!rl&&r
00140
MC/DC0%0/2
$data and UNIVERSAL::isa($data, "HASH")
$data UNIVERSAL::isa($data, "HASH")
Truth table33%1/3
A and B
A= $dataB= UNIVERSAL::isa($data, "HASH")
ABresult
0X0
100
111
314  
315 # isolate us against globals which affect print
316 140 local ($\, $,);
317  
318 140 my $lines = 0;
319 140 ▶ while (my ($key, $value) = each(%$data)) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %$data) 374 140 514
320 # output a key
321 374 print $fh "+ $level ". escape_key($key). "\n";
322 374 ▶ if (UNIVERSAL::isa($value,'ARRAY')) {
Branch: 1 branch
BranchTrueFalseTotal
if (UNIVERSAL::isa($value, 'ARRAY')) { } 282 92 374
323 # output a data set for a leaf node
324 282 print $fh "= ".join(' ', @$value)."\n";
325 282 $lines += 1;
326 } else {
327 # recurse through keys - this could be rewritten to use a
328 # stack for some small performance gain
329 92 $lines += $self->write_data($fh, $value, $level + 1);
330 }
331 }
332 140 return $lines;
333 }
334  
335  
336 # escape a key for output
337 386 ▶sub escape_key {
Subroutine escape_key: called CC=1 SCAR=0.0
Pod undocumented
338 386 my $key = shift;
339 386 $key =~ s!\\!\\\\!g;
340 386 $key =~ s!\n!\\n!g;
341 386 $key =~ s!\r!\\r!g;
342 386 $key =~ s!\0!!g;
343 386 return $key;
344 }
345  
346  
347 # flush data to disk when profile object goes out of scope
348 6 ▶sub on_destroy {
Subroutine on_destroy: called CC=1 SCAR=0.0
Pod undocumented
349 6 shift->flush_to_disk();
350 }
351  
352 4 1;
« blib/lib/DBI/ProfileData.pm ↑ Summary blib/lib/DBI/W32ODBC.pm »