.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DBI::ProfileDumper::Apache 3pm"
.TH DBI::ProfileDumper::Apache 3pm "2020-10-29" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DBI::ProfileDumper::Apache \- capture DBI profiling data from Apache/mod_perl
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Add this line to your \fIhttpd.conf\fR:
.PP
.Vb 1
\&  PerlSetEnv DBI_PROFILE 2/DBI::ProfileDumper::Apache
.Ve
.PP
(If you're using mod_perl2, see \*(L"When using mod_perl2\*(R" for some additional notes.)
.PP
Then restart your server.  Access the code you wish to test using a
web browser, then shutdown your server.  This will create a set of
\&\fIdbi.prof.*\fR files in your Apache log directory.
.PP
Get a profiling report with dbiprof:
.PP
.Vb 1
\&  dbiprof /path/to/your/apache/logs/dbi.prof.*
.Ve
.PP
When you're ready to perform another profiling run, delete the old files and start again.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module interfaces DBI::ProfileDumper to Apache/mod_perl.  Using
this module you can collect profiling data from mod_perl applications.
It works by creating a DBI::ProfileDumper data file for each Apache
process.  These files are created in your Apache log directory.  You
can then use the dbiprof utility to analyze the profile files.
.SH "USAGE"
.IX Header "USAGE"
.SS "\s-1LOADING THE MODULE\s0"
.IX Subsection "LOADING THE MODULE"
The easiest way to use this module is just to set the \s-1DBI_PROFILE\s0
environment variable in your \fIhttpd.conf\fR:
.PP
.Vb 1
\&  PerlSetEnv DBI_PROFILE 2/DBI::ProfileDumper::Apache
.Ve
.PP
The \s-1DBI\s0 will look after loading and using the module when the first \s-1DBI\s0 handle
is created.
.PP
It's also possible to use this module by setting the Profile attribute
of any \s-1DBI\s0 handle:
.PP
.Vb 1
\&  $dbh\->{Profile} = "2/DBI::ProfileDumper::Apache";
.Ve
.PP
See DBI::ProfileDumper for more possibilities, and DBI::Profile for full
details of the \s-1DBI\s0's profiling mechanism.
.SS "\s-1WRITING PROFILE DATA\s0"
.IX Subsection "WRITING PROFILE DATA"
The profile data files will be written to your Apache log directory by default.
.PP
The user that the httpd processes run as will need write access to the
directory.  So, for example, if you're running the child httpds as user 'nobody'
and using chronolog to write to the logs directory, then you'll need to change
the default.
.PP
You can change the destination directory either by specifying a \f(CW\*(C`Dir\*(C'\fR value
when creating the profile (like \f(CW\*(C`File\*(C'\fR in the DBI::ProfileDumper docs),
or you can use the \f(CW\*(C`DBI_PROFILE_APACHE_LOG_DIR\*(C'\fR env var to change that. For example:
.PP
.Vb 1
\&  PerlSetEnv DBI_PROFILE_APACHE_LOG_DIR /server_root/logs
.Ve
.PP
\fIWhen using mod_perl2\fR
.IX Subsection "When using mod_perl2"
.PP
Under mod_perl2 you'll need to either set the \f(CW\*(C`DBI_PROFILE_APACHE_LOG_DIR\*(C'\fR env var,
or enable the mod_perl2 \f(CW\*(C`GlobalRequest\*(C'\fR option, like this:
.PP
.Vb 1
\&  PerlOptions +GlobalRequest
.Ve
.PP
to the global config section you're about test with DBI::ProfileDumper::Apache.
If you don't do one of those then you'll see messages in your error_log similar to:
.PP
.Vb 2
\&  DBI::ProfileDumper::Apache on_destroy failed: Global $r object is not available. Set:
\&    PerlOptions +GlobalRequest in httpd.conf at ..../DBI/ProfileDumper/Apache.pm line 144
.Ve
.PP
\fINaming the files\fR
.IX Subsection "Naming the files"
.PP
The default file name is inherited from DBI::ProfileDumper via the
\&\fBfilename()\fR method, but DBI::ProfileDumper::Apache appends the parent pid and
the current pid, separated by dots, to that name.
.PP
\fISilencing the log\fR
.IX Subsection "Silencing the log"
.PP
By default a message is written to \s-1STDERR\s0 (i.e., the apache error_log file)
when \fBflush_to_disk()\fR is called (either explicitly, or implicitly via \s-1DESTROY\s0).
.PP
That's usually very useful. If you don't want the log message you can silence
it by setting the \f(CW\*(C`Quiet\*(C'\fR attribute true.
.PP
.Vb 1
\&  PerlSetEnv DBI_PROFILE 2/DBI::ProfileDumper::Apache/Quiet:1
\&
\&  $dbh\->{Profile} = "!Statement/DBI::ProfileDumper/Quiet:1";
\&
\&  $dbh\->{Profile} = DBI::ProfileDumper\->new(
\&      Path => [ \*(Aq!Statement\*(Aq ]
\&      Quiet => 1
\&  );
.Ve
.SS "\s-1GATHERING PROFILE DATA\s0"
.IX Subsection "GATHERING PROFILE DATA"
Once you have the module loaded, use your application as you normally
would.  Stop the webserver when your tests are complete.  Profile data
files will be produced when Apache exits and you'll see something like
this in your error_log:
.PP
.Vb 1
\&  DBI::ProfileDumper::Apache writing to /usr/local/apache/logs/dbi.prof.2604.2619
.Ve
.PP
Now you can use dbiprof to examine the data:
.PP
.Vb 1
\&  dbiprof /usr/local/apache/logs/dbi.prof.2604.*
.Ve
.PP
By passing dbiprof a list of all generated files, dbiprof will
automatically merge them into one result set.  You can also pass
dbiprof sorting and querying options, see dbiprof for details.
.SS "\s-1CLEANING UP\s0"
.IX Subsection "CLEANING UP"
Once you've made some code changes, you're ready to start again.
First, delete the old profile data files:
.PP
.Vb 1
\&  rm /usr/local/apache/logs/dbi.prof.*
.Ve
.PP
Then restart your server and get back to work.
.SH "OTHER ISSUES"
.IX Header "OTHER ISSUES"
.SS "Memory usage"
.IX Subsection "Memory usage"
DBI::Profile can use a lot of memory for very active applications because it
collects profiling data in memory for each distinct query run.
Calling \f(CW\*(C`flush_to_disk()\*(C'\fR will write the current data to disk and free the
memory it's using. For example:
.PP
.Vb 1
\&  $dbh\->{Profile}\->flush_to_disk() if $dbh\->{Profile};
.Ve
.PP
or, rather than flush every time, you could flush less often:
.PP
.Vb 2
\&  $dbh\->{Profile}\->flush_to_disk()
\&    if $dbh\->{Profile} and ++$i % 100;
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Sam Tregar <sam@tregar.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2002 Sam Tregar
.PP
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl 5 itself.