1DBI::ProfileData(3)   User Contributed Perl Documentation  DBI::ProfileData(3)
2
3
4

NAME

6       DBI::ProfileData - manipulate DBI::ProfileDumper data dumps
7

SYNOPSIS

9       The easiest way to use this module is through the dbiprof frontend (see
10       dbiprof for details):
11
12         dbiprof --number 15 --sort count
13
14       This module can also be used to roll your own profile analysis:
15
16         # load data from dbi.prof
17         $prof = DBI::ProfileData->new(File => "dbi.prof");
18
19         # get a count of the records (unique paths) in the data set
20         $count = $prof->count();
21
22         # sort by longest overall time
23         $prof->sort(field => "longest");
24
25         # sort by longest overall time, least to greatest
26         $prof->sort(field => "longest", reverse => 1);
27
28         # exclude records with key2 eq 'disconnect'
29         $prof->exclude(key2 => 'disconnect');
30
31         # exclude records with key1 matching /^UPDATE/i
32         $prof->exclude(key1 => qr/^UPDATE/i);
33
34         # remove all records except those where key1 matches /^SELECT/i
35         $prof->match(key1 => qr/^SELECT/i);
36
37         # produce a formatted report with the given number of items
38         $report = $prof->report(number => 10);
39
40         # clone the profile data set
41         $clone = $prof->clone();
42
43         # get access to hash of header values
44         $header = $prof->header();
45
46         # get access to sorted array of nodes
47         $nodes = $prof->nodes();
48
49         # format a single node in the same style as report()
50         $text = $prof->format($nodes->[0]);
51
52         # get access to Data hash in DBI::Profile format
53         $Data = $prof->Data();
54

DESCRIPTION

56       This module offers the ability to read, manipulate and format
57       DBI::ProfileDumper profile data.
58
59       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

METHODS

65       The following methods are supported by DBI::ProfileData objects.
66
67   $prof = DBI::ProfileData->new(File => "dbi.prof")
68   $prof = DBI::ProfileData->new(File => "dbi.prof", Filter => sub { ... })
69   $prof = DBI::ProfileData->new(Files => [ "dbi.prof.1", "dbi.prof.2" ])
70       Creates a new DBI::ProfileData object.  Takes either a single file
71       through the File option or a list of Files in an array ref.  If
72       multiple files are specified then the header data from the first file
73       is used.
74
75       Files
76
77       Reference to an array of file names to read.
78
79       File
80
81       Name of file to read. Takes precedence over "Files".
82
83       DeleteFiles
84
85       If true, the files are deleted after being read.
86
87       Actually the files are renamed with a "deleteme" suffix before being
88       read, and then, after reading all the files, they're all deleted
89       together.
90
91       The files are locked while being read which, combined with the rename,
92       makes it safe to 'consume' files that are still being generated by
93       DBI::ProfileDumper.
94
95       Filter
96
97       The "Filter" parameter can be used to supply a code reference that can
98       manipulate the profile data as it is being read. This is most useful
99       for editing SQL statements so that slightly different statements in the
100       raw data will be merged and aggregated in the loaded data. For example:
101
102         Filter => sub {
103             my ($path_ref, $data_ref) = @_;
104             s/foo = '.*?'/foo = '...'/ for @$path_ref;
105         }
106
107       Here's an example that performs some normalization on the SQL. It
108       converts all numbers to "N" and all quoted strings to "S".  It can also
109       convert digits to N within names. Finally, it summarizes long "IN
110       (...)" clauses.
111
112       It's aggressive and simplistic, but it's often sufficient, and serves
113       as an example that you can tailor to suit your own needs:
114
115         Filter => sub {
116             my ($path_ref, $data_ref) = @_;
117             local $_ = $path_ref->[0]; # whichever element contains the SQL Statement
118             s/\b\d+\b/N/g;             # 42 -> N
119             s/\b0x[0-9A-Fa-f]+\b/N/g;  # 0xFE -> N
120             s/'.*?'/'S'/g;             # single quoted strings (doesn't handle escapes)
121             s/".*?"/"S"/g;             # double quoted strings (doesn't handle escapes)
122             # convert names like log_20001231 into log_NNNNNNNN, controlled by $opt{n}
123             s/([a-z_]+)(\d{$opt{n},})/$1.('N' x length($2))/ieg if $opt{n};
124             # abbreviate massive "in (...)" statements and similar
125             s!(([NS],){100,})!sprintf("$2,{repeated %d times}",length($1)/2)!eg;
126         }
127
128       It's often better to perform this kinds of normalization in the DBI
129       while the data is being collected, to avoid too much memory being used
130       by storing profile data for many different SQL statement. See
131       DBI::Profile.
132
133   $copy = $prof->clone();
134       Clone a profile data set creating a new object.
135
136   $header = $prof->header();
137       Returns a reference to a hash of header values.  These are the key
138       value pairs included in the header section of the DBI::ProfileDumper
139       data format.  For example:
140
141         $header = {
142           Path    => [ '!Statement', '!MethodName' ],
143           Program => 't/42profile_data.t',
144         };
145
146       Note that modifying this hash will modify the header data stored inside
147       the profile object.
148
149   $nodes = $prof->nodes()
150       Returns a reference the sorted nodes array.  Each element in the array
151       is a single record in the data set.  The first seven elements are the
152       same as the elements provided by DBI::Profile.  After that each key is
153       in a separate element.  For example:
154
155        $nodes = [
156                   [
157                     2,                      # 0, count
158                     0.0312958955764771,     # 1, total duration
159                     0.000490069389343262,   # 2, first duration
160                     0.000176072120666504,   # 3, shortest duration
161                     0.00140702724456787,    # 4, longest duration
162                     1023115819.83019,       # 5, time of first event
163                     1023115819.86576,       # 6, time of last event
164                     'SELECT foo FROM bar'   # 7, key1
165                     'execute'               # 8, key2
166                                             # 6+N, keyN
167                   ],
168                                             # ...
169                 ];
170
171       Note that modifying this array will modify the node data stored inside
172       the profile object.
173
174   $count = $prof->count()
175       Returns the number of items in the profile data set.
176
177   $prof->sort(field => "field")
178   $prof->sort(field => "field", reverse => 1)
179       Sorts data by the given field.  Available fields are:
180
181         longest
182         total
183         count
184         shortest
185
186       The default sort is greatest to smallest, which is the opposite of the
187       normal Perl meaning.  This, however, matches the expected behavior of
188       the dbiprof frontend.
189
190   $count = $prof->exclude(key2 => "disconnect")
191   $count = $prof->exclude(key2 => "disconnect", case_sensitive => 1)
192   $count = $prof->exclude(key1 => qr/^SELECT/i)
193       Removes records from the data set that match the given string or
194       regular expression.  This method modifies the data in a permanent
195       fashion - use clone() first to maintain the original data after
196       exclude().  Returns the number of nodes left in the profile data set.
197
198   $count = $prof->match(key2 => "disconnect")
199   $count = $prof->match(key2 => "disconnect", case_sensitive => 1)
200   $count = $prof->match(key1 => qr/^SELECT/i)
201       Removes records from the data set that do not match the given string or
202       regular expression.  This method modifies the data in a permanent
203       fashion - use clone() first to maintain the original data after
204       match().  Returns the number of nodes left in the profile data set.
205
206   $Data = $prof->Data()
207       Returns the same Data hash structure as seen in DBI::Profile.  This
208       structure is not sorted.  The nodes() structure probably makes more
209       sense for most analysis.
210
211   $text = $prof->format($nodes->[0])
212       Formats a single node into a human-readable block of text.
213
214   $text = $prof->report(number => 10)
215       Produces a report with the given number of items.
216

AUTHOR

218       Sam Tregar <sam@tregar.com>
219
221       Copyright (C) 2002 Sam Tregar
222
223       This program is free software; you can redistribute it and/or modify it
224       under the same terms as Perl 5 itself.
225
226
227
228perl v5.36.0                      2023-01-20               DBI::ProfileData(3)
Impressum