blib/lib/DBI/ProfileDumper/Apache.pm untested

filter: Statementstmt 0.0% 0 / 42 Branchbran 0.0% 0 / 12 Conditioncond 0.0% 0 / 14 MC/DCmcdc 0.0% 0 / 8 Subroutinesub 0.0% 0 / 10 Podpod 0.0% 0 / 3 totaltotal 0.0% 0 / 89 CC 5 SCAR 20.4
CC
5
Cov
0%
filename
20.0
flush_to_disk
6.0
_dirname
2.0
CRAP 7.7
1 package DBI::ProfileDumper::Apache;
2  
3 use strict;
4 use warnings;
5  
6 =head1 NAME
7  
8 DBI::ProfileDumper::Apache - capture DBI profiling data from Apache/mod_perl
9  
10 =head1 SYNOPSIS
11  
12 Add this line to your F<httpd.conf>:
13  
14 PerlSetEnv DBI_PROFILE 2/DBI::ProfileDumper::Apache
15  
16 (If you're using mod_perl2, see L</When using mod_perl2> for some additional notes.)
17  
18 Then restart your server. Access the code you wish to test using a
19 web browser, then shutdown your server. This will create a set of
20 F<dbi.prof.*> files in your Apache log directory.
21  
22 Get a profiling report with L<dbiprof|dbiprof>:
23  
24 dbiprof /path/to/your/apache/logs/dbi.prof.*
25  
26 When you're ready to perform another profiling run, delete the old files and start again.
27  
28 =head1 DESCRIPTION
29  
30 This module interfaces DBI::ProfileDumper to Apache/mod_perl. Using
31 this module you can collect profiling data from mod_perl applications.
32 It works by creating a DBI::ProfileDumper data file for each Apache
33 process. These files are created in your Apache log directory. You
34 can then use the dbiprof utility to analyze the profile files.
35  
36 =head1 USAGE
37  
38 =head2 LOADING THE MODULE
39  
40 The easiest way to use this module is just to set the DBI_PROFILE
41 environment variable in your F<httpd.conf>:
42  
43 PerlSetEnv DBI_PROFILE 2/DBI::ProfileDumper::Apache
44  
45 The DBI will look after loading and using the module when the first DBI handle
46 is created.
47  
48 It's also possible to use this module by setting the Profile attribute
49 of any DBI handle:
50  
51 $dbh->{Profile} = "2/DBI::ProfileDumper::Apache";
52  
53 See L<DBI::ProfileDumper> for more possibilities, and L<DBI::Profile> for full
54 details of the DBI's profiling mechanism.
55  
56 =head2 WRITING PROFILE DATA
57  
58 The profile data files will be written to your Apache log directory by default.
59  
60 The user that the httpd processes run as will need write access to the
61 directory. So, for example, if you're running the child httpds as user 'nobody'
62 and using chronolog to write to the logs directory, then you'll need to change
63 the default.
64  
65 You can change the destination directory either by specifying a C<Dir> value
66 when creating the profile (like C<File> in the L<DBI::ProfileDumper> docs),
67 or you can use the C<DBI_PROFILE_APACHE_LOG_DIR> env var to change that. For example:
68  
69 PerlSetEnv DBI_PROFILE_APACHE_LOG_DIR /server_root/logs
70  
71 =head3 When using mod_perl2
72  
73 Under mod_perl2 you'll need to either set the C<DBI_PROFILE_APACHE_LOG_DIR> env var,
74 or enable the mod_perl2 C<GlobalRequest> option, like this:
75  
76 PerlOptions +GlobalRequest
77  
78 to the global config section you're about test with DBI::ProfileDumper::Apache.
79 If you don't do one of those then you'll see messages in your error_log similar to:
80  
81 DBI::ProfileDumper::Apache on_destroy failed: Global $r object is not available. Set:
82 PerlOptions +GlobalRequest in httpd.conf at ..../DBI/ProfileDumper/Apache.pm line 144
83  
84 =head3 Naming the files
85  
86 The default file name is inherited from L<DBI::ProfileDumper> via the
87 filename() method, but DBI::ProfileDumper::Apache appends the parent pid and
88 the current pid, separated by dots, to that name.
89  
90 =head3 Silencing the log
91  
92 By default a message is written to STDERR (i.e., the apache error_log file)
93 when flush_to_disk() is called (either explicitly, or implicitly via DESTROY).
94  
95 That's usually very useful. If you don't want the log message you can silence
96 it by setting the C<Quiet> attribute true.
97  
98 PerlSetEnv DBI_PROFILE 2/DBI::ProfileDumper::Apache/Quiet:1
99  
100 $dbh->{Profile} = "!Statement/DBI::ProfileDumper/Quiet:1";
101  
102 $dbh->{Profile} = DBI::ProfileDumper->new(
103 Path => [ '!Statement' ]
104 Quiet => 1
105 );
106  
107  
108 =head2 GATHERING PROFILE DATA
109  
110 Once you have the module loaded, use your application as you normally
111 would. Stop the webserver when your tests are complete. Profile data
112 files will be produced when Apache exits and you'll see something like
113 this in your error_log:
114  
115 DBI::ProfileDumper::Apache writing to /usr/local/apache/logs/dbi.prof.2604.2619
116  
117 Now you can use dbiprof to examine the data:
118  
119 dbiprof /usr/local/apache/logs/dbi.prof.2604.*
120  
121 By passing dbiprof a list of all generated files, dbiprof will
122 automatically merge them into one result set. You can also pass
123 dbiprof sorting and querying options, see L<dbiprof> for details.
124  
125 =head2 CLEANING UP
126  
127 Once you've made some code changes, you're ready to start again.
128 First, delete the old profile data files:
129  
130 rm /usr/local/apache/logs/dbi.prof.*
131  
132 Then restart your server and get back to work.
133  
134 =head1 OTHER ISSUES
135  
136 =head2 Memory usage
137  
138 DBI::Profile can use a lot of memory for very active applications because it
139 collects profiling data in memory for each distinct query run.
140 Calling C<flush_to_disk()> will write the current data to disk and free the
141 memory it's using. For example:
142  
143 $dbh->{Profile}->flush_to_disk() if $dbh->{Profile};
144  
145 or, rather than flush every time, you could flush less often:
146  
147 $dbh->{Profile}->flush_to_disk()
148 if $dbh->{Profile} and ++$i % 100;
149  
150 =head1 AUTHOR
151  
152 Sam Tregar <sam@tregar.com>
153  
154 =head1 COPYRIGHT AND LICENSE
155  
156 Copyright (C) 2002 Sam Tregar
157  
158 This program is free software; you can redistribute it and/or modify
159 it under the same terms as Perl 5 itself.
160  
161 =cut
162  
163 our $VERSION = "2.014121";
164  
165 our @ISA = qw(DBI::ProfileDumper);
166  
167 use DBI::ProfileDumper;
168 use File::Spec;
169  
170 my $initial_pid = $$;
171  
172 use constant MP2 => ($ENV{MOD_PERL_API_VERSION} and $ENV{MOD_PERL_API_VERSION} == 2) ? 1 : 0;
173  
174 my $server_root_dir;
175  
176 if (MP2) {
177 require Apache2::ServerUtil;
178 $server_root_dir = Apache2::ServerUtil::server_root();
179 }
180 else {
181 require Apache;
182 $server_root_dir = eval { Apache->server_root_relative('') } || "/tmp";
183 }
184  
185  
186 sub _dirname {
187 my $self = shift;
188 return $self->{Dir} ||= $ENV{DBI_PROFILE_APACHE_LOG_DIR}
189 || File::Spec->catdir($server_root_dir, "logs");
190 }
191  
192  
193 sub filename {
194 my $self = shift;
195 my $filename = $self->SUPER::filename(@_);
196 return $filename if not $filename; # not set yet
197  
198 # to be able to identify groups of profile files from the same set of
199 # apache processes, we include the parent pid in the file name
200 # as well as the pid.
201 my $group_pid = ($$ eq $initial_pid) ? $$ : getppid();
202 $filename .= ".$group_pid.$$";
203  
204 return $filename if File::Spec->file_name_is_absolute($filename);
205 return File::Spec->catfile($self->_dirname, $filename);
206 }
207  
208  
209 sub flush_to_disk {
210 my $self = shift;
211  
212 my $filename = $self->SUPER::flush_to_disk(@_);
213  
214 print STDERR ref($self)." pid$$ written to $filename\n"
215 if $filename && not $self->{Quiet};
216  
217 return $filename;
218 }
219  
220 1;