1DBI::ProfileData(3) User Contributed Perl Documentation DBI::ProfileData(3)
2
6 DBI::ProfileData - manipulate DBI::ProfileDumper data dumps
7
9 The easiest way to use this module is through the dbiprof frontend (see
10 dbiprof for details):
11 dbiprof --number 15 --sort count
13 This module can also be used to roll your own profile analysis:
15 # load data from dbi.prof
17 $prof = DBI::ProfileData->new(File => "dbi.prof");
18 # get a count of the records in the data set
20 $count = $prof->count();
21 # sort by longest overall time
23 $prof->sort(field => "longest");
24 # sort by longest overall time, least to greatest
26 $prof->sort(field => "longest", reverse => 1);
27 # exclude records with key2 eq 'disconnect'
29 $prof->exclude(key2 => 'disconnect');
30 # exclude records with key1 matching /^UPDATE/i
32 $prof->exclude(key1 => qr/^UPDATE/i);
33 # remove all records except those where key1 matches /^SELECT/i
35 $prof->match(key1 => qr/^SELECT/i);
36 # produce a formatted report with the given number of items
38 $report = $prof->report(number => 10);
39 # clone the profile data set
41 $clone = $prof->clone();
42 # get access to hash of header values
44 $header = $prof->header();
45 # get access to sorted array of nodes
47 $nodes = $prof->nodes();
48 # format a single node in the same style as report()
50 $text = $prof->format($nodes->[0]);
51 # get access to Data hash in DBI::Profile format
53 $Data = $prof->Data();
54
56 This module offers the ability to read, manipulate and format DBI::Pro‐
57 fileDumper profile data.
58 Conceptually, a profile consists of a series of records, or nodes, each
60 of each has a set of statistics and set of keys. Each record must have
61 a unique set of keys, but there is no requirement that every record
62 have the same number of keys.
63
65 The following methods are supported by DBI::ProfileData objects.
66 $prof = DBI::ProfileData->new(File => "dbi.prof")
68 $prof = DBI::ProfileData->new(File => "dbi.prof", Filter => sub { ...
69 })
70 $prof = DBI::ProfileData->new(Files => [ "dbi.prof.1", "dbi.prof.2" ])
71 Creates a a new DBI::ProfileData object. Takes either a single
72 file through the File option or a list of Files in an array ref.
73 If multiple files are specified then the header data from the first
74 file is used.
75 The "Filter" parameter can be used to supply a code reference that
77 can manipulate the profile data as it is being read. This is most
78 useful for editing SQL statements so that slightly different state‐
79 ments in the raw data will be merged and aggregated in the loaded
80 data. For example:
81 Filter => sub {
83 my ($path_ref, $data_ref) = @_;
84 s/foo = '.*?'/foo = '...'/ for @$path_ref;
85 }
86 Here's an example that performs some normalization on the SQL. It
88 converts all numbers to "N" and all quoted strings to "S". It can
89 also convert digits to N within names. Finally, it summarizes long
90 "IN (...)" clauses.
91 It's aggressive and simplistic, but it's often sufficient, and
93 serves as an example that you can tailor to suit your own needs:
94 Filter => sub {
96 my ($path_ref, $data_ref) = @_;
97 local $_ = $path_ref->[0]; # whichever element contains the SQL Statement
98 s/\b\d+\b/N/g; # 42 -> N
99 s/\b0x[0-9A-Fa-f]+\b/N/g; # 0xFE -> N
100 s/'.*?'/'S'/g; # single quoted strings (doesn't handle escapes)
101 s/".*?"/"S"/g; # double quoted strings (doesn't handle escapes)
102 # convert names like log_20001231 into log_NNNNNNNN, controlled by $opt{n}
103 s/([a-z_]+)(\d{$opt{n},})/$1.('N' x length($2))/ieg if $opt{n};
104 # abbreviate massive "in (...)" statements and similar
105 s!(([NS],){100,})!sprintf("$2,{repeated %d times}",length($1)/2)!eg;
106 }
107 It's often better to perform this kinds of normalization in the DBI
109 while the data is being collected, to avoid too much memory being
110 used by storing profile data for many different SQL statement. See
111 DBI::Profile.
112 $copy = $prof->clone();
114 Clone a profile data set creating a new object.
115 $header = $prof->header();
117 Returns a reference to a hash of header values. These are the key
118 value pairs included in the header section of the DBI::Profile‐
119 Dumper data format. For example:
120 $header = {
122 Path => [ '!Statement', '!MethodName' ],
123 Program => 't/42profile_data.t',
124 };
125 Note that modifying this hash will modify the header data stored
127 inside the profile object.
128 $nodes = $prof->nodes()
130 Returns a reference the sorted nodes array. Each element in the
131 array is a single record in the data set. The first seven elements
132 are the same as the elements provided by DBI::Profile. After that
133 each key is in a separate element. For example:
134 $nodes = [
136 [
137 2, # 0, count
138 0.0312958955764771, # 1, total duration
139 0.000490069389343262, # 2, first duration
140 0.000176072120666504, # 3, shortest duration
141 0.00140702724456787, # 4, longest duration
142 1023115819.83019, # 5, time of first event
143 1023115819.86576, # 6, time of last event
144 'SELECT foo FROM bar' # 7, key1
145 'execute' # 8, key2
146 # 6+N, keyN
147 ],
148 # ...
149 ];
150 Note that modifying this array will modify the node data stored
152 inside the profile object.
153 $count = $prof->count()
155 Returns the number of items in the profile data set.
156 $prof->sort(field => "field")
158 $prof->sort(field => "field", reverse => 1)
159 Sorts data by the given field. Available fields are:
160 longest
162 total
163 count
164 shortest
165 The default sort is greatest to smallest, which is the opposite of
167 the normal Perl meaning. This, however, matches the expected
168 behavior of the dbiprof frontend.
169 $count = $prof->exclude(key2 => "disconnect")
171 $count = $prof->exclude(key2 => "disconnect", case_sensitive => 1)
172 $count = $prof->exclude(key1 => qr/^SELECT/i)
173 Removes records from the data set that match the given string or
174 regular expression. This method modifies the data in a permanent
175 fashion - use clone() first to maintain the original data after
176 exclude(). Returns the number of nodes left in the profile data
177 set.
178 $count = $prof->match(key2 => "disconnect")
180 $count = $prof->match(key2 => "disconnect", case_sensitive => 1)
181 $count = $prof->match(key1 => qr/^SELECT/i)
182 Removes records from the data set that do not match the given
183 string or regular expression. This method modifies the data in a
184 permanent fashion - use clone() first to maintain the original data
185 after match(). Returns the number of nodes left in the profile
186 data set.
187 $Data = $prof->Data()
189 Returns the same Data hash structure as seen in DBI::Profile. This
190 structure is not sorted. The nodes() structure probably makes more
191 sense for most analysis.
192 $text = $prof->format($nodes->[0])
194 Formats a single node into a human-readable block of text.
195 $text = $prof->report(number => 10)
197 Produces a report with the given number of items.
198
200 Sam Tregar <sam@tregar.com>
201
203 Copyright (C) 2002 Sam Tregar
204 This program is free software; you can redistribute it and/or modify it
206 under the same terms as Perl 5 itself.
207perl v5.8.8 2006-02-07 DBI::ProfileData(3)