| 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; |