summaryrefslogtreecommitdiffstatsabout
path: root/docs
diff options
context:
space:
mode:
authorEdward Rudd <urkle@outoforder.cc>2006-11-07 02:44:33 (GMT)
committer Edward Rudd <urkle@outoforder.cc>2006-11-07 02:44:33 (GMT)
commitee22f4a4df3632c5d6def4ef108cbdbda0ce4e47 (patch)
tree87b6bae925ec676800765685774c70e282079d15 /docs
parent45d25f947b7cf068530f009e8846cd3ccde51220 (diff)
updated license file
updated documentation
Diffstat (limited to 'docs')
-rw-r--r--docs/Makefile.in2
-rw-r--r--docs/manual.xml2956
2 files changed, 2487 insertions, 471 deletions
diff --git a/docs/Makefile.in b/docs/Makefile.in
index 81f2298..fa1bd2e 100644
--- a/docs/Makefile.in
+++ b/docs/Makefile.in
@@ -19,7 +19,7 @@ DISTFILES = $(STD_DIST) $(EXTRA_DIST)
19all: all-subdirs 19all: all-subdirs
20 20
21%.html: %.xml 21%.html: %.xml
22 @xmlto html-nochunks $< 22 @xmlto xhtml-nochunks $<
23 23
24%.pdf: %.xml 24%.pdf: %.xml
25 @xmlto pdf $< 25 @xmlto pdf $<
diff --git a/docs/manual.xml b/docs/manual.xml
index 53d6842..9019e80 100644
--- a/docs/manual.xml
+++ b/docs/manual.xml
@@ -1,6 +1,6 @@
1<?xml version="1.0" encoding="UTF-8"?> 1<?xml version="1.0" encoding="UTF-8"?>
2<?xml-stylesheet href="file://localhost/home/urkle/Documents/DocBook/docbook.css" type="text/css"?> 2<?xml-stylesheet href="file://localhost/home/urkle/Documents/DocBook/docbook.css" type="text/css"?>
3<!DOCTYPE article PUBLIC "-//OOOCC//DTD Simplified DocBook XML V1.0 Variant V1.0//EN" "http://outoforder.cc/dtds/odocbook/1.0/odocbook.dtd" [ 3<!DOCTYPE article PUBLIC "-//OOOCC//DTD Simplified DocBook XML V1.1 Variant V1.0//EN" "http://outoforder.cc/dtds/odocbook/1.1/odocbook.dtd" [
4<!ENTITY EmailContact "<email>urkle &lt;at&gt; outoforder &lt;dot&gt; cc</email>"> 4<!ENTITY EmailContact "<email>urkle &lt;at&gt; outoforder &lt;dot&gt; cc</email>">
5]> 5]>
6<article> 6<article>
@@ -13,7 +13,7 @@
13 <contrib>Current Maintainer</contrib> 13 <contrib>Current Maintainer</contrib>
14 <authorblurb> 14 <authorblurb>
15 <simpara> 15 <simpara>
16 &EmailContact; 16 &EmailContact;
17 </simpara> 17 </simpara>
18 </authorblurb> 18 </authorblurb>
19 </author> 19 </author>
@@ -24,7 +24,7 @@
24 <contrib>Original documentation author.</contrib> 24 <contrib>Original documentation author.</contrib>
25 <authorblurb> 25 <authorblurb>
26 <simpara> 26 <simpara>
27 <email>chris &lt;at&gt; grubbybaby &lt;dot&gt; com</email> 27 <email>chris &lt;at&gt; grubbybaby &lt;dot&gt; com</email>
28 </simpara> 28 </simpara>
29 </authorblurb> 29 </authorblurb>
30 </author> 30 </author>
@@ -37,10 +37,21 @@
37 <copyright> 37 <copyright>
38 <year>2004</year> 38 <year>2004</year>
39 <year>2005</year> 39 <year>2005</year>
40 <year>2006</year>
40 <holder>Edward Rudd</holder> 41 <holder>Edward Rudd</holder>
41 </copyright> 42 </copyright>
42 <revhistory> 43 <revhistory>
43 <revision> 44 <revision>
45 <revnumber>1.5</revnumber>
46 <date>2006-11-04</date>
47 <revremark>Added documentation about logio parameters and added DBParam Mysql driver parameters (including tabletype)</revremark>
48 </revision>
49 <revision>
50 <revnumber>1.4</revnumber>
51 <date>2006-02-13</date>
52 <revremark>Added missing logformat types, switched to simplified docbook 1.1</revremark>
53 </revision>
54 <revision>
44 <revnumber>1.3</revnumber> 55 <revnumber>1.3</revnumber>
45 <date>2005-01-11</date> 56 <date>2005-01-11</date>
46 <revremark>Updated for mod_log_sql v1.100</revremark> 57 <revremark>Updated for mod_log_sql v1.100</revremark>
@@ -64,77 +75,245 @@
64 </articleinfo> 75 </articleinfo>
65 <section> 76 <section>
66 <title>Introduction</title> 77 <title>Introduction</title>
67 <section> 78 <section tocstyle="fragment">
68 <title>Summary</title> 79 <title>Summary</title>
69 <para>This Apache module will permit you to log to a SQL database; it can log each access request as well as data associated with each request: cookies, notes, and inbound/outbound headers. Unlike logging to a flat text file -- which is standard in Apache -- a SQL-based log exhibits tremendous flexibility and power of data extraction. (See FAQ entry <xref linkend="FAQ.WhyLogToSQL"/> for further discussion and examples of the advantages to SQL.)</para> 80 <para>
70 <para>This module can either replace or happily coexist with mod_log_config, Apache's text file logging facility. In addition to being more configurable than the standard module, mod_log_sql is much more flexible.</para> 81 This Apache module will permit you to log to a SQL database; it
82 can log each access request as well as data associated with each
83 request: cookies, notes, and inbound/outbound headers. Unlike
84 logging to a flat text file -- which is standard in Apache -- a
85 SQL-based log exhibits tremendous flexibility and power of data
86 extraction. (See FAQ entry
87 <xref linkend="FAQ.WhyLogToSQL" />
88 for further discussion and examples of the advantages to SQL.)
89 </para>
90 <para>
91 This module can either replace or happily coexist with
92 mod_log_config, Apache's text file logging facility. In addition
93 to being more configurable than the standard module, mod_log_sql
94 is much more flexible.
95 </para>
71 </section> 96 </section>
72 <section> 97 <section tocstyle="fragment">
73 <title>Approach</title> 98 <title>Approach</title>
74 <para>This project was formerly known as "mod_log_mysql." It was renamed "mod_log_sql" in order to reflect the project goal of database in-specificity. The module currently supports MySQL, but support for other database back-ends is underway.</para> 99 <para>
75 <para>In order to save speed and overhead, links are kept alive in between queries. This module uses one dedicated SQL link per httpd child, opened by each child process when it is born. Among other things, this means that this module supports logging into only one MySQL server, and for now, also, only one SQL database. But that's a small tradeoff compared to the blinding speed of this module. Error reporting is robust throughout the module and will inform the administrator of database issues in the Apache ErrorLog for the server/virtual server.</para> 100 This project was formerly known as "mod_log_mysql." It was
76 <para>Virtual hosts are supported in the same manner they are in the regular logging modules. The administrator defines some basic 'global' directives in the main server config, then defines more specific 'local' directives inside each VirtualHost stanza.</para> 101 renamed "mod_log_sql" in order to reflect the project goal of
77 <para>A robust "preserve" capability has now been implemented. This permits the module to preserve any failed INSERT commands to a local file on its machine. In any situation that the database is unavailable -- e.g. the network fails or the database host is rebooted -- mod_log_sql will note this in the error log and begin appending its log entries to the preserve file (which is created with the user and group ID of the running Apache process, e.g. "nobody/nobody" on many Linux installations). When database availability returns, mod_log_sql seamlessly resumes logging to it. When convenient for the sysadmin, he/she can easily import the preserve file into the database because it is simply a series of SQL insert statements.</para> 102 database in-specificity. The module currently supports MySQL,
103 but support for other database back-ends is underway.
104 </para>
105 <para>
106 In order to save speed and overhead, links are kept alive in
107 between queries. This module uses one dedicated SQL link per
108 httpd child, opened by each child process when it is born. Among
109 other things, this means that this module supports logging into
110 only one MySQL server, and for now, also, only one SQL database.
111 But that's a small tradeoff compared to the blinding speed of
112 this module. Error reporting is robust throughout the module and
113 will inform the administrator of database issues in the Apache
114 ErrorLog for the server/virtual server.
115 </para>
116 <para>
117 Virtual hosts are supported in the same manner they are in the
118 regular logging modules. The administrator defines some basic
119 'global' directives in the main server config, then defines more
120 specific 'local' directives inside each VirtualHost stanza.
121 </para>
122 <para>
123 A robust "preserve" capability has now been implemented. This
124 permits the module to preserve any failed INSERT commands to a
125 local file on its machine. In any situation that the database is
126 unavailable -- e.g. the network fails or the database host is
127 rebooted -- mod_log_sql will note this in the error log and
128 begin appending its log entries to the preserve file (which is
129 created with the user and group ID of the running Apache
130 process, e.g. "nobody/nobody" on many Linux installations). When
131 database availability returns, mod_log_sql seamlessly resumes
132 logging to it. When convenient for the sysadmin, he/she can
133 easily import the preserve file into the database because it is
134 simply a series of SQL insert statements.
135 </para>
78 </section> 136 </section>
79 <section> 137 <section tocstyle="fragment">
80 <title>What gets logged by default?</title> 138 <title>What gets logged by default?</title>
81 <para>All the data that would be contained in the "Combined Log Format" is logged by default, plus a little extra. Your best bet is to begin by accepting this default, then later customize the log configuration based on your needs. The documentation of the run-time directives includes a full explanation of what you can log, including examples -- see section <xref endterm="Sect.ConfigReference.title" linkend="Sect.ConfigReference"/>.</para> 139 <para>
140 All the data that would be contained in the "Combined Log
141 Format" is logged by default, plus a little extra. Your best bet
142 is to begin by accepting this default, then later customize the
143 log configuration based on your needs. The documentation of the
144 run-time directives includes a full explanation of what you can
145 log, including examples -- see section
146 <xref endterm="Sect.ConfigReference.title"
147 linkend="Sect.ConfigReference" />
148 .
149 </para>
82 </section> 150 </section>
83 <section> 151 <section tocstyle="fragment">
84 <title>Miscellaneous Notes</title> 152 <title>Miscellaneous Notes</title>
85 <itemizedlist> 153 <itemizedlist>
86 <listitem> 154 <listitem>
87 <para>Note which directives go in the 'main server config' and which directives apply to the 'virtual host config'. This is made clear in the directive documentation.</para> 155 <para>
156 Note which directives go in the 'main server config' and
157 which directives apply to the 'virtual host config'. This is
158 made clear in the directive documentation.
159 </para>
88 </listitem> 160 </listitem>
89 <listitem> 161 <listitem>
90 <para>The 'time_stamp' field is stored in an UNSIGNED INTEGER format, in the standard unix "seconds since the epoch" format. This is superior to storing the access time as a string due to size requirements: an UNSIGNED INT requires 4 bytes, whereas an Apache date string (e.g. "18/Nov/2001:13:59:52 -0800") requires 26 bytes: those extra 22 bytes become significant when multiplied by thousands of accesses on a busy server. Besides, an INT type is far more flexible for comparisons, etc.</para> 162 <para>
91 <para>In MySQL 3.21 and above you can easily convert this to a human readable format using from_unixtime(), e.g.: </para> 163 The 'time_stamp' field is stored in an UNSIGNED INTEGER
92 <programlisting>select remote_host,request_uri,from_unixtime(time_stamp) from access_log; </programlisting> 164 format, in the standard unix "seconds since the epoch"
93 <para>The enclosed perl program "make_combined_log.pl" extracts your access log in a format that is completely compatible with the Combined Log Format. You can then feed this to your favorite web log analysis tool.</para> 165 format. This is superior to storing the access time as a
166 string due to size requirements: an UNSIGNED INT requires 4
167 bytes, whereas an Apache date string (e.g.
168 "18/Nov/2001:13:59:52 -0800") requires 26 bytes: those extra
169 22 bytes become significant when multiplied by thousands of
170 accesses on a busy server. Besides, an INT type is far more
171 flexible for comparisons, etc.
172 </para>
173 <para>
174 In MySQL 3.21 and above you can easily convert this to a
175 human readable format using from_unixtime(), e.g.:
176 </para>
177 <programlisting>SELECT remote_host,request_uri,from_unixtime(time_stamp)
178FROM access_log;</programlisting>
179 <para>
180 The enclosed perl program "make_combined_log.pl" extracts
181 your access log in a format that is completely compatible
182 with the Combined Log Format. You can then feed this to your
183 favorite web log analysis tool.
184 </para>
94 </listitem> 185 </listitem>
95 <listitem> 186 <listitem>
96 <para>The table's string values can be CHAR or VARCHAR, at a length of your choice. VARCHAR is superior because it truncates long strings; CHAR types are fixed-length and will be padded with spaces, resulting in waste. Just like the time_stamp issue described above, that kind of space waste multiplies over thousands of records.</para> 187 <para>
188 The table's string values can be CHAR or VARCHAR, at a
189 length of your choice. VARCHAR is superior because it
190 truncates long strings; CHAR types are fixed-length and will
191 be padded with spaces, resulting in waste. Just like the
192 time_stamp issue described above, that kind of space waste
193 multiplies over thousands of records.
194 </para>
97 </listitem> 195 </listitem>
98 <listitem> 196 <listitem>
99 <para>Be careful not to go overboard setting fields to NOT NULL. If a field is marked NOT NULL then it must contain data in the INSERT statement, or the INSERT will fail. These mysterious failures can be quite frustrating and difficult to debug.</para> 197 <para>
198 Be careful not to go overboard setting fields to NOT NULL.
199 If a field is marked NOT NULL then it must contain data in
200 the INSERT statement, or the INSERT will fail. These
201 mysterious failures can be quite frustrating and difficult
202 to debug.
203 </para>
100 </listitem> 204 </listitem>
101 <listitem> 205 <listitem>
102 <para>When Apache logs a numeric field, it uses a '-' character to mean "not applicable," e.g. the number of bytes returned on a 304 (unchanged) request. Since '-' is an illegal character in an SQL numeric field, such fields are assigned the value 0 instead of '-' which, of course, makes perfect sense anyway.</para> 206 <para>
207 When Apache logs a numeric field, it uses a '-' character to
208 mean "not applicable," e.g. the number of bytes returned on
209 a 304 (unchanged) request. Since '-' is an illegal character
210 in an SQL numeric field, such fields are assigned the value
211 0 instead of '-' which, of course, makes perfect sense
212 anyway.
213 </para>
103 </listitem> 214 </listitem>
104 </itemizedlist> 215 </itemizedlist>
105 </section> 216 </section>
106 <section> 217 <section tocstyle="fragment">
107 <title>Author / Maintainer</title> 218 <title>Author / Maintainer</title>
108 <para>The actual logging code was taken from the already existing flat file text modules, so all that credit goes to the Apache Software Foundation.</para> 219 <para>
109 <para>The MySQL routines and directives were added by Zeev Suraski &lt;bourbon@netvision.net.il&gt;. </para> 220 The actual logging code was taken from the already existing flat
110 <para>All changes from 1.06+ and the new documentation were added by Chris Powell <email>chris &lt;at&gt; grubbybaby &lt;dot&gt; com</email>. It seems that the module had fallen into the "un-maintained" category -- it had not been updated since 1998 -- so Chris adopted it as the new maintainer.</para> 221 file text modules, so all that credit goes to the Apache
111 <para>In December of 2003, Edward Rudd &EmailContact; porting the module to Apache 2.0, cleaning up the code, converting the documentation to DocBook, optimizing the main logging loop, and added the much anticipated database abstraction layer.</para> 222 Software Foundation.
112 <para>As of February 2004, Chris Powell handed over maintenance of the module over to Edward Rudd. So you should contact Edward Rudd about the module from now on.</para> 223 </para>
224 <para>
225 The MySQL routines and directives were added by Zeev Suraski
226 &lt;bourbon@netvision.net.il&gt;.
227 </para>
228 <para>
229 All changes from 1.06+ and the new documentation were added by
230 Chris Powell
231 <email>chris &lt;at&gt; grubbybaby &lt;dot&gt; com</email>
232 . It seems that the module had fallen into the "un-maintained"
233 category -- it had not been updated since 1998 -- so Chris
234 adopted it as the new maintainer.
235 </para>
236 <para>
237 In December of 2003, Edward Rudd
238 &EmailContact;
239 porting the module to Apache 2.0, cleaning up the code,
240 converting the documentation to DocBook, optimizing the main
241 logging loop, and added the much anticipated database
242 abstraction layer.
243 </para>
244 <para>
245 As of February 2004, Chris Powell handed over maintenance of the
246 module over to Edward Rudd. So you should contact Edward Rudd
247 about the module from now on.
248 </para>
113 </section> 249 </section>
114 <section id="Sect.MailingLists"> 250 <section id="Sect.MailingLists" tocstyle="fragment">
115 <title id="Sect.MailingLists.title">Mailing Lists</title> 251 <title id="Sect.MailingLists.title">Mailing Lists</title>
116 <para>A general discussion and support mailing list is provided for mod_log_sq at lists.outoforder.cc. To subscribe to the mailing list send a blank e-mail to mod_log_sql-subscribe@lists.outoforder.cc. The list archives can be accessed via Gmane.org's mailng list gateway via any new reader <ulink url="news://news.gmane.org/gmane.comp.apache.mod-log-sql">news://news.gmane.org/gmane.comp.apache.mod-log-sql</ulink>, or via a web browser at <ulink url="http://news.gmane.org/gmane.comp.apache.mod-log-sql">http://news.gmane.org/gmane.comp.apache.mod-log-sql</ulink>.</para> 252 <para>
253 A general discussion and support mailing list is provided for
254 mod_log_sq at lists.outoforder.cc. To subscribe to the mailing
255 list send a blank e-mail to
256 mod_log_sql-subscribe@lists.outoforder.cc. The list archives can
257 be accessed via Gmane.org's mailng list gateway via any new
258 reader
259 <ulink
260 url="news://news.gmane.org/gmane.comp.apache.mod-log-sql">
261 news://news.gmane.org/gmane.comp.apache.mod-log-sql
262 </ulink>
263 , or via a web browser at
264 <ulink
265 url="http://news.gmane.org/gmane.comp.apache.mod-log-sql">
266 http://news.gmane.org/gmane.comp.apache.mod-log-sql
267 </ulink>
268 .
269 </para>
117 </section> 270 </section>
118 </section> 271 </section>
119 <section> 272 <section>
120 <title>Installation</title> 273 <title>Installation</title>
121 <section> 274 <section tocstyle="fragment">
122 <title>Requirements</title> 275 <title>Requirements</title>
123 <itemizedlist> 276 <itemizedlist>
124 <listitem> 277 <listitem>
125 <para>A compatible system. mod_log_sql was authored and tested on systems based on Red Hat Linux (Red Hat, Mandrake), but the module should easily adapt to any modern distribution. mod_log_sql has also been ported successfully to Solaris and FreeBSD.</para> 278 <para>
279 A compatible system. mod_log_sql was authored and tested on
280 systems based on Red Hat Linux (Red Hat, Mandrake), but the
281 module should easily adapt to any modern distribution.
282 mod_log_sql has also been ported successfully to Solaris and
283 FreeBSD.
284 </para>
126 </listitem> 285 </listitem>
127 <listitem> 286 <listitem>
128 <para>Apache 1.3 or 2.0, 1.2 is no longer supported, but may still compile. Ideally you should already have successfully compiled Apache and understand the process, but this document tries to make it simple for beginners.</para> 287 <para>
288 Apache 1.3 or 2.0, 1.2 is no longer supported, but may still
289 compile. Ideally you should already have successfully
290 compiled Apache and understand the process, but this
291 document tries to make it simple for beginners.
292 </para>
129 </listitem> 293 </listitem>
130 <listitem> 294 <listitem>
131 <para>The MySQL development headers. This package is called different things on different distributions. For example, Red Hat 6.x calls this RPM "MySQL-devel" whereas Mandrake calls it "libmysql10-devel." Both MySQL 3.23.x and 4.x are supported.</para> 295 <para>
296 The MySQL development headers. This package is called
297 different things on different distributions. For example,
298 Red Hat 6.x calls this RPM "MySQL-devel" whereas Mandrake
299 calls it "libmysql10-devel." Both MySQL 3.23.x and 4.x are
300 supported.
301 </para>
132 </listitem> 302 </listitem>
133 <listitem> 303 <listitem>
134 <para>MySQL &gt;= 3.23.15 configured, installed and running on either localhost or an accessible networked machine. You should already have a basic understanding of MySQL and how it functions.</para> 304 <para>
305 MySQL &gt;= 3.23.15 configured, installed and running on
306 either localhost or an accessible networked machine. You
307 should already have a basic understanding of MySQL and how
308 it functions.
309 </para>
135 </listitem> 310 </listitem>
136 <listitem> 311 <listitem>
137 <para>Optionally, if you want to be able to log SSL information such as keysize or cipher, you need OpenSSL and mod_ssl installed.</para> 312 <para>
313 Optionally, if you want to be able to log SSL information
314 such as keysize or cipher, you need OpenSSL and mod_ssl
315 installed.
316 </para>
138 </listitem> 317 </listitem>
139 </itemizedlist> 318 </itemizedlist>
140 </section> 319 </section>
@@ -144,111 +323,263 @@
144 <listitem> 323 <listitem>
145 <para>Unpack the archive into a working directory.</para> 324 <para>Unpack the archive into a working directory.</para>
146 <programlisting>$ tar -xzf mod_log_sql-1.94.tar.gz 325 <programlisting>$ tar -xzf mod_log_sql-1.94.tar.gz
147$ cd mod_log_sql-1.9</programlisting> 326$ cd mod_log_sql-1.94</programlisting>
148 </listitem> 327 </listitem>
149 <listitem> 328 <listitem>
150 <para>run configure to configure the source directory.</para> 329 <para>run configure to configure the source directory.</para>
151 <programlisting>$ ./configure</programlisting> 330 <programlisting>$ ./configure</programlisting>
152 <para>The <filename>configure</filename> script should automatically detect all the required libraries and program if the are installed in standard locations.. If it returns an error, here is a description of the arguments you can specify when you run <filename>configure</filename>.</para> 331 <para>
332 The
333 <filename>configure</filename>
334 script should automatically detect all the required
335 libraries and program if the are installed in standard
336 locations.. If it returns an error, here is a description of
337 the arguments you can specify when you run
338 <filename>configure</filename>
339 .
340 </para>
153 <variablelist> 341 <variablelist>
154 <varlistentry> 342 <varlistentry>
155 <term>--with-apxs=/usr/sbin/apxs</term> 343 <term>--with-apxs=/usr/sbin/apxs</term>
156 <listitem> 344 <listitem>
157 <para>This is the full path to the apxs binary, or the directory which contains the program. This program is part of the Apache 1.3 and 2.0 installation.</para> 345 <para>
158 <para>The default is to search <filename>/usr/bin/apxs</filename> and <filename>/usr/sbin/apxs</filename>.</para> 346 This is the full path to the apxs binary, or the
159 <para>Specifying a directory here will search $directory/apxs, $directory/bin/apxs, and $directory/sbin/apxs</para> 347 directory which contains the program. This program is
160 <para>If you have more than one version of Apache installed, you need to specify the correct apxs binary for the one you wish to compile for.</para> 348 part of the Apache 1.3 and 2.0 installation.
349 </para>
350 <para>
351 The default is to search
352 <filename>/usr/bin/apxs</filename>
353 and
354 <filename>/usr/sbin/apxs</filename>
355 .
356 </para>
357 <para>
358 Specifying a directory here will search
359 $directory/apxs, $directory/bin/apxs, and
360 $directory/sbin/apxs
361 </para>
362 <para>
363 If you have more than one version of Apache installed,
364 you need to specify the correct apxs binary for the
365 one you wish to compile for.
366 </para>
161 </listitem> 367 </listitem>
162 </varlistentry> 368 </varlistentry>
163 <varlistentry> 369 <varlistentry>
164 <term>--with-mysql=/path/to/mysql</term> 370 <term>--with-mysql=/path/to/mysql</term>
165 <listitem> 371 <listitem>
166 <para>This is the directory to search for the <filename>libmysqlclient</filename> library and the <application>MySQL</application> headers.</para> 372 <para>
167 <para>The default is to search <filename>/usr/include</filename>, <filename>/usr/include/mysql</filename>, <filename>/usr/local/include</filename>, and <filename>/usr/local/include/mysql</filename> for <application>MySQL</application> headers.. And <filename>/usr/lib</filename>. <filename>/usr/lib/mysql</filename>, <filename>/usr/local/lib</filename>, and <filename>/usr/local/lin/mysql</filename> for the <application>MySQL</application> libraries.</para> 373 This is the directory to search for the
168 <para>Specifying this testargument will search $directory/include and $directory/mysql for <application>MySQL</application> headers. And $directory/lib and $directory/lib/mysql for <application>MySQL</application> libraries.</para> 374 <filename>libmysqlclient</filename>
375 library and the
376 <application>MySQL</application>
377 headers.
378 </para>
379 <para>
380 The default is to search
381 <filename>/usr/include</filename>
382 ,
383 <filename>/usr/include/mysql</filename>
384 ,
385 <filename>/usr/local/include</filename>
386 , and
387 <filename>/usr/local/include/mysql</filename>
388 for
389 <application>MySQL</application>
390 headers.. And
391 <filename>/usr/lib</filename>
392 .
393 <filename>/usr/lib/mysql</filename>
394 ,
395 <filename>/usr/local/lib</filename>
396 , and
397 <filename>/usr/local/lin/mysql</filename>
398 for the
399 <application>MySQL</application>
400 libraries.
401 </para>
402 <para>
403 Specifying this testargument will search
404 $directory/include and $directory/mysql for
405 <application>MySQL</application>
406 headers. And $directory/lib and $directory/lib/mysql
407 for
408 <application>MySQL</application>
409 libraries.
410 </para>
169 </listitem> 411 </listitem>
170 </varlistentry> 412 </varlistentry>
171 <varlistentry> 413 <varlistentry>
172 <term>--enable-ssl</term> 414 <term>--enable-ssl</term>
173 <listitem> 415 <listitem>
174 <para>Specifying this argument will enable the search for mod_ssl and SSL headers, and if found will enable compilation of SSL support into mod_log_sql. SSL support is compiled into a separate module that can be loaded after the main mod_log_sql.</para> 416 <para>
417 Specifying this argument will enable the search for
418 mod_ssl and SSL headers, and if found will enable
419 compilation of SSL support into mod_log_sql. SSL
420 support is compiled into a separate module that can be
421 loaded after the main mod_log_sql.
422 </para>
175 </listitem> 423 </listitem>
176 </varlistentry> 424 </varlistentry>
177 <varlistentry> 425 <varlistentry>
178 <term>--with-ssl-inc=/usr/include/openssl</term> 426 <term>--with-ssl-inc=/usr/include/openssl</term>
179 <listitem> 427 <listitem>
180 <para>This is the path to the SSL toolkit header files that were used to compile mod_ssl. If you want SSL support you most likely need to specify this.</para> 428 <para>
181 <para>The default is to search <filename>/usr/include</filename> and <filename>/usr/include/openssl</filename>.</para> 429 This is the path to the SSL toolkit header files that
182 <para>Specifying this argument will search that directory for the SSL headers.</para> 430 were used to compile mod_ssl. If you want SSL support
431 you most likely need to specify this.
432 </para>
433 <para>
434 The default is to search
435 <filename>/usr/include</filename>
436 and
437 <filename>/usr/include/openssl</filename>
438 .
439 </para>
440 <para>
441 Specifying this argument will search that directory
442 for the SSL headers.
443 </para>
183 </listitem> 444 </listitem>
184 </varlistentry> 445 </varlistentry>
185 <varlistentry> 446 <varlistentry>
186 <term>--with-db-inc=/usr/include/db1</term> 447 <term>--with-db-inc=/usr/include/db1</term>
187 <listitem> 448 <listitem>
188 <para>This argument is only needed when compiling SSL support for Apache 1.3, and needs to be the directory which contains the ndbm.h header file. You can find this by using </para> 449 <para>
189 <programlisting format="linespecific">$ locate ndbm.h 450 This argument is only needed when compiling SSL
451 support for Apache 1.3, and needs to be the directory
452 which contains the ndbm.h header file. You can find
453 this by using
454 </para>
455 <programlisting>$ locate ndbm.h
190/usr/include/db1/ndbm.h 456/usr/include/db1/ndbm.h
191/usr/include/gdbm/ndbm.h</programlisting> 457/usr/include/gdbm/ndbm.h</programlisting>
192 <para>As far as I can tell, there is no difference as to which you specify, but it should be the one that you compiled mod_ssl with.</para> 458 <para>
193 <para>The default is <filename>/usr/include/db1</filename>, which should work on most systems.</para> 459 As far as I can tell, there is no difference as to
460 which you specify, but it should be the one that you
461 compiled mod_ssl with.
462 </para>
463 <para>
464 The default is
465 <filename>/usr/include/db1</filename>
466 , which should work on most systems.
467 </para>
194 </listitem> 468 </listitem>
195 </varlistentry> 469 </varlistentry>
196 <varlistentry> 470 <varlistentry>
197 <term>--disable-apachetest</term> 471 <term>--disable-apachetest</term>
198 <listitem> 472 <listitem>
199 <para>This will disable the apache version test. However there is a side affect if you specify this where I will not be able to determine which version of Apache you are compiling for. So don't specify this.. If you are having troubles with the script detecting your Apache version, then send a bug report along with your system OS version and versions of related packages.</para> 473 <para>
474 This will disable the apache version test. However
475 there is a side affect if you specify this where I
476 will not be able to determine which version of Apache
477 you are compiling for. So don't specify this.. If you
478 are having troubles with the script detecting your
479 Apache version, then send a bug report along with your
480 system OS version and versions of related packages.
481 </para>
200 </listitem> 482 </listitem>
201 </varlistentry> 483 </varlistentry>
202 <varlistentry> 484 <varlistentry>
203 <term>--disable-mysqltest</term> 485 <term>--disable-mysqltest</term>
204 <listitem> 486 <listitem>
205 <para>This will disable the MySQL compile test. Specify this if for some reason the test fail but you know you have specified the correct directories. If mod_los_sql also fails to compile report a bug along with your system OS version and versions of related packages.</para> 487 <para>
488 This will disable the MySQL compile test. Specify this
489 if for some reason the test fail but you know you have
490 specified the correct directories. If mod_los_sql also
491 fails to compile report a bug along with your system
492 OS version and versions of related packages.
493 </para>
206 </listitem> 494 </listitem>
207 </varlistentry> 495 </varlistentry>
208 </variablelist> 496 </variablelist>
209 </listitem> 497 </listitem>
210 <listitem> 498 <listitem>
211 <para>Now compile the module with GNU make. You may have to specify gmake on some systems like FreeBSD.</para> 499 <para>
500 Now compile the module with GNU make. You may have to
501 specify gmake on some systems like FreeBSD.
502 </para>
212 <programlisting>$ gmake</programlisting> 503 <programlisting>$ gmake</programlisting>
213 </listitem> 504 </listitem>
214 <listitem> 505 <listitem>
215 <para>If there were no errors, you can now install the module(s). If you compiled as a non-root user you may need to switch users with <application>su</application> or <application>sudo</application>.</para> 506 <para>
507 If there were no errors, you can now install the module(s).
508 If you compiled as a non-root user you may need to switch
509 users with
510 <application>su</application>
511 or
512 <application>sudo</application>
513 .
514 </para>
216 <programlisting>$ su -c "gmake install" 515 <programlisting>$ su -c "gmake install"
217Password:</programlisting> 516Password:</programlisting>
218 </listitem> 517 </listitem>
219 <listitem> 518 <listitem>
220 <para>Now edit your Apache configuration and load the modules.</para> 519 <para>
520 Now edit your Apache configuration and load the modules.
521 </para>
221 <note> 522 <note>
222 <itemizedlist> 523 <itemizedlist>
223 <listitem> 524 <listitem>
224 <para>If you are loading the SSL logging module, you need to make sure it is loaded after mod_ssl and mod_log_sql.</para> 525 <para>
526 If you are loading the SSL logging module, you need to
527 make sure it is loaded after mod_ssl and mod_log_sql.
528 </para>
225 </listitem> 529 </listitem>
226 <listitem> 530 <listitem>
227 <para>If you have previously used mod_log_sql version 1.18, the name of the module has changed from sql_log_module to log_sql_module (the first parameter to LoadModule)</para> 531 <para>
532 If you have previously used mod_log_sql version 1.18,
533 the name of the module has changed from sql_log_module
534 to log_sql_module (the first parameter to LoadModule)
535 </para>
228 </listitem> 536 </listitem>
229 <listitem> 537 <listitem>
230 <para>If you are upgrading from any release earlier than 1.97 you need to add an extra LoadModule directive to load the database driver (ie mysql).</para> 538 <para>
539 If you are upgrading from any release earlier than
540 1.97 you need to add an extra LoadModule directive to
541 load the database driver (ie mysql).
542 </para>
231 </listitem> 543 </listitem>
232 </itemizedlist> 544 </itemizedlist>
233 </note> 545 </note>
234 <orderedlist> 546 <orderedlist>
235 <listitem> 547 <listitem>
236 <para>Insert these lines to either the main <filename>httpd.conf</filename> or a file included via an include directive.</para> 548 <para>
549 Insert these lines to either the main
550 <filename>httpd.conf</filename>
551 or a file included via an include directive.
552 </para>
237 <programlisting>LoadModule log_sql_module modules/mod_log_sql.so 553 <programlisting>LoadModule log_sql_module modules/mod_log_sql.so
238LoadModule log_sql_mysql_module modules/mod_log_sql_mysql.so 554LoadModule log_sql_mysql_module modules/mod_log_sql_mysql.so
239&lt;IfModule mod_ssl.c&gt; 555&lt;IfModule mod_ssl.c&gt;
240LoadModule log_sql_ssl_module moduels/mod_log_sql_ssl.so 556LoadModule log_sql_ssl_module moduels/mod_log_sql_ssl.so
241&lt;/IfModule&gt;</programlisting> 557&lt;/IfModule&gt;</programlisting>
242 <note><para>If you did not compile SSL support in mod_log_sql, do not include the lines between the &lt;IfModule&gt; directives.</para></note> 558 <note>
559 <para>
560 If you did not compile SSL support in mod_log_sql, do
561 not include the lines between the &lt;IfModule&gt;
562 directives.
563 </para>
564 </note>
243 </listitem> 565 </listitem>
244 <listitem> 566 <listitem>
245 <para>If you are using Apache 1.3 you may need add these lines later in the configuration.</para> 567 <para>
568 If you are using Apache 1.3 you may need add these lines
569 later in the configuration.
570 </para>
246 <programlisting>AddModule mod_log_sql.c 571 <programlisting>AddModule mod_log_sql.c
247AddModule mod_log_sql_mysql.c 572AddModule mod_log_sql_mysql.c
248&lt;IfModule mod_ssl.c&gt; 573&lt;IfModule mod_ssl.c&gt;
249AddModule mod_log_sql_ssl.c 574AddModule mod_log_sql_ssl.c
250&lt;/IfModule&gt;</programlisting> 575&lt;/IfModule&gt;</programlisting>
251 <note><para>If you did not compile SSL support in mod_log_sql, do not include the lines between the &lt;IfModule&gt; directives.</para></note> 576 <note>
577 <para>
578 If you did not compile SSL support in mod_log_sql, do
579 not include the lines between the &lt;IfModule&gt;
580 directives.
581 </para>
582 </note>
252 </listitem> 583 </listitem>
253 </orderedlist> 584 </orderedlist>
254 </listitem> 585 </listitem>
@@ -258,37 +589,100 @@ AddModule mod_log_sql_ssl.c
258 <section id="Sect.Configuration"> 589 <section id="Sect.Configuration">
259 <title id="Sect.Configuration.title">Configuration</title> 590 <title id="Sect.Configuration.title">Configuration</title>
260 <section id="Sect.Preperation"> 591 <section id="Sect.Preperation">
261 <title id="Sect.Preperation.title">Preparing MySQL for logging</title> 592 <title id="Sect.Preperation.title">
262 <para>You have to prepare the database to receive data from <application>mod_log_sql</application>, and set up run-time directives in <filename>httpd.conf</filename> to control how and what <application>mod_log_sql</application> logs.</para> 593 Preparing MySQL for logging
263 <para>This section will discuss how to get started with a basic configuration. Full documentation of all available run-time directives is available in section <xref endterm="Sect.ConfigReference.title" linkend="Sect.ConfigReference"/>.</para> 594 </title>
595 <para>
596 You have to prepare the database to receive data from
597 <application>mod_log_sql</application>
598 , and set up run-time directives in
599 <filename>httpd.conf</filename>
600 to control how and what
601 <application>mod_log_sql</application>
602 logs.
603 </para>
604 <para>
605 This section will discuss how to get started with a basic
606 configuration. Full documentation of all available run-time
607 directives is available in section
608 <xref endterm="Sect.ConfigReference.title"
609 linkend="Sect.ConfigReference" />
610 .
611 </para>
264 <orderedlist> 612 <orderedlist>
265 <listitem> 613 <listitem>
266 <para>mod_log_sql can make its own tables on-the-fly, or you can pre-make the tables by hand. The advantage of letting the module make the tables is ease-of-use, but for raw performance you will want to pre-make the tables in order to save some overhead. In this basic setup we'll just let the module create tables for us.</para> 614 <para>
615 mod_log_sql can make its own tables on-the-fly, or you can
616 pre-make the tables by hand. The advantage of letting the
617 module make the tables is ease-of-use, but for raw
618 performance you will want to pre-make the tables in order to
619 save some overhead. In this basic setup we'll just let the
620 module create tables for us.
621 </para>
267 </listitem> 622 </listitem>
268 <listitem> 623 <listitem>
269 <para>We still need to have a logging database created and ready, so run the MySQL command line client and create a database:</para> 624 <para>
270 <programlisting># mysql -uadmin -pmypassword 625 We still need to have a logging database created and ready,
626 so run the MySQL command line client and create a database:
627 </para>
628 <programlisting># mysql -uadmin -p
271Enter password: 629Enter password:
272mysql&gt; create database apachelogs;</programlisting> 630mysql&gt; create database apachelogs;</programlisting>
273 </listitem> 631 </listitem>
274 <listitem id="Item.CreateTable"> 632 <listitem id="Item.CreateTable">
275 <para>If you want to hand-create the tables, run the enclosed 'create-tables' SQL script as follows ("create_tables.sql" needs to be in your current working directory).</para> 633 <para>
634 If you want to hand-create the tables, run the enclosed
635 'create-tables' SQL script as follows ("create_tables.sql"
636 needs to be in your current working directory).
637 </para>
276 <programlisting>mysql&gt; use apachelogs 638 <programlisting>mysql&gt; use apachelogs
277Database changed 639Database changed
278mysql&gt; source create_tables.sql</programlisting> 640mysql&gt; source create_tables.sql</programlisting>
279 </listitem> 641 </listitem>
280 <listitem> 642 <listitem>
281 <para>Create a specific <application>MySQL</application> userid that <application>httpd</application> will use to authenticate and enter data. This userid need not be an actual Unix user. It is a userid internal to <application>MySQL</application> with specific privileges. In the following example command, "apachelogs" is the database, "loguser" is the userid to create, "my.apachemachine.com" is the name of the Apache machine, and "l0gger" is the password to assign. Choose values that are different from these examples.</para> 643 <para>
644 Create a specific
645 <application>MySQL</application>
646 userid that
647 <application>httpd</application>
648 will use to authenticate and enter data. This userid need
649 not be an actual Unix user. It is a userid internal to
650 <application>MySQL</application>
651 with specific privileges. In the following example command,
652 "apachelogs" is the database, "loguser" is the userid to
653 create, "my.apachemachine.com" is the name of the Apache
654 machine, and "l0gger" is the password to assign. Choose
655 values that are different from these examples.
656 </para>
282 <programlisting>mysql&gt; grant insert,create on apachelogs.* to loguser@my.apachemachine.com identified by 'l0gger';</programlisting> 657 <programlisting>mysql&gt; grant insert,create on apachelogs.* to loguser@my.apachemachine.com identified by 'l0gger';</programlisting>
283 </listitem> 658 </listitem>
284 <listitem> 659 <listitem>
285 <para>You may be especially security-paranoid and want "loguser" to not have "create" capability within the "apachelogs" database. You can disable that privilege, but the cost is that you will not be able to use the module's on-the-fly table creation feature. If that cost is acceptable, hand-create the tables as described in step <xref linkend="Item.CreateTable"/> and use the following GRANT statement instead of the one above:</para> 660 <para>
661 You may be especially security-paranoid and want "loguser"
662 to not have "create" capability within the "apachelogs"
663 database. You can disable that privilege, but the cost is
664 that you will not be able to use the module's on-the-fly
665 table creation feature. If that cost is acceptable,
666 hand-create the tables as described in step
667 <xref linkend="Item.CreateTable" />
668 and use the following GRANT statement instead of the one
669 above:
670 </para>
286 <programlisting>mysql&gt; grant insert on apachelogs.* to loguser@my.apachemachine.com identified by 'l0gger';</programlisting> 671 <programlisting>mysql&gt; grant insert on apachelogs.* to loguser@my.apachemachine.com identified by 'l0gger';</programlisting>
287 </listitem> 672 </listitem>
288 <listitem id="Item.EnableLogging"> 673 <listitem id="Item.EnableLogging">
289 <para>Enable full logging of your <application>MySQL</application> daemon (at least temporarily for debugging purposes) if you don't do this already. Edit /etc/my.cnf and add the following line to your [mysqld] section:</para> 674 <para>
675 Enable full logging of your
676 <application>MySQL</application>
677 daemon (at least temporarily for debugging purposes) if you
678 don't do this already. Edit /etc/my.cnf and add the
679 following line to your [mysqld] section:
680 </para>
290 <programlisting>log=/var/log/mysql-messages</programlisting> 681 <programlisting>log=/var/log/mysql-messages</programlisting>
291 <para>Then restart <application>MySQL</application></para> 682 <para>
683 Then restart
684 <application>MySQL</application>
685 </para>
292 <programlisting># /etc/rc.d/init.d/mysql restart</programlisting> 686 <programlisting># /etc/rc.d/init.d/mysql restart</programlisting>
293 </listitem> 687 </listitem>
294 </orderedlist> 688 </orderedlist>
@@ -297,21 +691,52 @@ mysql&gt; source create_tables.sql</programlisting>
297 <title>A very basic logging setup in Apache</title> 691 <title>A very basic logging setup in Apache</title>
298 <orderedlist> 692 <orderedlist>
299 <listitem> 693 <listitem>
300 <para>Tell the module what database to use and the appropriate authentication information.</para> 694 <para>
301 <para>So, edit httpd.conf and insert the following lines somewhere after any LoadModule / AddModule statements. Make sure these statements are "global," i.e. not inside any VirtualHost stanza. You will also note that you are embedding a password in the file. Therefore you are advised to "chmod 660 httpd.conf" to prevent unauthorized regular users from viewing your database user and password.</para> 695 Tell the module what database to use and the appropriate
302 <para>Use the <application>MySQL</application> database called "apachelogs" running on "dbmachine.foo.com". Use username "loguser" and password "l0gg3r" to authenticate to the database. Permit the module create tables for us.</para> 696 authentication information.
697 </para>
698 <para>
699 So, edit httpd.conf and insert the following lines somewhere
700 after any LoadModule / AddModule statements. Make sure these
701 statements are "global," i.e. not inside any VirtualHost
702 stanza. You will also note that you are embedding a password
703 in the file. Therefore you are advised to "chmod 660
704 httpd.conf" to prevent unauthorized regular users from
705 viewing your database user and password.
706 </para>
707 <para>
708 Use the
709 <application>MySQL</application>
710 database called "apachelogs" running on "dbmachine.foo.com".
711 Use username "loguser" and password "l0gg3r" to authenticate
712 to the database. Permit the module create tables for us.
713 </para>
303 <example> 714 <example>
304 <title>Basic Example</title> 715 <title>Basic Example</title>
305 <programlisting>LogSQLLoginInfo mysql://loguser:l0gg3r@dbmachine.foo.com/apachelogs 716 <programlisting>LogSQLLoginInfo mysql://loguser:l0gg3r@dbmachine.foo.com/apachelogs
306LogSQLCreateTables on</programlisting> 717LogSQLCreateTables on</programlisting>
307 </example> 718 </example>
308 <para>If your database resides on localhost instead of another host, specify the MySQL server's socket file as follows:</para> 719 <para>
720 If your database resides on localhost instead of another
721 host, specify the MySQL server's socket file as follows:
722 </para>
309 <programlisting>LogSQLDBParam socketfile /your/path/to/mysql.sock</programlisting> 723 <programlisting>LogSQLDBParam socketfile /your/path/to/mysql.sock</programlisting>
310 <para>If your database is listening on a port other than 3306, specify the correct TCP port as follows:</para> 724 <para>
725 If your database is listening on a port other than 3306,
726 specify the correct TCP port as follows:
727 </para>
311 <programlisting>LogSQLDBParam port 1234</programlisting> 728 <programlisting>LogSQLDBParam port 1234</programlisting>
312 </listitem> 729 </listitem>
313 <listitem> 730 <listitem>
314 <para>The actual logging is set up on a virtual-host-by-host basis. So, skip down to the virtual host you want to set up. Instruct this virtual host to log entries to the table "access_log" by inserting a LogSQLTransferLogTable directive. (The LogSQLTransferLogTable directive is the minimum required to log -- other directives that you will learn about later simply tune the module's behavior.)</para> 731 <para>
732 The actual logging is set up on a virtual-host-by-host
733 basis. So, skip down to the virtual host you want to set up.
734 Instruct this virtual host to log entries to the table
735 "access_log" by inserting a LogSQLTransferLogTable
736 directive. (The LogSQLTransferLogTable directive is the
737 minimum required to log -- other directives that you will
738 learn about later simply tune the module's behavior.)
739 </para>
315 <programlisting>&lt;VirtualHost 1.2.3.4&gt; 740 <programlisting>&lt;VirtualHost 1.2.3.4&gt;
316 [snip] 741 [snip]
317 LogSQLTransferLogTable access_log 742 LogSQLTransferLogTable access_log
@@ -329,75 +754,206 @@ LogSQLCreateTables on</programlisting>
329 <title>Testing the basic setup</title> 754 <title>Testing the basic setup</title>
330 <orderedlist> 755 <orderedlist>
331 <listitem> 756 <listitem>
332 <para>Visit your web site in a browser to trigger some hits, then confirm that the entries are being successfully logged:</para> 757 <para>
333 <programlisting># mysql -hdbmachine.foo.com -umysqladmin -p -e "select * from access_log" apachelogs 758 Visit your web site in a browser to trigger some hits, then
759 confirm that the entries are being successfully logged:
760 </para>
761 <programlisting># mysql -hdbmachine.foo.com -umysqladmin -p -e "SELECT * FROM access_log" apachelogs
334Enter password:</programlisting> 762Enter password:</programlisting>
335 <para>Several lines of output should follow, corresponding to your hits on the site. You now have basic functionality. Don't disable your regular Apache logs until you feel comfortable that the database is behaving as you'd like and that things are going well. If you do not see any entries in the access_log, please consult section <xref linkend="FAQ.NothingLogged"/> of the FAQ on how to debug and fix the situation.</para> 763 <para>
764 Several lines of output should follow, corresponding to your
765 hits on the site. You now have basic functionality. Don't
766 disable your regular Apache logs until you feel comfortable
767 that the database is behaving as you'd like and that things
768 are going well. If you do not see any entries in the
769 access_log, please consult section
770 <xref linkend="FAQ.NothingLogged" />
771 of the FAQ on how to debug and fix the situation.
772 </para>
336 </listitem> 773 </listitem>
337 <listitem> 774 <listitem>
338 <para>You can now activate the advanced features of mod_log_sql, which are described in the next section.</para> 775 <para>
776 You can now activate the advanced features of mod_log_sql,
777 which are described in the next section.
778 </para>
339 </listitem> 779 </listitem>
340 </orderedlist> 780 </orderedlist>
341 </section> 781 </section>
342 <section> 782 <section>
343 <title>How to tune logging with run-time directives</title> 783 <title>How to tune logging with run-time directives</title>
344 <section> 784 <section tocstyle="fragment">
345 <title>Instructing the module what to log</title> 785 <title>Instructing the module what to log</title>
346 <para>The most basic directive for the module is LogSQLTransferLogFormat, which tells the module which information to send to the database; logging to the database will not take place without it. Place a LogSQLTransferLogFormat directive in the VirtualHost stanza of each virtual host that you want to activate.</para> 786 <para>
347 <para>After LogSQLTransferLogFormat you supply a string of characters that tell the module what information to log. In the configuration directive reference (section <xref linkend="Conf.LogSQLTransferLogFormat"/>) there is a table which clearly defines all the possible things to log. Let's say you want to log only the "request time," the "remote host," and the "request"; you'd use:</para> 787 The most basic directive for the module is
788 LogSQLTransferLogFormat, which tells the module which
789 information to send to the database; logging to the database
790 will not take place without it. Place a
791 LogSQLTransferLogFormat directive in the VirtualHost stanza of
792 each virtual host that you want to activate.
793 </para>
794 <para>
795 After LogSQLTransferLogFormat you supply a string of
796 characters that tell the module what information to log. In
797 the configuration directive reference (section
798 <xref linkend="Conf.LogSQLTransferLogFormat" />
799 ) there is a table which clearly defines all the possible
800 things to log. Let's say you want to log only the "request
801 time," the "remote host," and the "request"; you'd use:
802 </para>
348 <programlisting>LogSQLTransferLogFormat hUS</programlisting> 803 <programlisting>LogSQLTransferLogFormat hUS</programlisting>
349 <para>But a more appropriate string to use is</para> 804 <para>But a more appropriate string to use is</para>
350 <programlisting>LogSQLTransferLogFormat AbHhmRSsTUuv</programlisting> 805 <programlisting>LogSQLTransferLogFormat AbHhmRSsTUuv</programlisting>
351 <para>which logs all the information required to be compatible with the Combined Log Format (CLF).</para> 806 <para>
352 <para>If you don't choose to log everything that is available, that's fine. Fields in the unused columns in your table will simply contain NULL.</para> 807 which logs all the information required to be compatible with
353 <para>Some of the LogSQLTransferLogFormat characters require a little extra configuration:</para> 808 the Combined Log Format (CLF).
809 </para>
810 <para>
811 If you don't choose to log everything that is available,
812 that's fine. Fields in the unused columns in your table will
813 simply contain NULL.
814 </para>
815 <para>
816 Some of the LogSQLTransferLogFormat characters require a
817 little extra configuration:
818 </para>
354 <itemizedlist> 819 <itemizedlist>
355 <listitem> 820 <listitem>
356 <para>If you specify 'c' to indicate that you want to log the cookie value, you must also tell the module which cookie you mean by using LogSQLWhichCookie -- after all, there could be many cookies associated with a given request. Fail to specify LogSQLWhichCookie, and no cookie information at all will be logged. </para> 821 <para>
822 If you specify 'c' to indicate that you want to log the
823 cookie value, you must also tell the module which cookie
824 you mean by using LogSQLWhichCookie -- after all, there
825 could be many cookies associated with a given request.
826 Fail to specify LogSQLWhichCookie, and no cookie
827 information at all will be logged.
828 </para>
357 </listitem> 829 </listitem>
358 <listitem> 830 <listitem>
359 <para>If you specify 'M' to indicate that you want to log the machine ID, you must also tell the module this machine's identity using the LogSQLMachineID directive. Fail to specify LogSQLMachineID, and a simple '-' character will be logged in the machine_id column.</para> 831 <para>
832 If you specify 'M' to indicate that you want to log the
833 machine ID, you must also tell the module this machine's
834 identity using the LogSQLMachineID directive. Fail to
835 specify LogSQLMachineID, and a simple '-' character will
836 be logged in the machine_id column.
837 </para>
360 </listitem> 838 </listitem>
361 </itemizedlist> 839 </itemizedlist>
362 </section> 840 </section>
363 <section id="Sect.Ignore"> 841 <section id="Sect.Ignore">
364 <title id="Sect.Ignore.title">Instructing the module what NOT to log using filtering directives</title> 842 <title id="Sect.Ignore.title">
365 <para>One "accept" and two "ignore" directives allow you to fine-tune what the module should not log. These are very handy for keeping your database as uncluttered as possible and keeping your statistics free of unneeded numbers. Think of each one as a gatekeeper.</para> 843 Instructing the module what NOT to log using filtering
366 <para><emphasis>It is important to remember that each of these three directives is purely optional. mod_log_sql's default is to log everything.</emphasis></para> 844 directives
367 <para>When a request comes in, the contents of LogSQLRequestAccept are evaluated first. This optional, "blanket" directive lets you specify that only certain things are to be accepted for logging, and everything else discarded. Because it is evaluated before LogSQLRequestIgnore and LogSQLRemhostIgnore it can halt logging before those two filtering directives "get their chance." </para> 845 </title>
368 <para>Once a request makes it past LogSQLRequestAccept, it still can be excluded based on LogSQLRemhostIgnore and LogSQLRequestIgnore. A good way to use LogSQLRemhostIgnore is to prevent the module from logging the traffic that your internal hosts generate. LogSQLRequestIgnore is great for preventing things like requests for "favicon.ico" from cluttering up your database, as well as excluding the various requests that worms make, etc.</para> 846 <para>
369 <para>You can specify a series of strings after each directive. Do not use any type of globbing or regular-expression syntax -- each string is considered a match <emphasis>if it is a substring of the larger request or remote-host; the comarison is case-sensitive</emphasis>. This means that "LogSQLRemhostIgnore micro" will ignore requests from "microsoft.com," "microworld.net," "mymicroscope.org," etc. "LogSQLRequestIgnore gif" will instruct the module to ignore requests for "leftbar.gif," "bluedot.gif" and even "giftwrap.jpg" -- but "RED.GIF" and "Tree.Gif" would still get logged because of case sensitivity.</para> 847 One "accept" and two "ignore" directives allow you to
848 fine-tune what the module should not log. These are very handy
849 for keeping your database as uncluttered as possible and
850 keeping your statistics free of unneeded numbers. Think of
851 each one as a gatekeeper.
852 </para>
853 <para>
854 <emphasis>
855 It is important to remember that each of these three
856 directives is purely optional. mod_log_sql's default is to
857 log everything.
858 </emphasis>
859 </para>
860 <para>
861 When a request comes in, the contents of LogSQLRequestAccept
862 are evaluated first. This optional, "blanket" directive lets
863 you specify that only certain things are to be accepted for
864 logging, and everything else discarded. Because it is
865 evaluated before LogSQLRequestIgnore and LogSQLRemhostIgnore
866 it can halt logging before those two filtering directives "get
867 their chance."
868 </para>
869 <para>
870 Once a request makes it past LogSQLRequestAccept, it still can
871 be excluded based on LogSQLRemhostIgnore and
872 LogSQLRequestIgnore. A good way to use LogSQLRemhostIgnore is
873 to prevent the module from logging the traffic that your
874 internal hosts generate. LogSQLRequestIgnore is great for
875 preventing things like requests for "favicon.ico" from
876 cluttering up your database, as well as excluding the various
877 requests that worms make, etc.
878 </para>
879 <para>
880 You can specify a series of strings after each directive. Do
881 not use any type of globbing or regular-expression syntax --
882 each string is considered a match
883 <emphasis>
884 if it is a substring of the larger request or remote-host;
885 the comarison is case-sensitive
886 </emphasis>
887 . This means that "LogSQLRemhostIgnore micro" will ignore
888 requests from "microsoft.com," "microworld.net,"
889 "mymicroscope.org," etc. "LogSQLRequestIgnore gif" will
890 instruct the module to ignore requests for "leftbar.gif,"
891 "bluedot.gif" and even "giftwrap.jpg" -- but "RED.GIF" and
892 "Tree.Gif" would still get logged because of case sensitivity.
893 </para>
370 <para>A summary of the decision flow:</para> 894 <para>A summary of the decision flow:</para>
371 <orderedlist> 895 <orderedlist>
372 <listitem> 896 <listitem>
373 <para>If LogSQLRequestAccept exists and a request does not match anything in that list, it is discarded.</para> 897 <para>
898 If LogSQLRequestAccept exists and a request does not match
899 anything in that list, it is discarded.
900 </para>
374 </listitem> 901 </listitem>
375 <listitem> 902 <listitem>
376 <para>If a request matches anything in the LogSQLRequestIgnore list, it is discarded.</para> 903 <para>
904 If a request matches anything in the LogSQLRequestIgnore
905 list, it is discarded.
906 </para>
377 </listitem> 907 </listitem>
378 <listitem> 908 <listitem>
379 <para>If a reqiest matches anything in the LogSQLRemhostIgnore list, it is discarded.</para> 909 <para>
910 If a reqiest matches anything in the LogSQLRemhostIgnore
911 list, it is discarded.
912 </para>
380 </listitem> 913 </listitem>
381 <listitem> 914 <listitem>
382 <para>Otherwise the request is logged.</para> 915 <para>Otherwise the request is logged.</para>
383 </listitem> 916 </listitem>
384 </orderedlist> 917 </orderedlist>
385 <para>This means that you can have a series of directives similar to the following:</para> 918 <para>
919 This means that you can have a series of directives similar to
920 the following:
921 </para>
386 <programlisting>LogSQLRequestAccept .html .gif .jpg 922 <programlisting>LogSQLRequestAccept .html .gif .jpg
387LogSQLRequestIgnore statistics.html bluedot.jpg</programlisting> 923LogSQLRequestIgnore statistics.html bluedot.jpg</programlisting>
388 <para>So the first line instructs the module to only log files with html, gif and jpg suffixes; requests for "formail.cgi" and "shopping-cart.pl" will never be considered for logging. ("LeftArrow.JPG" will also never be considered for logging -- remember, the comparison is case sensitive.) The second line prunes the list further -- you never want to log requests for those two objects.</para> 924 <para>
925 So the first line instructs the module to only log files with
926 html, gif and jpg suffixes; requests for "formail.cgi" and
927 "shopping-cart.pl" will never be considered for logging.
928 ("LeftArrow.JPG" will also never be considered for logging --
929 remember, the comparison is case sensitive.) The second line
930 prunes the list further -- you never want to log requests for
931 those two objects.
932 </para>
389 <note role="tip"> 933 <note role="tip">
390 <itemizedlist> 934 <itemizedlist>
391 <listitem> 935 <listitem>
392 <para>If you want to match all the hosts in your domain such as "host1.corp.foo.com" and "server.dmz.foo.com", simply specify:</para> 936 <para>
937 If you want to match all the hosts in your domain such
938 as "host1.corp.foo.com" and "server.dmz.foo.com", simply
939 specify:
940 </para>
393 <programlisting>LogSQLRemhostIgnore foo.com</programlisting> 941 <programlisting>LogSQLRemhostIgnore foo.com</programlisting>
394 </listitem> 942 </listitem>
395 <listitem> 943 <listitem>
396 <para>A great way to catch the vast majority of worm-attack requests and prevent them from being logged is to specify:</para> 944 <para>
945 A great way to catch the vast majority of worm-attack
946 requests and prevent them from being logged is to
947 specify:
948 </para>
397 <programlisting>LogSQLRequestIgnore root.exe cmd.exe default.ida</programlisting> 949 <programlisting>LogSQLRequestIgnore root.exe cmd.exe default.ida</programlisting>
398 </listitem> 950 </listitem>
399 <listitem> 951 <listitem>
400 <para>To prevent the logging of requests for common graphic types, make sure to put a '.' before the suffix to avoid matches that you didn't intend:</para> 952 <para>
953 To prevent the logging of requests for common graphic
954 types, make sure to put a '.' before the suffix to avoid
955 matches that you didn't intend:
956 </para>
401 <programlisting>LogSQLRequestIgnore .gif .jpg</programlisting> 957 <programlisting>LogSQLRequestIgnore .gif .jpg</programlisting>
402 </listitem> 958 </listitem>
403 </itemizedlist> 959 </itemizedlist>
@@ -406,45 +962,118 @@ LogSQLRequestIgnore statistics.html bluedot.jpg</programlisting>
406 </section> 962 </section>
407 <section> 963 <section>
408 <title>Advanced logging scenarios</title> 964 <title>Advanced logging scenarios</title>
409 <section> 965 <section tocstyle="fragment">
410 <title>Using the module in an ISP environment</title> 966 <title>Using the module in an ISP environment</title>
411 <para>mod_log_sql has three basic tiers of operation:</para> 967 <para>mod_log_sql has three basic tiers of operation:</para>
412 <orderedlist> 968 <orderedlist>
413 <listitem> 969 <listitem>
414 <para>The administrator creates all necessary tables by hand and configures each Apache VirtualHost by hand. (LogSQLCreateTables Off)</para> 970 <para>
971 The administrator creates all necessary tables by hand and
972 configures each Apache VirtualHost by hand.
973 (LogSQLCreateTables Off)
974 </para>
415 </listitem> 975 </listitem>
416 <listitem> 976 <listitem>
417 <para>The module is permitted to create necessary tables on-the-fly, but the administrator configures each Apache VirtualHost by hand. (LogSQLCreateTables On)</para> 977 <para>
978 The module is permitted to create necessary tables
979 on-the-fly, but the administrator configures each Apache
980 VirtualHost by hand. (LogSQLCreateTables On)
981 </para>
418 </listitem> 982 </listitem>
419 <listitem> 983 <listitem>
420 <para>The module is permitted to create all necessary tables and to make intelligent, on-the-fly configuration of each VirtualHost. (LogSQLMassVirtualHosting On)</para> 984 <para>
985 The module is permitted to create all necessary tables and
986 to make intelligent, on-the-fly configuration of each
987 VirtualHost. (LogSQLMassVirtualHosting On)
988 </para>
421 </listitem> 989 </listitem>
422 </orderedlist> 990 </orderedlist>
423 <para>Many users are happy to use the module in its most minimal form: they hand-create any necessary tables (using "create_tables.sql"), and they configure each VirtualHost by hand to suit their needs. However, some administrators need extra features due to a large and growing number of VirtualHosts. The LogSQLMassVirtualHosting directive activates module capabilities that make it far easier to manage an ISP environment, or any situation characterized by a large and varying number of virtual servers.</para> 991 <para>
992 Many users are happy to use the module in its most minimal
993 form: they hand-create any necessary tables (using
994 "create_tables.sql"), and they configure each VirtualHost by
995 hand to suit their needs. However, some administrators need
996 extra features due to a large and growing number of
997 VirtualHosts. The LogSQLMassVirtualHosting directive activates
998 module capabilities that make it far easier to manage an ISP
999 environment, or any situation characterized by a large and
1000 varying number of virtual servers.
1001 </para>
424 <itemizedlist> 1002 <itemizedlist>
425 <listitem> 1003 <listitem>
426 <para>the on-the-fly table creation feature is activated automatically</para> 1004 <para>
1005 the on-the-fly table creation feature is activated
1006 automatically
1007 </para>
427 </listitem> 1008 </listitem>
428 <listitem> 1009 <listitem>
429 <para>the transfer log table name is dynamically set from the virtual host's name (example: a virtual host "www.grubbybaby.com" gets logged to table "access_www_grubbybaby_com")</para> 1010 <para>
1011 the transfer log table name is dynamically set from the
1012 virtual host's name (example: a virtual host
1013 "www.grubbybaby.com" gets logged to table
1014 "access_www_grubbybaby_com")
1015 </para>
430 </listitem> 1016 </listitem>
431 </itemizedlist> 1017 </itemizedlist>
432 <para>There are numerous benefits. The admin will not need to create new tables for every new VirtualHost. (Although the admin will still need to drop the tables of virtual hosts that are removed.) The admin will not need to set LogSQLTransferLogTable for each virtual host -- it will be configured automatically based on the host's name. Because each virtual host will log to its own segregated table, data about one virtual server will segregate from others; an admin can grant users access to the tables they need, and they will be unable to view data about another user's virtual host.</para> 1018 <para>
433 <para>In an ISP scenario the admin is likely to have a cluster of many front-end webservers logging to a back-end database. mod_log_sql has a feature that permits analysis of how well the web servers are loadbalancing: the LogSQLMachineID directive. The administrator uses this directive to assign a unique identifier to each machine in the web cluster, e.g. "LogSQLMachineID web01," "LogSQLMachineID web02," etc. Used in conjunction with the 'M' character in LogSQLTransferLogFormat, each entry in the SQL log will include the machine ID of the machine that created the entry. This permits the administrator to count the entries made by each particular machine and thereby analyze the front-end loadbalancing algorithm.</para> 1019 There are numerous benefits. The admin will not need to create
1020 new tables for every new VirtualHost. (Although the admin will
1021 still need to drop the tables of virtual hosts that are
1022 removed.) The admin will not need to set
1023 LogSQLTransferLogTable for each virtual host -- it will be
1024 configured automatically based on the host's name. Because
1025 each virtual host will log to its own segregated table, data
1026 about one virtual server will segregate from others; an admin
1027 can grant users access to the tables they need, and they will
1028 be unable to view data about another user's virtual host.
1029 </para>
1030 <para>
1031 In an ISP scenario the admin is likely to have a cluster of
1032 many front-end webservers logging to a back-end database.
1033 mod_log_sql has a feature that permits analysis of how well
1034 the web servers are loadbalancing: the LogSQLMachineID
1035 directive. The administrator uses this directive to assign a
1036 unique identifier to each machine in the web cluster, e.g.
1037 "LogSQLMachineID web01," "LogSQLMachineID web02," etc. Used in
1038 conjunction with the 'M' character in LogSQLTransferLogFormat,
1039 each entry in the SQL log will include the machine ID of the
1040 machine that created the entry. This permits the administrator
1041 to count the entries made by each particular machine and
1042 thereby analyze the front-end loadbalancing algorithm.
1043 </para>
434 </section> 1044 </section>
435 <section id="Sect.MultiTable"> 1045 <section id="Sect.MultiTable">
436 <title id="Sect.MultiTable.title">Logging many-to-one data in separate tables</title> 1046 <title id="Sect.MultiTable.title">
437 <para>A given HTTP request can have a one-to-many relationship with certain kinds of data. For example, a single HTTP request can have 4 cookies, 3 headers and 5 "mod_gzip" notes associated with it. mod_log_sql is capable of logging these relationships due to the elegance of SQL relational data.</para> 1047 Logging many-to-one data in separate tables
438 <para>You already have a single table containing access requests. One of the columns in that table is 'id' which is intended to contain the unique request ID supplied by the standard Apache module mod_unique_id -- all you need to do is compile in that module and employ the LogSQLTransferLogFormat character 'I'. Thereafter, each request gets a unique ID that can be thought of as a primary key within the database, useful for joining multiple tables. So let's envision several new tables: a notes table, a cookies table, and a table for inbound and outbound headers.</para> 1048 </title>
1049 <para>
1050 A given HTTP request can have a one-to-many relationship with
1051 certain kinds of data. For example, a single HTTP request can
1052 have 4 cookies, 3 headers and 5 "mod_gzip" notes associated
1053 with it. mod_log_sql is capable of logging these relationships
1054 due to the elegance of SQL relational data.
1055 </para>
1056 <para>
1057 You already have a single table containing access requests.
1058 One of the columns in that table is 'id' which is intended to
1059 contain the unique request ID supplied by the standard Apache
1060 module mod_unique_id -- all you need to do is compile in that
1061 module and employ the LogSQLTransferLogFormat character 'I'.
1062 Thereafter, each request gets a unique ID that can be thought
1063 of as a primary key within the database, useful for joining
1064 multiple tables. So let's envision several new tables: a notes
1065 table, a cookies table, and a table for inbound and outbound
1066 headers.
1067 </para>
439 <table> 1068 <table>
440 <title>&lt;tblAcc&gt;access_log</title> 1069 <title>&lt;tblAcc&gt;access_log</title>
441 <tgroup cols="6"> 1070 <tgroup cols="6">
442 <colspec colname="1"/> 1071 <colspec colname="1" />
443 <colspec colname="2"/> 1072 <colspec colname="2" />
444 <colspec colname="3"/> 1073 <colspec colname="3" />
445 <colspec colname="4"/> 1074 <colspec colname="4" />
446 <colspec colname="5" colwidth="40"/> 1075 <colspec colname="5" colwidth="40" />
447 <colspec colname="6" colwidth="70"/> 1076 <colspec colname="6" colwidth="70" />
448 <thead> 1077 <thead>
449 <row> 1078 <row>
450 <entry colname="1">id</entry> 1079 <entry colname="1">id</entry>
@@ -470,9 +1099,9 @@ LogSQLRequestIgnore statistics.html bluedot.jpg</programlisting>
470 <table> 1099 <table>
471 <title>&lt;tblNotes&gt;notes_log</title> 1100 <title>&lt;tblNotes&gt;notes_log</title>
472 <tgroup cols="3"> 1101 <tgroup cols="3">
473 <colspec colname="1"/> 1102 <colspec colname="1" />
474 <colspec colname="2"/> 1103 <colspec colname="2" />
475 <colspec colname="3" colwidth="30"/> 1104 <colspec colname="3" colwidth="30" />
476 <thead> 1105 <thead>
477 <row> 1106 <row>
478 <entry colname="1">id</entry> 1107 <entry colname="1">id</entry>
@@ -497,9 +1126,9 @@ LogSQLRequestIgnore statistics.html bluedot.jpg</programlisting>
497 <table> 1126 <table>
498 <title>&lt;tblHdr&gt;headers_log</title> 1127 <title>&lt;tblHdr&gt;headers_log</title>
499 <tgroup cols="3"> 1128 <tgroup cols="3">
500 <colspec colname="1" colnum="1"/> 1129 <colspec colname="1" colnum="1" />
501 <colspec colname="2" colnum="2"/> 1130 <colspec colname="2" colnum="2" />
502 <colspec colname="3" colnum="3"/> 1131 <colspec colname="3" colnum="3" />
503 <thead> 1132 <thead>
504 <row> 1133 <row>
505 <entry colname="1">id</entry> 1134 <entry colname="1">id</entry>
@@ -531,16 +1160,28 @@ LogSQLRequestIgnore statistics.html bluedot.jpg</programlisting>
531 </tbody> 1160 </tbody>
532 </tgroup> 1161 </tgroup>
533 </table> 1162 </table>
534 <para>We have a certain request, and its unique ID is "PPIDskBRH30AAGPtAsg". Within each separate table will be multiple entries with that request ID: several cookie entries, several header entries, etc. As you can see in tables [tblAcc], [tblNotes] and [tblHdr], you have a one-to-many relationship for request PPIDskBRH30AAGPtAsg: that one access has two associated notes and four associated headers. You can extract this data easily using the power of SQL's "select" statement and table joins. To see the notes associated with a particular request:</para> 1163 <para>
535 <programlisting>select a.remote_host, a.request_uri, n.item, n.val from access_log a, notes_log n 1164 We have a certain request, and its unique ID is
536where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting> 1165 "PPIDskBRH30AAGPtAsg". Within each separate table will be
1166 multiple entries with that request ID: several cookie entries,
1167 several header entries, etc. As you can see in tables
1168 [tblAcc], [tblNotes] and [tblHdr], you have a one-to-many
1169 relationship for request PPIDskBRH30AAGPtAsg: that one access
1170 has two associated notes and four associated headers. You can
1171 extract this data easily using the power of SQL's "select"
1172 statement and table joins. To see the notes associated with a
1173 particular request:
1174 </para>
1175 <programlisting>SELECT a.remote_host, a.request_uri, n.item, n.val
1176FROM access_log a JOIN notes_log n ON a.id=n.id
1177WHERE a.id='PPIDskBRH30AAGPtAsg';</programlisting>
537 <table> 1178 <table>
538 <title>access_log joined to notes_log</title> 1179 <title>access_log joined to notes_log</title>
539 <tgroup cols="4"> 1180 <tgroup cols="4">
540 <colspec colname="1"/> 1181 <colspec colname="1" />
541 <colspec colname="2"/> 1182 <colspec colname="2" />
542 <colspec colname="3"/> 1183 <colspec colname="3" />
543 <colspec colname="4" colwidth="30"/> 1184 <colspec colname="4" colwidth="30" />
544 <thead> 1185 <thead>
545 <row> 1186 <row>
546 <entry colname="1">remote_host</entry> 1187 <entry colname="1">remote_host</entry>
@@ -565,64 +1206,179 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
565 </tbody> 1206 </tbody>
566 </tgroup> 1207 </tgroup>
567 </table> 1208 </table>
568 <para>Naturally you can craft similar statements for the outboud headers, inbound headers and cookies, all of which can live in separate tables. Your statements are limited in power only by your skill with SQL.</para> 1209 <para>
569 <para>In order to use this capability of mod_log_sql, you must do several things.</para> 1210 Naturally you can craft similar statements for the outboud
1211 headers, inbound headers and cookies, all of which can live in
1212 separate tables. Your statements are limited in power only by
1213 your skill with SQL.
1214 </para>
1215 <para>
1216 In order to use this capability of mod_log_sql, you must do
1217 several things.
1218 </para>
570 <itemizedlist> 1219 <itemizedlist>
571 <listitem> 1220 <listitem>
572 <para>Compile mod_unique_id into Apache (statically or as a DSO). mod_log_sql employs the unique request ID that mod_unique_id provides in order to key between the separate tables. You can still log the data without mod_unqiue_id, but it will be completely uncorrelated and you will have no way to discern any meaning.</para> 1221 <para>
1222 Compile mod_unique_id into Apache (statically or as a
1223 DSO). mod_log_sql employs the unique request ID that
1224 mod_unique_id provides in order to key between the
1225 separate tables. You can still log the data without
1226 mod_unqiue_id, but it will be completely uncorrelated and
1227 you will have no way to discern any meaning.
1228 </para>
573 </listitem> 1229 </listitem>
574 <listitem> 1230 <listitem>
575 <para>Create the appropriate tables. This will be done for you if you permit mod_log_sql to create its own tables using LogSQLCreateTables On, or if you use the enclosed "create_tables.sql" script.</para> 1231 <para>
1232 Create the appropriate tables. This will be done for you
1233 if you permit mod_log_sql to create its own tables using
1234 LogSQLCreateTables On, or if you use the enclosed
1235 "create_tables.sql" script.
1236 </para>
576 </listitem> 1237 </listitem>
577 <listitem> 1238 <listitem>
578 <para>Create a SQL index on the "id" column. Without this index, table joins will be deathly slow. I recommend you consult the MySQL documentation on the proper way to create a column index if you are not familiar with this operation.</para> 1239 <para>
1240 Create a SQL index on the "id" column. Without this index,
1241 table joins will be deathly slow. I recommend you consult
1242 the MySQL documentation on the proper way to create a
1243 column index if you are not familiar with this operation.
1244 </para>
579 </listitem> 1245 </listitem>
580 <listitem> 1246 <listitem>
581 <para>Within each appropriate VirtualHost stanza, use the LogSQLWhich* and LogSQL*LogTable directives to tell the module what and where to log the data. In the following example, I have overridden the name for the notes table whereas I have left the other table names at their defaults. I have then specified the cookies, headers and notes that interest me. (And as you can see, these directives do not require me to add any characters to LogSQLTransferLogTable.)</para> 1247 <para>
1248 Within each appropriate VirtualHost stanza, use the
1249 LogSQLWhich* and LogSQL*LogTable directives to tell the
1250 module what and where to log the data. In the following
1251 example, I have overridden the name for the notes table
1252 whereas I have left the other table names at their
1253 defaults. I have then specified the cookies, headers and
1254 notes that interest me. (And as you can see, these
1255 directives do not require me to add any characters to
1256 LogSQLTransferLogTable.)
1257 </para>
582 <programlisting>&lt;VirtualHost 216.231.36.128&gt; 1258 <programlisting>&lt;VirtualHost 216.231.36.128&gt;
583 (snip) 1259 (snip)
584 LogSQLNotesLogTable notestable 1260 LogSQLNotesLogTable notestable
585 LogSQLWhichCookies bluecookie redcookie greencookie 1261 LogSQLWhichCookies bluecookie redcookie greencookie
586 LogSQLWhichNotes mod_gzip_result mod_gzip_compression_ratio 1262 LogSQLWhichNotes mod_gzip_result mod_gzip_compression_ratio
587 LogSQLWhichHeadersOut Expires Content-Type Cache-Control 1263 LogSQLWhichHeadersOut Expires Content-Type Cache-Control
588 LogSQLWhichHeadersIn User-Agent Accept-Encoding Host 1264 LogSQLWhichHeadersIn User-Agent Accept-Encoding Host
589 (snip) 1265 (snip)
590&lt;/VirtualHost&gt;</programlisting> 1266&lt;/VirtualHost&gt;</programlisting>
591 </listitem> 1267 </listitem>
592 </itemizedlist> 1268 </itemizedlist>
593 </section> 1269 </section>
594 <section> 1270 <section>
595 <title>Using the same database for production and test</title> 1271 <title>Using the same database for production and test</title>
596 <para>Although sub-optimal, it is not uncommon to use the same back-end database for the "production" webservers as well as the "test" webservers (budgetary constraints, rack-space limits, etc.). Furthermore, an administrator in this situation may be unable to use LogSQLRemhostIgnore to exclude requests from the test servers -- perhaps the generated entries are genuinely useful for analytical or QA purposes, but their value after analysis is minimal.</para> 1272 <para>
597 <para>It is wasteful and potentially confusing to permit this internal test data to clutter the database, and a solution to the problem is the proper use of the LogSQLMachineID directive. Assume a scenario where the production webservers have IDs like "web01," "web02," and so on -- and the test webservers have IDs like "test01," "test02," etc. Because entries in the log database are distinguished by their source machine, an administrator may purge unneeded test data from the access log as follows:</para> 1273 Although sub-optimal, it is not uncommon to use the same
598 <programlisting>delete from access_log where machine_id like 'test%';</programlisting> 1274 back-end database for the "production" webservers as well as
1275 the "test" webservers (budgetary constraints, rack-space
1276 limits, etc.). Furthermore, an administrator in this situation
1277 may be unable to use LogSQLRemhostIgnore to exclude requests
1278 from the test servers -- perhaps the generated entries are
1279 genuinely useful for analytical or QA purposes, but their
1280 value after analysis is minimal.
1281 </para>
1282 <para>
1283 It is wasteful and potentially confusing to permit this
1284 internal test data to clutter the database, and a solution to
1285 the problem is the proper use of the LogSQLMachineID
1286 directive. Assume a scenario where the production webservers
1287 have IDs like "web01," "web02," and so on -- and the test
1288 webservers have IDs like "test01," "test02," etc. Because
1289 entries in the log database are distinguished by their source
1290 machine, an administrator may purge unneeded test data from
1291 the access log as follows:
1292 </para>
1293 <programlisting>DELETE FROM access_log WHERE machine_id like 'test%';</programlisting>
599 </section> 1294 </section>
600 <section id="Sect.DelayedInsert"> 1295 <section id="Sect.DelayedInsert">
601 <title id="Sect.DelayedInsert.title">Optimizing for a busy database</title> 1296 <title id="Sect.DelayedInsert.title">
602 <para>A busy MySQL database will have SELECT statements running concurrently with INSERT and UPDATE statements. A long-running SELECT can in certain circumstances block INSERTs and therefore block mod_log_sql. A workaround is to enable mod_log_sql for "delayed inserts," which are described as follows in the MySQL documentation.</para> 1297 Optimizing for a busy database
603 <para>The DELAYED option for the INSERT statement is a MySQL-specific option that is very useful if you have clients that can't wait for the INSERT to complete. This is a common problem when you use MySQL for logging and you also periodically run SELECT and UPDATE statements that take a long time to complete. DELAYED was introduced in MySQL Version 3.22.15. It is a MySQL extension to ANSI SQL92.</para> 1298 </title>
604 <para>INSERT DELAYED only works with ISAM and MyISAM tables. Note that as MyISAM tables supports concurrent SELECT and INSERT, if there is no free blocks in the middle of the data file, you very seldom need to use INSERT DELAYED with MyISAM. </para> 1299 <para>
605 <para>When you use INSERT DELAYED, the client will get an OK at once and the row will be inserted when the table is not in use by any other thread.</para> 1300 A busy MySQL database will have SELECT statements running
606 <para>Another major benefit of using INSERT DELAYED is that inserts from many clients are bundled together and written in one block. This is much faster than doing many separate inserts. </para> 1301 concurrently with INSERT and UPDATE statements. A long-running
1302 SELECT can in certain circumstances block INSERTs and
1303 therefore block mod_log_sql. A workaround is to enable
1304 mod_log_sql for "delayed inserts," which are described as
1305 follows in the MySQL documentation.
1306 </para>
1307 <para>
1308 The DELAYED option for the INSERT statement is a
1309 MySQL-specific option that is very useful if you have clients
1310 that can't wait for the INSERT to complete. This is a common
1311 problem when you use MySQL for logging and you also
1312 periodically run SELECT and UPDATE statements that take a long
1313 time to complete. DELAYED was introduced in MySQL Version
1314 3.22.15. It is a MySQL extension to ANSI SQL92.
1315 </para>
1316 <para>
1317 INSERT DELAYED only works with ISAM and MyISAM tables. Note
1318 that as MyISAM tables supports concurrent SELECT and INSERT,
1319 if there is no free blocks in the middle of the data file, you
1320 very seldom need to use INSERT DELAYED with MyISAM.
1321 </para>
1322 <para>
1323 When you use INSERT DELAYED, the client will get an OK at once
1324 and the row will be inserted when the table is not in use by
1325 any other thread.
1326 </para>
1327 <para>
1328 Another major benefit of using INSERT DELAYED is that inserts
1329 from many clients are bundled together and written in one
1330 block. This is much faster than doing many separate inserts.
1331 </para>
607 <para>The general disadvantages of delayed inserts are</para> 1332 <para>The general disadvantages of delayed inserts are</para>
608 <orderedlist> 1333 <orderedlist>
609 <listitem> 1334 <listitem>
610 <para>The queued rows are only stored in memory until they are inserted into the table. If mysqld dies unexpectedly, any queued rows that were not written to disk are lost.</para> 1335 <para>
1336 The queued rows are only stored in memory until they are
1337 inserted into the table. If mysqld dies unexpectedly, any
1338 queued rows that were not written to disk are lost.
1339 </para>
611 </listitem> 1340 </listitem>
612 <listitem> 1341 <listitem>
613 <para>There is additional overhead for the server to handle a separate thread for each table on which you use INSERT DELAYED.</para> 1342 <para>
1343 There is additional overhead for the server to handle a
1344 separate thread for each table on which you use INSERT
1345 DELAYED.
1346 </para>
614 </listitem> 1347 </listitem>
615 </orderedlist> 1348 </orderedlist>
616 <note role="warning"> 1349 <note role="warning">
617 <para>The MySQL documentation concludes, "This means that you should only use INSERT DELAYED when you are really sure you need it!" Furthermore, the current state of error return from a failed INSERT DELAYED seems to be in flux, and may behave in unpredictable ways between different MySQL versions. See FAQ entry <xref linkend="FAQ.DelayedInsert"/> -- you have been warned.</para> 1350 <para>
1351 The MySQL documentation concludes, "This means that you
1352 should only use INSERT DELAYED when you are really sure you
1353 need it!" Furthermore, the current state of error return
1354 from a failed INSERT DELAYED seems to be in flux, and may
1355 behave in unpredictable ways between different MySQL
1356 versions. See FAQ entry
1357 <xref linkend="FAQ.DelayedInsert" />
1358 -- you have been warned.
1359 </para>
618 </note> 1360 </note>
619 <para>If you are experiencing issues which could be solved by delayed inserts, then set LogSqlDelayedInserts On in the <filename>httpd.conf</filename>. All regular INSERT statements are now INSERT DELAYED, and you should see no more blocking of the module.</para> 1361 <para>
1362 If you are experiencing issues which could be solved by
1363 delayed inserts, then set LogSqlDelayedInserts On in the
1364 <filename>httpd.conf</filename>
1365 . All regular INSERT statements are now INSERT DELAYED, and
1366 you should see no more blocking of the module.
1367 </para>
620 </section> 1368 </section>
621 </section> 1369 </section>
622 <section id="Sect.ConfigReference"> 1370 <section id="Sect.ConfigReference">
623 <title id="Sect.ConfigReference.title">Configuration Directive Reference</title> 1371 <title id="Sect.ConfigReference.title">
624 <para>It is imperative that you understand which directives are used only once in the main server config, and which are used inside VirtualHost stanzas and therefore multiple times within httpd.conf. The "context" listed with each entry informs you of this.</para> 1372 Configuration Directive Reference
625 <section> 1373 </title>
1374 <para>
1375 It is imperative that you understand which directives are used
1376 only once in the main server config, and which are used inside
1377 VirtualHost stanzas and therefore multiple times within
1378 httpd.conf. The "context" listed with each entry informs you of
1379 this.
1380 </para>
1381 <section tocstyle="fragment">
626 <title>DataBase Configuration</title> 1382 <title>DataBase Configuration</title>
627 <variablelist> 1383 <variablelist>
628 <varlistentry> 1384 <varlistentry>
@@ -630,53 +1386,89 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
630 <listitem> 1386 <listitem>
631 <cmdsynopsis> 1387 <cmdsynopsis>
632 <command>LogSQLLoginInfo</command> 1388 <command>LogSQLLoginInfo</command>
633 <arg choice="req"><replaceable>connection URI</replaceable></arg> 1389 <arg choice="req">
1390 <replaceable>connection URI</replaceable>
1391 </arg>
634 </cmdsynopsis> 1392 </cmdsynopsis>
635 <simpara>Example: LogSQLLoginInfo mysql://logwriter:passw0rd@foobar.baz.com/Apache_log</simpara> 1393 <simpara>
1394 Example: LogSQLLoginInfo
1395 mysql://logwriter:passw0rd@foobar.baz.com/Apache_log
1396 </simpara>
636 <simpara>Context: main server config</simpara> 1397 <simpara>Context: main server config</simpara>
637 <para>Defines the basic connection URI to connect to the database with. The format of the connection URI is</para> 1398 <para>
638 <simpara>driver://username[:password]@hostname[:port]/database</simpara> 1399 Defines the basic connection URI to connect to the
1400 database with. The format of the connection URI is
1401 </para>
1402 <simpara>
1403 driver://username[:password]@hostname[:port]/database
1404 </simpara>
639 <variablelist> 1405 <variablelist>
640 <varlistentry> 1406 <varlistentry>
641 <term>driver</term> 1407 <term>driver</term>
642 <listitem> 1408 <listitem>
643 <simpara>The database driver to use (mysql, pgsql, etc..)</simpara> 1409 <simpara>
1410 The database driver to use (mysql, pgsql, etc..)
1411 </simpara>
644 </listitem> 1412 </listitem>
645 </varlistentry> 1413 </varlistentry>
646 <varlistentry> 1414 <varlistentry>
647 <term>username</term> 1415 <term>username</term>
648 <listitem> 1416 <listitem>
649 <simpara>The database username to login with INSERT privileges on the logging table defined in LogSQLtransferLogTable.</simpara> 1417 <simpara>
1418 The database username to login with INSERT
1419 privileges on the logging table defined in
1420 LogSQLtransferLogTable.
1421 </simpara>
650 </listitem> 1422 </listitem>
651 </varlistentry> 1423 </varlistentry>
652 <varlistentry> 1424 <varlistentry>
653 <term>password</term> 1425 <term>password</term>
654 <listitem> 1426 <listitem>
655 <simpara>The password to use for username, and can be omitted if there is no password.</simpara> 1427 <simpara>
1428 The password to use for username, and can be
1429 omitted if there is no password.
1430 </simpara>
656 </listitem> 1431 </listitem>
657 </varlistentry> 1432 </varlistentry>
658 <varlistentry> 1433 <varlistentry>
659 <term>hostname</term> 1434 <term>hostname</term>
660 <listitem> 1435 <listitem>
661 <simpara>The hostname or Ip address of the Database machine, ans is simple "localhost" if the database lives on the same machine as Apache.</simpara> 1436 <simpara>
1437 The hostname or Ip address of the Database
1438 machine, ans is simple "localhost" if the database
1439 lives on the same machine as Apache.
1440 </simpara>
662 </listitem> 1441 </listitem>
663 </varlistentry> 1442 </varlistentry>
664 <varlistentry> 1443 <varlistentry>
665 <term>port</term> 1444 <term>port</term>
666 <listitem> 1445 <listitem>
667 <simpara>Port on hostname to connect to the Database, if not specified use the default port for the database.</simpara> 1446 <simpara>
1447 Port on hostname to connect to the Database, if
1448 not specified use the default port for the
1449 database.
1450 </simpara>
668 </listitem> 1451 </listitem>
669 </varlistentry> 1452 </varlistentry>
670 <varlistentry> 1453 <varlistentry>
671 <term>database</term> 1454 <term>database</term>
672 <listitem> 1455 <listitem>
673 <simpara>The database to connect to on the server.</simpara> 1456 <simpara>
1457 The database to connect to on the server.
1458 </simpara>
674 </listitem> 1459 </listitem>
675 </varlistentry> 1460 </varlistentry>
676 </variablelist> 1461 </variablelist>
677 <note> 1462 <note>
678 <para>This is defined only once in the <filename>httpd.conf</filename> file.</para> 1463 <para>
679 <para>This directive Must be defined for logging to be enabled.</para> 1464 This is defined only once in the
1465 <filename>httpd.conf</filename>
1466 file.
1467 </para>
1468 <para>
1469 This directive Must be defined for logging to be
1470 enabled.
1471 </para>
680 </note> 1472 </note>
681 </listitem> 1473 </listitem>
682 </varlistentry> 1474 </varlistentry>
@@ -685,14 +1477,81 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
685 <listitem> 1477 <listitem>
686 <cmdsynopsis sepchar=" "> 1478 <cmdsynopsis sepchar=" ">
687 <command>LogSQLDBParam</command> 1479 <command>LogSQLDBParam</command>
688 <arg choice="req"><replaceable>parameter-name</replaceable></arg> 1480 <arg choice="req">
689 <arg choice="req"><replaceable>value</replaceable></arg> 1481 <replaceable>parameter-name</replaceable>
1482 </arg>
1483 <arg choice="req">
1484 <replaceable>value</replaceable>
1485 </arg>
690 </cmdsynopsis> 1486 </cmdsynopsis>
691 <simpara>Example: LogSQLDBParam socketfile /var/lib/mysql/mysql.socket</simpara> 1487 <simpara>
1488 Example: LogSQLDBParam socketfile
1489 /var/lib/mysql/mysql.socket
1490 </simpara>
692 <simpara>Context: main server config</simpara> 1491 <simpara>Context: main server config</simpara>
693 <para>This is the new method of specifying Database connection credentials and settings. This is used to define database driver specific options. For a list of options read the documentation for each specific database driver.</para> 1492 <para>
1493 This is the new method of specifying Database connection
1494 credentials and settings. This is used to define
1495 database driver specific options. For a list of options
1496 read the documentation for each specific database
1497 driver.
1498 </para>
1499 <table>
1500 <title>MySQL Driver parameters</title>
1501 <tgroup cols="5">
1502 <colspec colname="1" colnum="1" />
1503 <colspec colname="2" colnum="2" />
1504 <colspec colname="3" colnum="3" />
1505 <thead>
1506 <row>
1507 <entry colname="1">Parameter</entry>
1508 <entry colname="2">Meaning</entry>
1509 <entry colname="3">Default</entry>
1510 </row>
1511 </thead>
1512 <tbody>
1513 <row>
1514 <entry colname="1">hostname</entry>
1515 <entry colname="2">MySQL Server hostname</entry>
1516 <entry colname="3">none (use LogSQLLoginInfo to set)</entry>
1517 </row>
1518 <row>
1519 <entry colname="1">username</entry>
1520 <entry colname="2">The username to log in with</entry>
1521 <entry colname="3">none (use LogSQLLoginInfo to set)</entry>
1522 </row>
1523 <row>
1524 <entry colname="1">password</entry>
1525 <entry colname="2">The password to use</entry>
1526 <entry colname="3">none (use LogSQLLoginInfo to set)</entry>
1527 </row>
1528 <row>
1529 <entry colname="1">database</entry>
1530 <entry colname="2">Which database to connect to</entry>
1531 <entry colname="3">none (use LogSQLLoginInfo to set)</entry>
1532 </row>
1533 <row>
1534 <entry colname="1">port</entry>
1535 <entry colname="2">The TCP port to connect to the MySQL server over</entry>
1536 <entry colname="3">3306 (use LogSQLLoginInfo to set)</entry>
1537 </row>
1538 <row>
1539 <entry colname="1">socketfile</entry>
1540 <entry colname="2">The MySQL Unix socket file to use</entry>
1541 <entry colname="3">none</entry>
1542 </row>
1543 <row>
1544 <entry colname="1">tabletype</entry>
1545 <entry colname="2">MySQL Table Engine to use</entry>
1546 <entry colname="3">MySQL server default</entry>
1547 </row>
1548 </tbody>
1549 </tgroup>
1550 </table>
694 <note> 1551 <note>
695 <para>Each parameter-name may only be defined once.</para> 1552 <para>
1553 Each parameter-name may only be defined once.
1554 </para>
696 </note> 1555 </note>
697 </listitem> 1556 </listitem>
698 </varlistentry> 1557 </varlistentry>
@@ -706,10 +1565,32 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
706 <simpara>Example: LogSQLCreateTables On</simpara> 1565 <simpara>Example: LogSQLCreateTables On</simpara>
707 <simpara>Default: Off</simpara> 1566 <simpara>Default: Off</simpara>
708 <simpara>Context: main server config</simpara> 1567 <simpara>Context: main server config</simpara>
709 <para>mod_log_sql has the ability to create its tables on-the-fly. The advantage to this is convenience: you don't have to execute any SQL by hand to prepare the table. This is especially helpful for people with lots of virtual hosts (who should also see the LogSQLMassVirtualHosting directive).</para> 1568 <para>
710 <para>There is a slight disadvantage: if you wish to activate this feature, then the userid specified in LogSQLLoginInfo must have CREATE privileges on the database. In an absolutely paranoid, locked-down situation you may only want to grant your mod_log_sql user INSERT privileges on the database; in that situation you are unable to take advantage of LogSQLCreateTables. But most people -- even the very security-conscious -- will find that granting CREATE on the logging database is reasonable.</para> 1569 mod_log_sql has the ability to create its tables
1570 on-the-fly. The advantage to this is convenience: you
1571 don't have to execute any SQL by hand to prepare the
1572 table. This is especially helpful for people with lots
1573 of virtual hosts (who should also see the
1574 LogSQLMassVirtualHosting directive).
1575 </para>
1576 <para>
1577 There is a slight disadvantage: if you wish to activate
1578 this feature, then the userid specified in
1579 LogSQLLoginInfo must have CREATE privileges on the
1580 database. In an absolutely paranoid, locked-down
1581 situation you may only want to grant your mod_log_sql
1582 user INSERT privileges on the database; in that
1583 situation you are unable to take advantage of
1584 LogSQLCreateTables. But most people -- even the very
1585 security-conscious -- will find that granting CREATE on
1586 the logging database is reasonable.
1587 </para>
711 <note> 1588 <note>
712 <para>This is defined only once in the <filename>httpd.conf</filename> file.</para> 1589 <para>
1590 This is defined only once in the
1591 <filename>httpd.conf</filename>
1592 file.
1593 </para>
713 </note> 1594 </note>
714 </listitem> 1595 </listitem>
715 </varlistentry> 1596 </varlistentry>
@@ -723,10 +1604,25 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
723 <simpara>Example: LogForcePreserve On</simpara> 1604 <simpara>Example: LogForcePreserve On</simpara>
724 <simpara>Default: Off</simpara> 1605 <simpara>Default: Off</simpara>
725 <simpara>Context: main server config</simpara> 1606 <simpara>Context: main server config</simpara>
726 <para>You may need to perform debugging on your database and specifically want mod_log_sql to make no attempts to log to it. This directive instructs the module to send all its log entries directly to the preserve file and to make no database INSERT attempts.</para> 1607 <para>
727 <para>This is presumably a directive for temporary use only; it could be dangerous if you set it and forget it, as all your entries will simply pile up in the preserve file.</para> 1608 You may need to perform debugging on your database and
1609 specifically want mod_log_sql to make no attempts to log
1610 to it. This directive instructs the module to send all
1611 its log entries directly to the preserve file and to
1612 make no database INSERT attempts.
1613 </para>
1614 <para>
1615 This is presumably a directive for temporary use only;
1616 it could be dangerous if you set it and forget it, as
1617 all your entries will simply pile up in the preserve
1618 file.
1619 </para>
728 <note> 1620 <note>
729 <para>This is defined only once in the <filename>httpd.conf</filename> file.</para> 1621 <para>
1622 This is defined only once in the
1623 <filename>httpd.conf</filename>
1624 file.
1625 </para>
730 </note> 1626 </note>
731 </listitem> 1627 </listitem>
732 </varlistentry> 1628 </varlistentry>
@@ -740,10 +1636,21 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
740 <simpara>Example: LogDisablePreserve On</simpara> 1636 <simpara>Example: LogDisablePreserve On</simpara>
741 <simpara>Default: Off</simpara> 1637 <simpara>Default: Off</simpara>
742 <simpara>Context; main server config</simpara> 1638 <simpara>Context; main server config</simpara>
743 <para>This option can be enabled to completely disable the preserve file fail back. This may be useful for servers where the file-system is read-only.</para> 1639 <para>
744 <para>If the database is not available those log entries will be lost.</para> 1640 This option can be enabled to completely disable the
1641 preserve file fail back. This may be useful for servers
1642 where the file-system is read-only.
1643 </para>
1644 <para>
1645 If the database is not available those log entries will
1646 be lost.
1647 </para>
745 <note> 1648 <note>
746 <para>This is defined only once in the <filename>httpd.conf</filename> file.</para> 1649 <para>
1650 This is defined only once in the
1651 <filename>httpd.conf</filename>
1652 file.
1653 </para>
747 </note> 1654 </note>
748 </listitem> 1655 </listitem>
749 </varlistentry> 1656 </varlistentry>
@@ -756,9 +1663,22 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
756 </cmdsynopsis> 1663 </cmdsynopsis>
757 <simpara>Example: LogSQLMachineID web01</simpara> 1664 <simpara>Example: LogSQLMachineID web01</simpara>
758 <simpara>Context: main server config</simpara> 1665 <simpara>Context: main server config</simpara>
759 <para>If you have a farm of webservers then you may wish to know which particular machine made each entry; this is useful for analyzing your load-balancing methodology. LogSQLMachineID permits you to distinguish each machine's entries if you assign each machine its own LogSQLMachineID: for example, the first webserver gets ``LogSQLMachineID web01,'' the second gets ``LogSQLMachineID web02,'' etc.</para> 1666 <para>
1667 If you have a farm of webservers then you may wish to
1668 know which particular machine made each entry; this is
1669 useful for analyzing your load-balancing methodology.
1670 LogSQLMachineID permits you to distinguish each
1671 machine's entries if you assign each machine its own
1672 LogSQLMachineID: for example, the first webserver gets
1673 ``LogSQLMachineID web01,'' the second gets
1674 ``LogSQLMachineID web02,'' etc.
1675 </para>
760 <note> 1676 <note>
761 <para>This is defined only once in the <filename>httpd.conf</filename> file.</para> 1677 <para>
1678 This is defined only once in the
1679 <filename>httpd.conf</filename>
1680 file.
1681 </para>
762 </note> 1682 </note>
763 </listitem> 1683 </listitem>
764 </varlistentry> 1684 </varlistentry>
@@ -767,16 +1687,58 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
767 <listitem> 1687 <listitem>
768 <cmdsynopsis sepchar=" "> 1688 <cmdsynopsis sepchar=" ">
769 <command>LogSQLPreserveFile</command> 1689 <command>LogSQLPreserveFile</command>
770 <arg choice="req"><replaceable>filename</replaceable></arg> 1690 <arg choice="req">
1691 <replaceable>filename</replaceable>
1692 </arg>
771 </cmdsynopsis> 1693 </cmdsynopsis>
772 <simpara>Example: LogSQLPreserveFile offline-preserve</simpara> 1694 <simpara>
1695 Example: LogSQLPreserveFile offline-preserve
1696 </simpara>
773 <simpara>Default: /tmp/sql-preserve</simpara> 1697 <simpara>Default: /tmp/sql-preserve</simpara>
774 <simpara>Context: virtual host</simpara> 1698 <simpara>Context: virtual host</simpara>
775 <para>mod_log_sql writes queries to this local preserve file in the event that it cannot reach the database, and thus ensures that your high-availability web frontend does not lose logs during a temporary database outage. This could happen for a number of reasons: the database goes offline, the network breaks, etc. You will not lose entries since the module has this backup. The file consists of a series of SQL statements that can be imported into your database at your convenience; furthermore, because the SQL queries contain the access timestamps you do not need to worry about out-of-order data after the import, which is done in a simple manner:</para> 1699 <para>
1700 mod_log_sql writes queries to this local preserve file
1701 in the event that it cannot reach the database, and thus
1702 ensures that your high-availability web frontend does
1703 not lose logs during a temporary database outage. This
1704 could happen for a number of reasons: the database goes
1705 offline, the network breaks, etc. You will not lose
1706 entries since the module has this backup. The file
1707 consists of a series of SQL statements that can be
1708 imported into your database at your convenience;
1709 furthermore, because the SQL queries contain the access
1710 timestamps you do not need to worry about out-of-order
1711 data after the import, which is done in a simple manner:
1712 </para>
776 <programlisting format="linespecific"># mysql -uadminuser -p mydbname &lt; /tmp/sql-preserve</programlisting> 1713 <programlisting format="linespecific"># mysql -uadminuser -p mydbname &lt; /tmp/sql-preserve</programlisting>
777 <para>If you do not define LogSQLPreserveFile then all virtual servers will log to the same default preserve file (<filename>/tmp/sql-preserve</filename>). You can redefine this on a virtual-host basis in order to segregate your preserve files if you desire. Note that segregation is not usually necessary, as the SQL statements that are written to the preserve file already distinguish between different virtual hosts if you include the 'v' character in your LogSQLTransferLogFormat directive. It is only necessary to segregate preserve-files by virualhost if you also segregate access logs by virtualhost.</para> 1714 <para>
778 <para>The module will log to Apache's ErrorLog when it notices a database outage, and upon database return. You will therefore know when the preserve file is being used, although it is your responsibility to import the file.</para> 1715 If you do not define LogSQLPreserveFile then all virtual
779 <para>The file does not need to be created in advance. It is safe to remove or rename the file without interrupting Apache, as the module closes the filehandle immediately after completing the write. The file is created with the user &amp; group ID of the running Apache process (e.g. 'nobody' on many Linux distributions).</para> 1716 servers will log to the same default preserve file (
1717 <filename>/tmp/sql-preserve</filename>
1718 ). You can redefine this on a virtual-host basis in
1719 order to segregate your preserve files if you desire.
1720 Note that segregation is not usually necessary, as the
1721 SQL statements that are written to the preserve file
1722 already distinguish between different virtual hosts if
1723 you include the 'v' character in your
1724 LogSQLTransferLogFormat directive. It is only necessary
1725 to segregate preserve-files by virualhost if you also
1726 segregate access logs by virtualhost.
1727 </para>
1728 <para>
1729 The module will log to Apache's ErrorLog when it notices
1730 a database outage, and upon database return. You will
1731 therefore know when the preserve file is being used,
1732 although it is your responsibility to import the file.
1733 </para>
1734 <para>
1735 The file does not need to be created in advance. It is
1736 safe to remove or rename the file without interrupting
1737 Apache, as the module closes the filehandle immediately
1738 after completing the write. The file is created with the
1739 user &amp; group ID of the running Apache process (e.g.
1740 'nobody' on many Linux distributions).
1741 </para>
780 </listitem> 1742 </listitem>
781 </varlistentry> 1743 </varlistentry>
782 </variablelist> 1744 </variablelist>
@@ -789,14 +1751,33 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
789 <listitem> 1751 <listitem>
790 <cmdsynopsis sepchar=" "> 1752 <cmdsynopsis sepchar=" ">
791 <command>LogSQLTransferLogTable</command> 1753 <command>LogSQLTransferLogTable</command>
792 <arg choice="req"><replaceable>table-name</replaceable></arg> 1754 <arg choice="req">
1755 <replaceable>table-name</replaceable>
1756 </arg>
793 </cmdsynopsis> 1757 </cmdsynopsis>
794 <simpara>Example: LogSQLTransferLogTable access_log_table</simpara> 1758 <simpara>
1759 Example: LogSQLTransferLogTable access_log_table
1760 </simpara>
795 <simpara>Context: virtual host</simpara> 1761 <simpara>Context: virtual host</simpara>
796 <para>Defines which table is used for logging of Apache's transfers; this is analogous to Apache's TransferLog directive. table-name must be a valid table within the database defined in the LogSQLLoginInfo connection URI.</para> 1762 <para>
797 <para>This directive is <emphasis>not</emphasis> necessary if you declare LogSQLMassVirtualHosting On, since that directive activates dynamically-named tables. If you attempt to use LogSqlTransferlogTable at the same time a warning will be logged and it will be ignored, since LogSQLMassVirtualHosting takes priority.</para> 1763 Defines which table is used for logging of Apache's
1764 transfers; this is analogous to Apache's TransferLog
1765 directive. table-name must be a valid table within the
1766 database defined in the LogSQLLoginInfo connection URI.
1767 </para>
1768 <para>
1769 This directive is
1770 <emphasis>not</emphasis>
1771 necessary if you declare LogSQLMassVirtualHosting On,
1772 since that directive activates dynamically-named tables.
1773 If you attempt to use LogSqlTransferlogTable at the same
1774 time a warning will be logged and it will be ignored,
1775 since LogSQLMassVirtualHosting takes priority.
1776 </para>
798 <note> 1777 <note>
799 <para>Requires unless LogSQLMassVirtualHosting is set to On</para> 1778 <para>
1779 Requires unless LogSQLMassVirtualHosting is set to On
1780 </para>
800 </note> 1781 </note>
801 </listitem> 1782 </listitem>
802 </varlistentry> 1783 </varlistentry>
@@ -805,14 +1786,30 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
805 <listitem> 1786 <listitem>
806 <cmdsynopsis sepchar=" "> 1787 <cmdsynopsis sepchar=" ">
807 <command>LogSQLCookieLogTable</command> 1788 <command>LogSQLCookieLogTable</command>
808 <arg choice="req"><replaceable></replaceable>table-name</arg> 1789 <arg choice="req">
1790 <replaceable></replaceable>
1791 table-name
1792 </arg>
809 </cmdsynopsis> 1793 </cmdsynopsis>
810 <simpara>Example: LogSQLCookieLogTable cookie_log</simpara> 1794 <simpara>
1795 Example: LogSQLCookieLogTable cookie_log
1796 </simpara>
811 <simpara>Default: cookies</simpara> 1797 <simpara>Default: cookies</simpara>
812 <simpara>Context: virtual host</simpara> 1798 <simpara>Context: virtual host</simpara>
813 <para>Defines which table is used for logging of cookies. Working in conjunction with LogSQLWhichCookies, you can log many of each request's associated cookies to a separate table. For meaningful data retrieval the cookie table is keyed to the access table by the unique request ID supplied by the standard Apache module mod_unique_id.</para> 1799 <para>
1800 Defines which table is used for logging of cookies.
1801 Working in conjunction with LogSQLWhichCookies, you can
1802 log many of each request's associated cookies to a
1803 separate table. For meaningful data retrieval the cookie
1804 table is keyed to the access table by the unique request
1805 ID supplied by the standard Apache module mod_unique_id.
1806 </para>
814 <note> 1807 <note>
815 <para>You must create the table (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to "on".</para> 1808 <para>
1809 You must create the table (see create-tables.sql,
1810 included in the package), or LogSQLCreateTables must
1811 be set to "on".
1812 </para>
816 </note> 1813 </note>
817 </listitem> 1814 </listitem>
818 </varlistentry> 1815 </varlistentry>
@@ -821,14 +1818,30 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
821 <listitem> 1818 <listitem>
822 <cmdsynopsis sepchar=" "> 1819 <cmdsynopsis sepchar=" ">
823 <command>LogSQLHeadersInLogTable</command> 1820 <command>LogSQLHeadersInLogTable</command>
824 <arg choice="req"><replaceable>table-name</replaceable></arg> 1821 <arg choice="req">
1822 <replaceable>table-name</replaceable>
1823 </arg>
825 </cmdsynopsis> 1824 </cmdsynopsis>
826 <simpara>Example: LogSQLHeadersInLogTable headers</simpara> 1825 <simpara>
1826 Example: LogSQLHeadersInLogTable headers
1827 </simpara>
827 <simpara>Default: headers_in</simpara> 1828 <simpara>Default: headers_in</simpara>
828 <simpara>Context: virtual host</simpara> 1829 <simpara>Context: virtual host</simpara>
829 <para>Defines which table is used for logging of inbound headers. Working in conjunction with LogSQLWhichHeadersIn, you can log many of each request's associated headers to a separate table. For meaningful data retrieval the headers table is keyed to the access table by the unique request ID supplied by the standard Apache module mod_unique_id.</para> 1830 <para>
1831 Defines which table is used for logging of inbound
1832 headers. Working in conjunction with
1833 LogSQLWhichHeadersIn, you can log many of each request's
1834 associated headers to a separate table. For meaningful
1835 data retrieval the headers table is keyed to the access
1836 table by the unique request ID supplied by the standard
1837 Apache module mod_unique_id.
1838 </para>
830 <note> 1839 <note>
831 <para>Note that you must create the table (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to "on".</para> 1840 <para>
1841 Note that you must create the table (see
1842 create-tables.sql, included in the package), or
1843 LogSQLCreateTables must be set to "on".
1844 </para>
832 </note> 1845 </note>
833 </listitem> 1846 </listitem>
834 </varlistentry> 1847 </varlistentry>
@@ -837,14 +1850,30 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
837 <listitem> 1850 <listitem>
838 <cmdsynopsis sepchar=" "> 1851 <cmdsynopsis sepchar=" ">
839 <command>LogSQLHeadersOutLogTable</command> 1852 <command>LogSQLHeadersOutLogTable</command>
840 <arg choice="req"><replaceable>table-name</replaceable></arg> 1853 <arg choice="req">
1854 <replaceable>table-name</replaceable>
1855 </arg>
841 </cmdsynopsis> 1856 </cmdsynopsis>
842 <simpara>Example: LogSQLHeadersOutLogTable headers</simpara> 1857 <simpara>
1858 Example: LogSQLHeadersOutLogTable headers
1859 </simpara>
843 <simpara>Default: headers_out</simpara> 1860 <simpara>Default: headers_out</simpara>
844 <simpara>Context: virtual host</simpara> 1861 <simpara>Context: virtual host</simpara>
845 <para>Defines which table is used for logging of outbound headers. Working in conjunction with LogSQLWhichHeadersOut, you can log many of each request's associated headers to a separate table. For meaningful data retrieval the headers table is keyed to the access table by the unique request ID supplied by the standard Apache module mod_unique_id.</para> 1862 <para>
1863 Defines which table is used for logging of outbound
1864 headers. Working in conjunction with
1865 LogSQLWhichHeadersOut, you can log many of each
1866 request's associated headers to a separate table. For
1867 meaningful data retrieval the headers table is keyed to
1868 the access table by the unique request ID supplied by
1869 the standard Apache module mod_unique_id.
1870 </para>
846 <note> 1871 <note>
847 <para>Note that you must create the table (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to "on".</para> 1872 <para>
1873 Note that you must create the table (see
1874 create-tables.sql, included in the package), or
1875 LogSQLCreateTables must be set to "on".
1876 </para>
848 </note> 1877 </note>
849 </listitem> 1878 </listitem>
850 </varlistentry> 1879 </varlistentry>
@@ -853,14 +1882,27 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
853 <listitem> 1882 <listitem>
854 <cmdsynopsis sepchar=" "> 1883 <cmdsynopsis sepchar=" ">
855 <command>LogSQLNotesLogTable</command> 1884 <command>LogSQLNotesLogTable</command>
856 <arg choice="req"><replaceable>table-name</replaceable></arg> 1885 <arg choice="req">
1886 <replaceable>table-name</replaceable>
1887 </arg>
857 </cmdsynopsis> 1888 </cmdsynopsis>
858 <simpara>Example: LogSQLNotesLogTable notes-log</simpara> 1889 <simpara>Example: LogSQLNotesLogTable notes-log</simpara>
859 <simpara>Default: notes</simpara> 1890 <simpara>Default: notes</simpara>
860 <simpara>Context: virtual_host</simpara> 1891 <simpara>Context: virtual_host</simpara>
861 <para>Defines which table is used for logging of notes. Working in conjunction with LogSQLWhichNotes, you can log many of each request's associated notes to a separate table. For meaningful data retrieval the notes table is keyed to the access table by the unique request ID supplied by the standard Apache module mod_unique_id.</para> 1892 <para>
1893 Defines which table is used for logging of notes.
1894 Working in conjunction with LogSQLWhichNotes, you can
1895 log many of each request's associated notes to a
1896 separate table. For meaningful data retrieval the notes
1897 table is keyed to the access table by the unique request
1898 ID supplied by the standard Apache module mod_unique_id.
1899 </para>
862 <note> 1900 <note>
863 <para>This table must be created (see create-tables.sql included in the package), or LogSQLCreateTables must be set to 'On'.</para> 1901 <para>
1902 This table must be created (see create-tables.sql
1903 included in the package), or LogSQLCreateTables must
1904 be set to 'On'.
1905 </para>
864 </note> 1906 </note>
865 </listitem> 1907 </listitem>
866 </varlistentry> 1908 </varlistentry>
@@ -874,21 +1916,49 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
874 <simpara>Example: LogSQLMassVirtualHosting On</simpara> 1916 <simpara>Example: LogSQLMassVirtualHosting On</simpara>
875 <simpara>Default: Off</simpara> 1917 <simpara>Default: Off</simpara>
876 <simpara>Context: main server config</simpara> 1918 <simpara>Context: main server config</simpara>
877 <para>If you administer a site hosting many, many virtual hosts then this option will appeal to you. If you turn on LogSQLMassVirtualHosting then several things happen:</para> 1919 <para>
1920 If you administer a site hosting many, many virtual
1921 hosts then this option will appeal to you. If you turn
1922 on LogSQLMassVirtualHosting then several things happen:
1923 </para>
878 <itemizedlist> 1924 <itemizedlist>
879 <listitem> 1925 <listitem>
880 <para>the on-the-fly table creation feature is activated automatically</para> 1926 <para>
1927 the on-the-fly table creation feature is activated
1928 automatically
1929 </para>
881 </listitem> 1930 </listitem>
882 <listitem> 1931 <listitem>
883 <para>the transfer log table name is dynamically set from the virtual host's name after stripping out SQL-unfriendly characters (example: a virtual host www.grubbybaby.com gets logged to table access_www_grubbybaby_com)</para> 1932 <para>
1933 the transfer log table name is dynamically set from
1934 the virtual host's name after stripping out
1935 SQL-unfriendly characters (example: a virtual host
1936 www.grubbybaby.com gets logged to table
1937 access_www_grubbybaby_com)
1938 </para>
884 </listitem> 1939 </listitem>
885 <listitem> 1940 <listitem>
886 <para>which, in turn, means that each virtual host logs to its own segregated table. Because there is no data shared between virtual servers you can grant your users access to the tables they need; they will be unable to view others' data.</para> 1941 <para>
1942 which, in turn, means that each virtual host logs to
1943 its own segregated table. Because there is no data
1944 shared between virtual servers you can grant your
1945 users access to the tables they need; they will be
1946 unable to view others' data.
1947 </para>
887 </listitem> 1948 </listitem>
888 </itemizedlist> 1949 </itemizedlist>
889 <para>This is a huge boost in convenience for sites with many virtual servers. Activating LogSQLMassVirtualHosting obviates the need to create every virtual server's table and provides more granular security possibilities.</para> 1950 <para>
1951 This is a huge boost in convenience for sites with many
1952 virtual servers. Activating LogSQLMassVirtualHosting
1953 obviates the need to create every virtual server's table
1954 and provides more granular security possibilities.
1955 </para>
890 <note> 1956 <note>
891 <para>This is defined only once in the <filename>httpd.conf</filename> file.</para> 1957 <para>
1958 This is defined only once in the
1959 <filename>httpd.conf</filename>
1960 file.
1961 </para>
892 </note> 1962 </note>
893 </listitem> 1963 </listitem>
894 </varlistentry> 1964 </varlistentry>
@@ -898,24 +1968,33 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
898 <title>Configuring What Is logged</title> 1968 <title>Configuring What Is logged</title>
899 <variablelist> 1969 <variablelist>
900 <varlistentry id="Conf.LogSQLTransferLogFormat"> 1970 <varlistentry id="Conf.LogSQLTransferLogFormat">
901 <term>LogSQLTransferLogFormat </term> 1971 <term>LogSQLTransferLogFormat</term>
902 <listitem> 1972 <listitem>
903 <cmdsynopsis sepchar=" "> 1973 <cmdsynopsis sepchar=" ">
904 <command>LogSQLTransferLogFormat</command> 1974 <command>LogSQLTransferLogFormat</command>
905 <arg choice="req"><replaceable>format-string</replaceable></arg> 1975 <arg choice="req">
1976 <replaceable>format-string</replaceable>
1977 </arg>
906 </cmdsynopsis> 1978 </cmdsynopsis>
907 <simpara>Example: LogSQLTransferLogFormat huSUTv</simpara> 1979 <simpara>Example: LogSQLTransferLogFormat huSUTv</simpara>
908 <simpara>Default: AbHhmRSsTUuv</simpara> 1980 <simpara>Default: AbHhmRSsTUuv</simpara>
909 <simpara>Context: virtual host</simpara> 1981 <simpara>Context: virtual host</simpara>
910 <para>Each character in the format-string defines an attribute of the request that you wish to log. The default logs the information required to create Combined Log Format logs, plus several extras. Here is the full list of allowable keys, which sometimes resemble their Apache counterparts, but do not always:</para> 1982 <para>
1983 Each character in the format-string defines an attribute
1984 of the request that you wish to log. The default logs
1985 the information required to create Combined Log Format
1986 logs, plus several extras. Here is the full list of
1987 allowable keys, which sometimes resemble their Apache
1988 counterparts, but do not always:
1989 </para>
911 <table> 1990 <table>
912 <title>Core LogFormat parameters</title> 1991 <title>Core LogFormat parameters</title>
913 <tgroup cols="5"> 1992 <tgroup cols="5">
914 <colspec colname="1" colnum="1"/> 1993 <colspec colname="1" colnum="1" />
915 <colspec colname="2" colnum="2"/> 1994 <colspec colname="2" colnum="2" />
916 <colspec colname="3" colnum="3"/> 1995 <colspec colname="3" colnum="3" />
917 <colspec colname="4" colnum="4"/> 1996 <colspec colname="4" colnum="4" />
918 <colspec colname="5" colnum="5"/> 1997 <colspec colname="5" colnum="5" />
919 <thead> 1998 <thead>
920 <row> 1999 <row>
921 <entry colname="1">Symbol</entry> 2000 <entry colname="1">Symbol</entry>
@@ -931,14 +2010,18 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
931 <entry colname="2">User Agent</entry> 2010 <entry colname="2">User Agent</entry>
932 <entry colname="3">agent</entry> 2011 <entry colname="3">agent</entry>
933 <entry colname="4">varchar(255)</entry> 2012 <entry colname="4">varchar(255)</entry>
934 <entry colname="5">Mozilla/4.0 (compat; MSIE 6.0; Windows)</entry> 2013 <entry colname="5">
2014 Mozilla/4.0 (compat; MSIE 6.0; Windows)
2015 </entry>
935 </row> 2016 </row>
936 <row> 2017 <row>
937 <entry colname="1">a</entry> 2018 <entry colname="1">a</entry>
938 <entry colname="2">CGi request arguments</entry> 2019 <entry colname="2">CGi request arguments</entry>
939 <entry colname="3">request_args</entry> 2020 <entry colname="3">request_args</entry>
940 <entry colname="4">varchar(255)</entry> 2021 <entry colname="4">varchar(255)</entry>
941 <entry colname="5">user=Smith&amp;cart=1231&amp;item=532</entry> 2022 <entry colname="5">
2023 user=Smith&amp;cart=1231&amp;item=532
2024 </entry>
942 </row> 2025 </row>
943 <row> 2026 <row>
944 <entry colname="1">b</entry> 2027 <entry colname="1">b</entry>
@@ -948,11 +2031,16 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
948 <entry colname="5">32561</entry> 2031 <entry colname="5">32561</entry>
949 </row> 2032 </row>
950 <row> 2033 <row>
951 <entry colname="1">c<xref linkend="Foot.LogCookie"/></entry> 2034 <entry colname="1">
2035 c
2036 <xref linkend="Foot.LogCookie" xrefstyle="footer" />
2037 </entry>
952 <entry colname="2">Text of cookie</entry> 2038 <entry colname="2">Text of cookie</entry>
953 <entry colname="3">cookie</entry> 2039 <entry colname="3">cookie</entry>
954 <entry colname="4">varchar(255)</entry> 2040 <entry colname="4">varchar(255)</entry>
955 <entry colname="5">Apache=sdyn.fooonline.net 1300102700823</entry> 2041 <entry colname="5">
2042 Apache=sdyn.fooonline.net 1300102700823
2043 </entry>
956 </row> 2044 </row>
957 <row> 2045 <row>
958 <entry>f</entry> 2046 <entry>f</entry>
@@ -991,7 +2079,10 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
991 </row> 2079 </row>
992 <row> 2080 <row>
993 <entry>M</entry> 2081 <entry>M</entry>
994 <entry>Machine ID<xref linkend="Foot.MachineID"/></entry> 2082 <entry>
2083 Machine ID
2084 <xref linkend="Foot.MachineID" xrefstyle="footer" />
2085 </entry>
995 <entry>machine_id</entry> 2086 <entry>machine_id</entry>
996 <entry>varchar(25)</entry> 2087 <entry>varchar(25)</entry>
997 <entry>web01</entry> 2088 <entry>web01</entry>
@@ -1022,7 +2113,9 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1022 <entry>Referer</entry> 2113 <entry>Referer</entry>
1023 <entry>referer</entry> 2114 <entry>referer</entry>
1024 <entry>varchar(255)</entry> 2115 <entry>varchar(255)</entry>
1025 <entry>http://www.biglinks4u.com/linkpage.html</entry> 2116 <entry>
2117 http://www.biglinks4u.com/linkpage.html
2118 </entry>
1026 </row> 2119 </row>
1027 <row> 2120 <row>
1028 <entry>r</entry> 2121 <entry>r</entry>
@@ -1033,12 +2126,21 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1033 </row> 2126 </row>
1034 <row> 2127 <row>
1035 <entry>S</entry> 2128 <entry>S</entry>
1036 <entry>Time of request in UNIX time_t format</entry> 2129 <entry>
2130 Time of request in UNIX time_t format
2131 </entry>
1037 <entry>time_stamp</entry> 2132 <entry>time_stamp</entry>
1038 <entry>int unsigned</entry> 2133 <entry>int unsigned</entry>
1039 <entry>1005598029</entry> 2134 <entry>1005598029</entry>
1040 </row> 2135 </row>
1041 <row> 2136 <row>
2137 <entry>s</entry>
2138 <entry>HTTP Response Code Status</entry>
2139 <entry>status</entry>
2140 <entry>smallint</entry>
2141 <entry>200</entry>
2142 </row>
2143 <row>
1042 <entry>T</entry> 2144 <entry>T</entry>
1043 <entry>Seconds to service request</entry> 2145 <entry>Seconds to service request</entry>
1044 <entry>request_duration</entry> 2146 <entry>request_duration</entry>
@@ -1050,7 +2152,7 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1050 <entry>Time of request in human format</entry> 2152 <entry>Time of request in human format</entry>
1051 <entry>request_time</entry> 2153 <entry>request_time</entry>
1052 <entry>char(28)</entry> 2154 <entry>char(28)</entry>
1053 <entry> [02/Dec/2001:15:01:26 -0800]</entry> 2155 <entry>[02/Dec/2001:15:01:26 -0800]</entry>
1054 </row> 2156 </row>
1055 <row> 2157 <row>
1056 <entry>U</entry> 2158 <entry>U</entry>
@@ -1075,7 +2177,10 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1075 </row> 2177 </row>
1076 <row> 2178 <row>
1077 <entry>V</entry> 2179 <entry>V</entry>
1078 <entry>requested Virtual host name (mass virtualhosting)</entry> 2180 <entry>
2181 requested Virtual host name (mass
2182 virtualhosting)
2183 </entry>
1079 <entry>virtual_host</entry> 2184 <entry>virtual_host</entry>
1080 <entry>varchar(255)</entry> 2185 <entry>varchar(255)</entry>
1081 <entry>www.foobar.org</entry> 2186 <entry>www.foobar.org</entry>
@@ -1084,17 +2189,23 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1084 </tgroup> 2189 </tgroup>
1085 </table> 2190 </table>
1086 <note> 2191 <note>
1087 <simpara id="Foot.LogCookie">[1] You must also specify LogSQLWhichCookie for this to take effect.</simpara> 2192 <simpara id="Foot.LogCookie">
1088 <simpara id="Foot.MachineID">[2] You must also specify LogSQLmachineID for this to take effect.</simpara> 2193 [1] You must also specify LogSQLWhichCookie for this
2194 to take effect.
2195 </simpara>
2196 <simpara id="Foot.MachineID">
2197 [2] You must also specify LogSQLmachineID for this to
2198 take effect.
2199 </simpara>
1089 </note> 2200 </note>
1090 <table> 2201 <table>
1091 <title>SSL LogFormat Parameters</title> 2202 <title>SSL LogFormat Parameters</title>
1092 <tgroup cols="5"> 2203 <tgroup cols="5">
1093 <colspec colname="1" colnum="1"/> 2204 <colspec colname="1" colnum="1" />
1094 <colspec colname="2" colnum="2"/> 2205 <colspec colname="2" colnum="2" />
1095 <colspec colname="3" colnum="3"/> 2206 <colspec colname="3" colnum="3" />
1096 <colspec colname="4" colnum="4"/> 2207 <colspec colname="4" colnum="4" />
1097 <colspec colname="5" colnum="5"/> 2208 <colspec colname="5" colnum="5" />
1098 <thead> 2209 <thead>
1099 <row> 2210 <row>
1100 <entry colname="1">Symbol</entry> 2211 <entry colname="1">Symbol</entry>
@@ -1114,14 +2225,18 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1114 </row> 2225 </row>
1115 <row> 2226 <row>
1116 <entry colname="1">q</entry> 2227 <entry colname="1">q</entry>
1117 <entry colname="2">Keysize of the SSL connection</entry> 2228 <entry colname="2">
2229 Keysize of the SSL connection
2230 </entry>
1118 <entry colname="3">ssl_keysize</entry> 2231 <entry colname="3">ssl_keysize</entry>
1119 <entry colname="4">smallint unsigned</entry> 2232 <entry colname="4">smallint unsigned</entry>
1120 <entry colname="5">56</entry> 2233 <entry colname="5">56</entry>
1121 </row> 2234 </row>
1122 <row> 2235 <row>
1123 <entry colname="1">Q</entry> 2236 <entry colname="1">Q</entry>
1124 <entry colname="2">maximum keysize supported</entry> 2237 <entry colname="2">
2238 maximum keysize supported
2239 </entry>
1125 <entry colname="3">ssl_maxkeysize</entry> 2240 <entry colname="3">ssl_maxkeysize</entry>
1126 <entry colname="4">smallint unsigned</entry> 2241 <entry colname="4">smallint unsigned</entry>
1127 <entry colname="5">128</entry> 2242 <entry colname="5">128</entry>
@@ -1129,6 +2244,41 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1129 </tbody> 2244 </tbody>
1130 </tgroup> 2245 </tgroup>
1131 </table> 2246 </table>
2247 <table>
2248 <title>LogIO LogFormat Parameters</title>
2249 <tgroup cols="5">
2250 <colspec colname="1" colnum="1" />
2251 <colspec colname="2" colnum="2" />
2252 <colspec colname="3" colnum="3" />
2253 <colspec colname="4" colnum="4" />
2254 <colspec colname="5" colnum="5" />
2255 <thead>
2256 <row>
2257 <entry colname="1">Symbol</entry>
2258 <entry colname="2">Meaning</entry>
2259 <entry colname="3">DB Field</entry>
2260 <entry colname="4">Data Type</entry>
2261 <entry colname="5">Example</entry>
2262 </row>
2263 </thead>
2264 <tbody>
2265 <row>
2266 <entry colname="1">i</entry>
2267 <entry colname="2">Number of actual Bytes transfered in with the request</entry>
2268 <entry colname="3">bytes_in</entry>
2269 <entry colname="4">int unsigned</entry>
2270 <entry colname="5">505</entry>
2271 </row>
2272 <row>
2273 <entry colname="1">o</entry>
2274 <entry colname="2">Number of actual Bytes transfered out with the request</entry>
2275 <entry colname="3">bytes_out</entry>
2276 <entry colname="4">int unsigned</entry>
2277 <entry colname="5">4168</entry>
2278 </row>
2279 </tbody>
2280 </tgroup>
2281 </table>
1132 </listitem> 2282 </listitem>
1133 </varlistentry> 2283 </varlistentry>
1134 <varlistentry> 2284 <varlistentry>
@@ -1136,13 +2286,39 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1136 <listitem> 2286 <listitem>
1137 <cmdsynopsis sepchar=" "> 2287 <cmdsynopsis sepchar=" ">
1138 <command>LogSQLRemhostIgnore</command> 2288 <command>LogSQLRemhostIgnore</command>
1139 <arg choice="req" rep="repeat"><replaceable>hostname</replaceable></arg> 2289 <arg choice="req" rep="repeat">
2290 <replaceable>hostname</replaceable>
2291 </arg>
1140 </cmdsynopsis> 2292 </cmdsynopsis>
1141 <simpara>Example: LogSQLRemhostIgnore localnet.com</simpara> 2293 <simpara>
2294 Example: LogSQLRemhostIgnore localnet.com
2295 </simpara>
1142 <simpara>Context: virtual host</simpara> 2296 <simpara>Context: virtual host</simpara>
1143 <para>Lists a series of smortrings that, if present in the REMOTE_HOST, will cause that request to <emphasis>not</emphasis> be logged. This directive is useful for cutting down on log clutter when you are certain that you want to ignore requests from certain hosts, such as your own internal network machines. See section <xref endterm="Sect.Ignore.title" linkend="Sect.Ignore"/> for some tips for using this directive.</para> 2297 <para>
1144 <para>Each string may contain a + or - prefix in a &lt;VirtualHost&gt; context and will cause those strings to be added (+) or removed (-) from the global configuration. Otherwise the global is completely ignored and overridden if defined in a &lt;VirtualHost&gt;</para> 2298 Lists a series of smortrings that, if present in the
1145 <para>Each string is separated by a space, and no regular expressions or globbing are allowed. Each string is evaluated as a substring of the REMOTE_HOST using strstr(). The comparison is case sensitive.</para> 2299 REMOTE_HOST, will cause that request to
2300 <emphasis>not</emphasis>
2301 be logged. This directive is useful for cutting down on
2302 log clutter when you are certain that you want to ignore
2303 requests from certain hosts, such as your own internal
2304 network machines. See section
2305 <xref endterm="Sect.Ignore.title" linkend="Sect.Ignore" />
2306 for some tips for using this directive.
2307 </para>
2308 <para>
2309 Each string may contain a + or - prefix in a
2310 &lt;VirtualHost&gt; context and will cause those strings
2311 to be added (+) or removed (-) from the global
2312 configuration. Otherwise the global is completely
2313 ignored and overridden if defined in a
2314 &lt;VirtualHost&gt;
2315 </para>
2316 <para>
2317 Each string is separated by a space, and no regular
2318 expressions or globbing are allowed. Each string is
2319 evaluated as a substring of the REMOTE_HOST using
2320 strstr(). The comparison is case sensitive.
2321 </para>
1146 </listitem> 2322 </listitem>
1147 </varlistentry> 2323 </varlistentry>
1148 <varlistentry> 2324 <varlistentry>
@@ -1150,16 +2326,55 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1150 <listitem> 2326 <listitem>
1151 <cmdsynopsis sepchar=" "> 2327 <cmdsynopsis sepchar=" ">
1152 <command>LogSQLRequestAccept</command> 2328 <command>LogSQLRequestAccept</command>
1153 <arg choice="req" rep="repeat"><replaceable>substring</replaceable></arg> 2329 <arg choice="req" rep="repeat">
2330 <replaceable>substring</replaceable>
2331 </arg>
1154 </cmdsynopsis> 2332 </cmdsynopsis>
1155 <simpara>Example: LogSQLRequestAccept .html .php .jpg</simpara> 2333 <simpara>
1156 <simpara>Default: if not specified, all requests are 'accepted'</simpara> 2334 Example: LogSQLRequestAccept .html .php .jpg
2335 </simpara>
2336 <simpara>
2337 Default: if not specified, all requests are 'accepted'
2338 </simpara>
1157 <simpara>Context: virtual host</simpara> 2339 <simpara>Context: virtual host</simpara>
1158 <para>Lists a series of strings that, if present in the URI, will permit that request to be considered for logging (depending on additional filtering by the "ignore" directives). Any request that fails to match one of the LogSQLRequestAccept entries will be discarded.</para> 2340 <para>
1159 <para>Each string may contain a + or - prefix in a &lt;VirtualHost&gt; context and will cause those strings to be added (+) or removed (-) from the global configuration. Otherwise the global is completely ignored and overridden if defined in a &lt;VirtualHost&gt;</para> 2341 Lists a series of strings that, if present in the URI,
1160 <para>This directive is useful for cutting down on log clutter when you are certain that you only want to log certain kinds of requests, and just blanket-ignore everything else. See section <xref endterm="Sect.Ignore.title" linkend="Sect.Ignore"/> for some tips for using this directive.</para> 2342 will permit that request to be considered for logging
1161 <para>Each string is separated by a space, and no regular expressions or globbing are allowed. Each string is evaluated as a substring of the URI using strstr(). The comparison is case sensitive.</para> 2343 (depending on additional filtering by the "ignore"
1162 <para>This directive is completely optional. It is more general than LogSQLRequestIgnore and is evaluated before LogSQLRequestIgnore . If this directive is not used, <emphasis>all</emphasis> requests are accepted and passed on to the other filtering directives. Therefore, only use this directive if you have a specific reason to do so.</para> 2344 directives). Any request that fails to match one of the
2345 LogSQLRequestAccept entries will be discarded.
2346 </para>
2347 <para>
2348 Each string may contain a + or - prefix in a
2349 &lt;VirtualHost&gt; context and will cause those strings
2350 to be added (+) or removed (-) from the global
2351 configuration. Otherwise the global is completely
2352 ignored and overridden if defined in a
2353 &lt;VirtualHost&gt;
2354 </para>
2355 <para>
2356 This directive is useful for cutting down on log clutter
2357 when you are certain that you only want to log certain
2358 kinds of requests, and just blanket-ignore everything
2359 else. See section
2360 <xref endterm="Sect.Ignore.title" linkend="Sect.Ignore" />
2361 for some tips for using this directive.
2362 </para>
2363 <para>
2364 Each string is separated by a space, and no regular
2365 expressions or globbing are allowed. Each string is
2366 evaluated as a substring of the URI using strstr(). The
2367 comparison is case sensitive.
2368 </para>
2369 <para>
2370 This directive is completely optional. It is more
2371 general than LogSQLRequestIgnore and is evaluated before
2372 LogSQLRequestIgnore . If this directive is not used,
2373 <emphasis>all</emphasis>
2374 requests are accepted and passed on to the other
2375 filtering directives. Therefore, only use this directive
2376 if you have a specific reason to do so.
2377 </para>
1163 </listitem> 2378 </listitem>
1164 </varlistentry> 2379 </varlistentry>
1165 <varlistentry> 2380 <varlistentry>
@@ -1167,13 +2382,39 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1167 <listitem> 2382 <listitem>
1168 <cmdsynopsis sepchar=" "> 2383 <cmdsynopsis sepchar=" ">
1169 <command>LogSQLRequestIgnore</command> 2384 <command>LogSQLRequestIgnore</command>
1170 <arg choice="req" rep="repeat"><replaceable>substring</replaceable></arg> 2385 <arg choice="req" rep="repeat">
2386 <replaceable>substring</replaceable>
2387 </arg>
1171 </cmdsynopsis> 2388 </cmdsynopsis>
1172 <simpara>Example: LogSQLRequestIgnore root.exe cmd.exe default.ida favicon.ico</simpara> 2389 <simpara>
2390 Example: LogSQLRequestIgnore root.exe cmd.exe
2391 default.ida favicon.ico
2392 </simpara>
1173 <simpara>Context: virtual host</simpara> 2393 <simpara>Context: virtual host</simpara>
1174 <para>Lists a series of strings that, if present in the URI, will cause that request to <emphasis>NOT</emphasis> be logged. This directive is useful for cutting down on log clutter when you are certain that you want to ignore requests for certain objects. See section <xref endterm="Sect.Ignore.title" linkend="Sect.Ignore"/> for some tips for using this directive.</para> 2394 <para>
1175 <para>Each string may contain a + or - prefix in a &lt;VirtualHost&gt; context and will cause those strings to be added (+) or removed (-) from the global configuration. Otherwise the global is completely ignored and overridden if defined in a &lt;VirtualHost&gt;</para> 2395 Lists a series of strings that, if present in the URI,
1176 <para>Each string is separated by a space, and no regular expressions or globbing are allowed. Each string is evaluated as a substring of the URI using strstr(). The comparison is case sensitive.</para> 2396 will cause that request to
2397 <emphasis>NOT</emphasis>
2398 be logged. This directive is useful for cutting down on
2399 log clutter when you are certain that you want to ignore
2400 requests for certain objects. See section
2401 <xref endterm="Sect.Ignore.title" linkend="Sect.Ignore" />
2402 for some tips for using this directive.
2403 </para>
2404 <para>
2405 Each string may contain a + or - prefix in a
2406 &lt;VirtualHost&gt; context and will cause those strings
2407 to be added (+) or removed (-) from the global
2408 configuration. Otherwise the global is completely
2409 ignored and overridden if defined in a
2410 &lt;VirtualHost&gt;
2411 </para>
2412 <para>
2413 Each string is separated by a space, and no regular
2414 expressions or globbing are allowed. Each string is
2415 evaluated as a substring of the URI using strstr(). The
2416 comparison is case sensitive.
2417 </para>
1177 </listitem> 2418 </listitem>
1178 </varlistentry> 2419 </varlistentry>
1179 <varlistentry> 2420 <varlistentry>
@@ -1181,15 +2422,39 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1181 <listitem> 2422 <listitem>
1182 <cmdsynopsis sepchar=" "> 2423 <cmdsynopsis sepchar=" ">
1183 <command>LogSQLWhichCookie</command> 2424 <command>LogSQLWhichCookie</command>
1184 <arg choice="req"><replaceable>cookiename</replaceable></arg> 2425 <arg choice="req">
2426 <replaceable>cookiename</replaceable>
2427 </arg>
1185 </cmdsynopsis> 2428 </cmdsynopsis>
1186 <simpara>Example; LogSQLWhichCookie Clicks</simpara> 2429 <simpara>Example; LogSQLWhichCookie Clicks</simpara>
1187 <simpara>Context: virtual host</simpara> 2430 <simpara>Context: virtual host</simpara>
1188 <para>In HTTP, cookies have names to distinguish them from each other. Using mod_usertrack, for example, you can give your user-tracking cookies a name with the CookieName directive.</para> 2431 <para>
1189 <para>mod_log_sql allows you to log cookie information. LogSQL_WhichCookie tells mod_log_sql which cookie to log. This is necessary because you will usually be setting and receiving more than one cookie from a client.</para> 2432 In HTTP, cookies have names to distinguish them from
2433 each other. Using mod_usertrack, for example, you can
2434 give your user-tracking cookies a name with the
2435 CookieName directive.
2436 </para>
2437 <para>
2438 mod_log_sql allows you to log cookie information.
2439 LogSQL_WhichCookie tells mod_log_sql which cookie to
2440 log. This is necessary because you will usually be
2441 setting and receiving more than one cookie from a
2442 client.
2443 </para>
1190 <note> 2444 <note>
1191 <para>You must include a 'c' character in LogSQLTransferLogFormat for this directive to take effect.</para> 2445 <para>
1192 <para>although this was origintally intended for people using mod_usertrack to create user-tracking cookies, you are not restricted in any way. You can choose which cookie you wish to log to the database - any cookie at all - and it does not necessarily have to have anything to do with mod_usertrack.</para> 2446 You must include a 'c' character in
2447 LogSQLTransferLogFormat for this directive to take
2448 effect.
2449 </para>
2450 <para>
2451 although this was origintally intended for people
2452 using mod_usertrack to create user-tracking cookies,
2453 you are not restricted in any way. You can choose
2454 which cookie you wish to log to the database - any
2455 cookie at all - and it does not necessarily have to
2456 have anything to do with mod_usertrack.
2457 </para>
1193 </note> 2458 </note>
1194 </listitem> 2459 </listitem>
1195 </varlistentry> 2460 </varlistentry>
@@ -1198,14 +2463,38 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1198 <listitem> 2463 <listitem>
1199 <cmdsynopsis sepchar=" "> 2464 <cmdsynopsis sepchar=" ">
1200 <command>LogSQLWhichCookies</command> 2465 <command>LogSQLWhichCookies</command>
1201 <arg choice="req" rep="repeat"><replaceable>cookie-name</replaceable></arg> 2466 <arg choice="req" rep="repeat">
2467 <replaceable>cookie-name</replaceable>
2468 </arg>
1202 </cmdsynopsis> 2469 </cmdsynopsis>
1203 <simpara>Example: logSQLWhichCookies userlogin cookie1 cookie2</simpara> 2470 <simpara>
2471 Example: logSQLWhichCookies userlogin cookie1 cookie2
2472 </simpara>
1204 <simpara>Context: virtual host</simpara> 2473 <simpara>Context: virtual host</simpara>
1205 <para>Defines the list of cookies you would like logged. This works in conjunction with LogSQLCookieLogTable. This directive does <emphasis>not</emphasis> require any additional characters to be added to the LogSQLTransferLogFormat string. The feature is activated simply by including this directive, upon which you will begin populating the separate cookie table with data.</para> 2474 <para>
1206 <para>Each string may contain a + or - prefix in a &lt;VirtualHost&gt; context and will cause those strings to be added (+) or removed (-) from the global configuration. Otherwise the global is completely ignored and overridden if defined in a &lt;VirtualHost&gt;</para> 2475 Defines the list of cookies you would like logged. This
2476 works in conjunction with LogSQLCookieLogTable. This
2477 directive does
2478 <emphasis>not</emphasis>
2479 require any additional characters to be added to the
2480 LogSQLTransferLogFormat string. The feature is activated
2481 simply by including this directive, upon which you will
2482 begin populating the separate cookie table with data.
2483 </para>
2484 <para>
2485 Each string may contain a + or - prefix in a
2486 &lt;VirtualHost&gt; context and will cause those strings
2487 to be added (+) or removed (-) from the global
2488 configuration. Otherwise the global is completely
2489 ignored and overridden if defined in a
2490 &lt;VirtualHost&gt;
2491 </para>
1207 <note> 2492 <note>
1208 <para>The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'.</para> 2493 <para>
2494 The table must be created (see create-tables.sql,
2495 included in the package), or LogSQLCreateTables must
2496 be set to 'On'.
2497 </para>
1209 </note> 2498 </note>
1210 </listitem> 2499 </listitem>
1211 </varlistentry> 2500 </varlistentry>
@@ -1214,14 +2503,39 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1214 <listitem> 2503 <listitem>
1215 <cmdsynopsis sepchar=" "> 2504 <cmdsynopsis sepchar=" ">
1216 <command>LogSQLWhichHeadersIn</command> 2505 <command>LogSQLWhichHeadersIn</command>
1217 <arg choice="req" rep="repeat"><replaceable>header-name</replaceable></arg> 2506 <arg choice="req" rep="repeat">
2507 <replaceable>header-name</replaceable>
2508 </arg>
1218 </cmdsynopsis> 2509 </cmdsynopsis>
1219 <simpara>Example: LogSQLWhichHeadersIn User-Agent Accept-Encoding Host</simpara> 2510 <simpara>
2511 Example: LogSQLWhichHeadersIn User-Agent Accept-Encoding
2512 Host
2513 </simpara>
1220 <simpara>Context: virtual host</simpara> 2514 <simpara>Context: virtual host</simpara>
1221 <para>Defines the list of inbound headers you would like logged. This works in conjunction with LogSQLHeadersInLogTable. This directive does not require any additional characters to be added to the LogSQLTransferLogFormat string. The feature is activated simply by including this directive, upon which you will begin populating the separate inbound-headers table with data.</para> 2515 <para>
1222 <para>Each string may contain a + or - prefix in a &lt;VirtualHost&gt; context and will cause those strings to be added (+) or removed (-) from the global configuration. Otherwise the global is completely ignored and overridden if defined in a &lt;VirtualHost&gt;</para> 2516 Defines the list of inbound headers you would like
2517 logged. This works in conjunction with
2518 LogSQLHeadersInLogTable. This directive does not require
2519 any additional characters to be added to the
2520 LogSQLTransferLogFormat string. The feature is activated
2521 simply by including this directive, upon which you will
2522 begin populating the separate inbound-headers table with
2523 data.
2524 </para>
2525 <para>
2526 Each string may contain a + or - prefix in a
2527 &lt;VirtualHost&gt; context and will cause those strings
2528 to be added (+) or removed (-) from the global
2529 configuration. Otherwise the global is completely
2530 ignored and overridden if defined in a
2531 &lt;VirtualHost&gt;
2532 </para>
1223 <note> 2533 <note>
1224 <para>The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'.</para> 2534 <para>
2535 The table must be created (see create-tables.sql,
2536 included in the package), or LogSQLCreateTables must
2537 be set to 'On'.
2538 </para>
1225 </note> 2539 </note>
1226 </listitem> 2540 </listitem>
1227 </varlistentry> 2541 </varlistentry>
@@ -1230,14 +2544,39 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1230 <listitem> 2544 <listitem>
1231 <cmdsynopsis sepchar=" "> 2545 <cmdsynopsis sepchar=" ">
1232 <command>LogSQLWhichHeadersOut</command> 2546 <command>LogSQLWhichHeadersOut</command>
1233 <arg choice="req" rep="repeat"><replaceable>header-name</replaceable></arg> 2547 <arg choice="req" rep="repeat">
2548 <replaceable>header-name</replaceable>
2549 </arg>
1234 </cmdsynopsis> 2550 </cmdsynopsis>
1235 <simpara>Example: LogSQLWhichHeadersOut Expires Content-Type Cache-Control</simpara> 2551 <simpara>
2552 Example: LogSQLWhichHeadersOut Expires Content-Type
2553 Cache-Control
2554 </simpara>
1236 <simpara>Context: virtual host</simpara> 2555 <simpara>Context: virtual host</simpara>
1237 <para>Defines the list of outbound headers you would like logged. This works in conjunction with LogSQLHeadersOutLogTable. This directive does not require any additional characters to be added to the LogSQLTransferLogFormat string. The feature is activated simply by including this directive, upon which you will begin populating the separate outbound-headers table with data.</para> 2556 <para>
1238 <para>Each string may contain a + or - prefix in a &lt;VirtualHost&gt; context and will cause those strings to be added (+) or removed (-) from the global configuration. Otherwise the global is completely ignored and overridden if defined in a &lt;VirtualHost&gt;</para> 2557 Defines the list of outbound headers you would like
2558 logged. This works in conjunction with
2559 LogSQLHeadersOutLogTable. This directive does not
2560 require any additional characters to be added to the
2561 LogSQLTransferLogFormat string. The feature is activated
2562 simply by including this directive, upon which you will
2563 begin populating the separate outbound-headers table
2564 with data.
2565 </para>
2566 <para>
2567 Each string may contain a + or - prefix in a
2568 &lt;VirtualHost&gt; context and will cause those strings
2569 to be added (+) or removed (-) from the global
2570 configuration. Otherwise the global is completely
2571 ignored and overridden if defined in a
2572 &lt;VirtualHost&gt;
2573 </para>
1239 <note> 2574 <note>
1240 <para>The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'.</para> 2575 <para>
2576 The table must be created (see create-tables.sql,
2577 included in the package), or LogSQLCreateTables must
2578 be set to 'On'.
2579 </para>
1241 </note> 2580 </note>
1242 </listitem> 2581 </listitem>
1243 </varlistentry> 2582 </varlistentry>
@@ -1246,14 +2585,38 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1246 <listitem> 2585 <listitem>
1247 <cmdsynopsis sepchar=" "> 2586 <cmdsynopsis sepchar=" ">
1248 <command>LogSQLWhichNotes</command> 2587 <command>LogSQLWhichNotes</command>
1249 <arg choice="req" rep="repeat"><replaceable>note-name</replaceable></arg> 2588 <arg choice="req" rep="repeat">
2589 <replaceable>note-name</replaceable>
2590 </arg>
1250 </cmdsynopsis> 2591 </cmdsynopsis>
1251 <simpara>Example: LogSQLWhichNotes mod_gzip_result mod_gzip_ompression_ratio</simpara> 2592 <simpara>
2593 Example: LogSQLWhichNotes mod_gzip_result
2594 mod_gzip_ompression_ratio
2595 </simpara>
1252 <simpara>Context: virtual host</simpara> 2596 <simpara>Context: virtual host</simpara>
1253 <para>Defines the list of notes you would like logged. This works in conjunction with LogSQLNotesLogTable. This directive does not require any additional characters to be added to the LogSQLTransferLogFormat string. The feature is activated simply by including this directive, upon which you will begin populating the separate notes table with data.</para> 2597 <para>
1254 <para>Each string may contain a + or - prefix in a &lt;VirtualHost&gt; context and will cause those strings to be added (+) or removed (-) from the global configuration. Otherwise the global is completely ignored and overridden if defined in a &lt;VirtualHost&gt;</para> 2598 Defines the list of notes you would like logged. This
2599 works in conjunction with LogSQLNotesLogTable. This
2600 directive does not require any additional characters to
2601 be added to the LogSQLTransferLogFormat string. The
2602 feature is activated simply by including this directive,
2603 upon which you will begin populating the separate notes
2604 table with data.
2605 </para>
2606 <para>
2607 Each string may contain a + or - prefix in a
2608 &lt;VirtualHost&gt; context and will cause those strings
2609 to be added (+) or removed (-) from the global
2610 configuration. Otherwise the global is completely
2611 ignored and overridden if defined in a
2612 &lt;VirtualHost&gt;
2613 </para>
1255 <note> 2614 <note>
1256 <para>The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'.</para> 2615 <para>
2616 The table must be created (see create-tables.sql,
2617 included in the package), or LogSQLCreateTables must
2618 be set to 'On'.
2619 </para>
1257 </note> 2620 </note>
1258 </listitem> 2621 </listitem>
1259 </varlistentry> 2622 </varlistentry>
@@ -1267,17 +2630,41 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1267 <listitem> 2630 <listitem>
1268 <cmdsynopsis sepchar=" "> 2631 <cmdsynopsis sepchar=" ">
1269 <command>LogSQLSocketFile</command> 2632 <command>LogSQLSocketFile</command>
1270 <arg choice="req"><replaceable>filename</replaceable></arg> 2633 <arg choice="req">
2634 <replaceable>filename</replaceable>
2635 </arg>
1271 </cmdsynopsis> 2636 </cmdsynopsis>
1272 <simpara>Example: LogSQLSocketFile /tmp/mysql.sock</simpara> 2637 <simpara>
2638 Example: LogSQLSocketFile /tmp/mysql.sock
2639 </simpara>
1273 <simpara>Default: (database specific)</simpara> 2640 <simpara>Default: (database specific)</simpara>
1274 <simpara>Default (MySQL): /var/lib/mysql/mysql.sock</simpara> 2641 <simpara>
2642 Default (MySQL): /var/lib/mysql/mysql.sock
2643 </simpara>
1275 <simpara>Context: main server config</simpara> 2644 <simpara>Context: main server config</simpara>
1276 <para>At Apache runtime you can specify the MySQL socket file to use. Set this once in your main server config to override the default value. This value is irrelevant if your database resides on a separate machine.</para> 2645 <para>
1277 <para>mod_log_sql will automatically employ the socket for db communications if the database resides on the local host. If the db resides on a separate host the module will automatically use TCP/IP. This is a function of the MySQL API and is not user-configurable.</para> 2646 At Apache runtime you can specify the MySQL socket file
2647 to use. Set this once in your main server config to
2648 override the default value. This value is irrelevant if
2649 your database resides on a separate machine.
2650 </para>
2651 <para>
2652 mod_log_sql will automatically employ the socket for db
2653 communications if the database resides on the local
2654 host. If the db resides on a separate host the module
2655 will automatically use TCP/IP. This is a function of the
2656 MySQL API and is not user-configurable.
2657 </para>
1278 <note> 2658 <note>
1279 <para>This directive is deprecated in favor of LogSQLDBParam socketfile [socketfilename]</para> 2659 <para>
1280 <para>This is defined only once in the <filename>httpd.conf</filename> file.</para> 2660 This directive is deprecated in favor of LogSQLDBParam
2661 socketfile [socketfilename]
2662 </para>
2663 <para>
2664 This is defined only once in the
2665 <filename>httpd.conf</filename>
2666 file.
2667 </para>
1281 </note> 2668 </note>
1282 </listitem> 2669 </listitem>
1283 </varlistentry> 2670 </varlistentry>
@@ -1286,16 +2673,31 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1286 <listitem> 2673 <listitem>
1287 <cmdsynopsis sepchar=" "> 2674 <cmdsynopsis sepchar=" ">
1288 <command>LogSQLTCPPort</command> 2675 <command>LogSQLTCPPort</command>
1289 <arg choice="req"><replaceable>port-number</replaceable></arg> 2676 <arg choice="req">
2677 <replaceable>port-number</replaceable>
2678 </arg>
1290 </cmdsynopsis> 2679 </cmdsynopsis>
1291 <simpara>Example: LogSQLTCPPort 3309</simpara> 2680 <simpara>Example: LogSQLTCPPort 3309</simpara>
1292 <simpara>Default: (database specific)</simpara> 2681 <simpara>Default: (database specific)</simpara>
1293 <simpara>Default (MySQL): 3306</simpara> 2682 <simpara>Default (MySQL): 3306</simpara>
1294 <simpara>Context: main server config</simpara> 2683 <simpara>Context: main server config</simpara>
1295 <para>Your database may listen on a different port than the default. If so, use this directive to instruct the module which port to use. This directive only applies if the database is on a different machine connected via TCP/IP.</para> 2684 <para>
2685 Your database may listen on a different port than the
2686 default. If so, use this directive to instruct the
2687 module which port to use. This directive only applies if
2688 the database is on a different machine connected via
2689 TCP/IP.
2690 </para>
1296 <note> 2691 <note>
1297 <para>This directive is deprecated in favor of LogSQLDBParam tcpport [port-number]</para> 2692 <para>
1298 <para>This is defined only once in the <filename>httpd.conf</filename> file.</para> 2693 This directive is deprecated in favor of LogSQLDBParam
2694 tcpport [port-number]
2695 </para>
2696 <para>
2697 This is defined only once in the
2698 <filename>httpd.conf</filename>
2699 file.
2700 </para>
1299 </note> 2701 </note>
1300 </listitem> 2702 </listitem>
1301 </varlistentry> 2703 </varlistentry>
@@ -1304,14 +2706,27 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1304 <listitem> 2706 <listitem>
1305 <cmdsynopsis sepchar=" "> 2707 <cmdsynopsis sepchar=" ">
1306 <command>LogSQLDatabase</command> 2708 <command>LogSQLDatabase</command>
1307 <arg choice="req"><replaceable>database</replaceable></arg> 2709 <arg choice="req">
2710 <replaceable>database</replaceable>
2711 </arg>
1308 </cmdsynopsis> 2712 </cmdsynopsis>
1309 <simpara>Example: LogSQLDatabase loggingdb</simpara> 2713 <simpara>Example: LogSQLDatabase loggingdb</simpara>
1310 <simpara>Context: main server config</simpara> 2714 <simpara>Context: main server config</simpara>
1311 <para>Defines the database that is used for logging. "database" must be a valid db on the MySQL host defined in LogSQLLoginInfo</para> 2715 <para>
2716 Defines the database that is used for logging.
2717 "database" must be a valid db on the MySQL host defined
2718 in LogSQLLoginInfo
2719 </para>
1312 <note> 2720 <note>
1313 <para>This directive is deprecated in favor of the URI form of LogSQLLoginInfo.</para> 2721 <para>
1314 <para>This is defined only once in the <filename>httpd.conf</filename> file.</para> 2722 This directive is deprecated in favor of the URI form
2723 of LogSQLLoginInfo.
2724 </para>
2725 <para>
2726 This is defined only once in the
2727 <filename>httpd.conf</filename>
2728 file.
2729 </para>
1315 </note> 2730 </note>
1316 </listitem> 2731 </listitem>
1317 </varlistentry> 2732 </varlistentry>
@@ -1329,28 +2744,54 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1329 <para>Why log to an SQL database?</para> 2744 <para>Why log to an SQL database?</para>
1330 </question> 2745 </question>
1331 <answer> 2746 <answer>
1332 <para>To begin with, let's get it out of the way: logging to a database is not a panacea. But while there are complexities with this solution, the benefit can be substantial for certain classes of administrator or people with advanced requirements:</para> 2747 <para>
2748 To begin with, let's get it out of the way: logging to a
2749 database is not a panacea. But while there are
2750 complexities with this solution, the benefit can be
2751 substantial for certain classes of administrator or people
2752 with advanced requirements:
2753 </para>
1333 <itemizedlist> 2754 <itemizedlist>
1334 <listitem> 2755 <listitem>
1335 <para>Chores like log rotation go away, as you can DELETE records from the SQL database once they are no longer useful. For example, the excellent and popular log-analysis tool Webalizer (http://www.webalizer.com) does not need historic logs after it has processed them, enabling you to delete older logs.</para> 2756 <para>
2757 Chores like log rotation go away, as you can DELETE
2758 records from the SQL database once they are no longer
2759 useful. For example, the excellent and popular
2760 log-analysis tool Webalizer (http://www.webalizer.com)
2761 does not need historic logs after it has processed
2762 them, enabling you to delete older logs.
2763 </para>
1336 </listitem> 2764 </listitem>
1337 <listitem> 2765 <listitem>
1338 <para>People with clusters of web servers (for high availability) will benefit the most - all their webservers can log to a single SQL database. This obviates the need to collate/interleave the many separate logfiles, which can be / highly/ problematic.</para> 2766 <para>
2767 People with clusters of web servers (for high
2768 availability) will benefit the most - all their
2769 webservers can log to a single SQL database. This
2770 obviates the need to collate/interleave the many
2771 separate logfiles, which can be / highly/ problematic.
2772 </para>
1339 </listitem> 2773 </listitem>
1340 <listitem> 2774 <listitem>
1341 <para>People acquainted with the power of SQL SELECT statements will know the flexibility of the extraction possibilities at their fingertips.</para> 2775 <para>
2776 People acquainted with the power of SQL SELECT
2777 statements will know the flexibility of the extraction
2778 possibilities at their fingertips.
2779 </para>
1342 </listitem> 2780 </listitem>
1343 </itemizedlist> 2781 </itemizedlist>
1344 <para>For example, do you want to see all your 404's? Do this:</para> 2782 <para>
1345 <programlisting>select remote_host,status,request_uri,bytes_sent,from_unixtime(time_stamp) from acc_log_tbl where status=404 order by time_stamp;</programlisting> 2783 For example, do you want to see all your 404's? Do this:
2784 </para>
2785 <programlisting>SELECT remote_host, status, request_uri, bytes_sent, from_unixtime(time_stamp)
2786FROM acc_log_tbl WHERE status=404 ORDER BY time_stamp;</programlisting>
1346 <table> 2787 <table>
1347 <title></title> 2788 <title></title>
1348 <tgroup cols="5"> 2789 <tgroup cols="5">
1349 <colspec colname="1"/> 2790 <colspec colname="1" />
1350 <colspec colname="2"/> 2791 <colspec colname="2" />
1351 <colspec colname="3"/> 2792 <colspec colname="3" />
1352 <colspec colname="4"/> 2793 <colspec colname="4" />
1353 <colspec colname="5"/> 2794 <colspec colname="5" />
1354 <thead> 2795 <thead>
1355 <row> 2796 <row>
1356 <entry colname="1">remote_host</entry> 2797 <entry colname="1">remote_host</entry>
@@ -1392,14 +2833,20 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1392 </tbody> 2833 </tbody>
1393 </tgroup> 2834 </tgroup>
1394 </table> 2835 </table>
1395 <para>Or do you want to see how many bytes you've sent within a certain directory or site? Do this:</para> 2836 <para>
1396 <programlisting>select request_uri,sum(bytes_sent) as bytes,count(request_uri) as howmany from acc_log_tbl where request_uri like '%mod_log_sql%' group by request_uri order by howmany desc;</programlisting> 2837 Or do you want to see how many bytes you've sent within a
2838 certain directory or site? Do this:
2839 </para>
2840 <programlisting>SELECT request_uri,sum(bytes_sent) AS bytes, count(request_uri) AS howmany
2841FROM acc_log_tbl
2842WHERE request_uri LIKE '%mod_log_sql%'
2843GROUP BY request_uri ORDER BY howmany DESC;</programlisting>
1397 <table> 2844 <table>
1398 <title></title> 2845 <title></title>
1399 <tgroup cols="3"> 2846 <tgroup cols="3">
1400 <colspec colname="1"/> 2847 <colspec colname="1" />
1401 <colspec colname="2"/> 2848 <colspec colname="2" />
1402 <colspec colname="3"/> 2849 <colspec colname="3" />
1403 <thead> 2850 <thead>
1404 <row> 2851 <row>
1405 <entry colname="1">request_uri</entry> 2852 <entry colname="1">request_uri</entry>
@@ -1410,7 +2857,7 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1410 <tbody> 2857 <tbody>
1411 <row> 2858 <row>
1412 <entry colname="1">/mod_log_sql/style_1.css</entry> 2859 <entry colname="1">/mod_log_sql/style_1.css</entry>
1413 <entry colname="2">157396 </entry> 2860 <entry colname="2">157396</entry>
1414 <entry colname="3">1288</entry> 2861 <entry colname="3">1288</entry>
1415 </row> 2862 </row>
1416 <row> 2863 <row>
@@ -1419,7 +2866,9 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1419 <entry colname="3">801</entry> 2866 <entry colname="3">801</entry>
1420 </row> 2867 </row>
1421 <row> 2868 <row>
1422 <entry colname="1">/mod_log_sql/mod_log_sql.tar.gz</entry> 2869 <entry colname="1">
2870 /mod_log_sql/mod_log_sql.tar.gz
2871 </entry>
1423 <entry colname="2">9769312</entry> 2872 <entry colname="2">9769312</entry>
1424 <entry colname="3">456</entry> 2873 <entry colname="3">456</entry>
1425 </row> 2874 </row>
@@ -1431,13 +2880,18 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1431 </tbody> 2880 </tbody>
1432 </tgroup> 2881 </tgroup>
1433 </table> 2882 </table>
1434 <para>Or maybe you want to see who's linking to you? Do this:</para> 2883 <para>
1435 <programlisting>select count(referer) as num,referer from acc_log_tbl where request_uri='/mod_log_sql/' group by referer order by num desc;</programlisting> 2884 Or maybe you want to see who's linking to you? Do this:
2885 </para>
2886 <programlisting>SELECT count(referer) AS num,referer
2887FROM acc_log_tbl
2888WHERE request_uri='/mod_log_sql/'
2889GROUP BY referer ORDER BY num DESC;</programlisting>
1436 <table> 2890 <table>
1437 <title></title> 2891 <title></title>
1438 <tgroup cols="2"> 2892 <tgroup cols="2">
1439 <colspec colname="1"/> 2893 <colspec colname="1" />
1440 <colspec colname="2"/> 2894 <colspec colname="2" />
1441 <thead> 2895 <thead>
1442 <row> 2896 <row>
1443 <entry colname="1">num</entry> 2897 <entry colname="1">num</entry>
@@ -1447,11 +2901,15 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1447 <tbody> 2901 <tbody>
1448 <row> 2902 <row>
1449 <entry colname="1">271</entry> 2903 <entry colname="1">271</entry>
1450 <entry colname="2">http://freshmeat.net/projects/mod_log_sql/</entry> 2904 <entry colname="2">
2905 http://freshmeat.net/projects/mod_log_sql/
2906 </entry>
1451 </row> 2907 </row>
1452 <row> 2908 <row>
1453 <entry colname="1">96</entry> 2909 <entry colname="1">96</entry>
1454 <entry colname="2">http://modules.apache.org/search?id=339 </entry> 2910 <entry colname="2">
2911 http://modules.apache.org/search?id=339
2912 </entry>
1455 </row> 2913 </row>
1456 <row> 2914 <row>
1457 <entry colname="1">48</entry> 2915 <entry colname="1">48</entry>
@@ -1464,7 +2922,11 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1464 </tbody> 2922 </tbody>
1465 </tgroup> 2923 </tgroup>
1466 </table> 2924 </table>
1467 <para>As you can see, there are myriad possibilities that can be constructed with the wonderful SQL SELECT statement. Logging to an SQL database can be really quite useful!</para> 2925 <para>
2926 As you can see, there are myriad possibilities that can be
2927 constructed with the wonderful SQL SELECT statement.
2928 Logging to an SQL database can be really quite useful!
2929 </para>
1468 </answer> 2930 </answer>
1469 </qandaentry> 2931 </qandaentry>
1470 <qandaentry> 2932 <qandaentry>
@@ -1472,11 +2934,32 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1472 <para>Why use MySQL? Are there alternatives?</para> 2934 <para>Why use MySQL? Are there alternatives?</para>
1473 </question> 2935 </question>
1474 <answer> 2936 <answer>
1475 <para>MySQL is a robust, free, and very powerful production-quality database engine. It is well supported and comes with detailed documentation. Many 3rd-party software pacakges (e.g. Slashcode, the engine that powers Slashdot) run exclusively with MySQL. In other words, you will belong to a very robust and well-supported community by choosing MySQL.</para> 2937 <para>
1476 <para>That being said, there are alternatives. PostgreSQL is probably MySQL's leading "competitor" in the free database world. There is also an excellent module available for Apache to permit logging to a PostgreSQL database, called <ulink url="http://www.digitalstratum.com/pglogd/">pgLOGd</ulink></para> 2938 MySQL is a robust, free, and very powerful
2939 production-quality database engine. It is well supported
2940 and comes with detailed documentation. Many 3rd-party
2941 software pacakges (e.g. Slashcode, the engine that powers
2942 Slashdot) run exclusively with MySQL. In other words, you
2943 will belong to a very robust and well-supported community
2944 by choosing MySQL.
2945 </para>
2946 <para>
2947 That being said, there are alternatives. PostgreSQL is
2948 probably MySQL's leading "competitor" in the free database
2949 world. There is also an excellent module available for
2950 Apache to permit logging to a PostgreSQL database, called
2951 <ulink url="http://www.digitalstratum.com/pglogd/">
2952 pgLOGd
2953 </ulink>
2954 </para>
1477 </answer> 2955 </answer>
1478 <answer> 2956 <answer>
1479 <note><para>Currently a database abstraction system is in the works to allow any database to be used with mod_log_sql.</para></note> 2957 <note>
2958 <para>
2959 Currently a database abstraction system is in the works
2960 to allow any database to be used with mod_log_sql.
2961 </para>
2962 </note>
1480 </answer> 2963 </answer>
1481 </qandaentry> 2964 </qandaentry>
1482 <qandaentry> 2965 <qandaentry>
@@ -1484,7 +2967,14 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1484 <para>Is this code production-ready?</para> 2967 <para>Is this code production-ready?</para>
1485 </question> 2968 </question>
1486 <answer> 2969 <answer>
1487 <para>By all accounts it is. It is known to work without a problem on many-thousands-of-hits-per-day webservers. Does that mean it is 100% bug free? Well, no software is, but it is well-tested and believed to be fully compatible with production environments. (The usual disclaimers apply. This software is provided without warranty of any kind.)</para> 2970 <para>
2971 By all accounts it is. It is known to work without a
2972 problem on many-thousands-of-hits-per-day webservers. Does
2973 that mean it is 100% bug free? Well, no software is, but
2974 it is well-tested and believed to be fully compatible with
2975 production environments. (The usual disclaimers apply.
2976 This software is provided without warranty of any kind.)
2977 </para>
1488 </answer> 2978 </answer>
1489 </qandaentry> 2979 </qandaentry>
1490 <qandaentry> 2980 <qandaentry>
@@ -1492,21 +2982,42 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1492 <para>Who's using mod_log_sql?</para> 2982 <para>Who's using mod_log_sql?</para>
1493 </question> 2983 </question>
1494 <answer> 2984 <answer>
1495 <para>Good question! It would be great to find out! If you are a production-level mod_log_sql user, please contact eddie at &EmailContact; so that you can be mentioned here.</para> 2985 <para>
2986 Good question! It would be great to find out! If you are a
2987 production-level mod_log_sql user, please contact eddie at
2988 &EmailContact;
2989 so that you can be mentioned here.
2990 </para>
1496 </answer> 2991 </answer>
1497 </qandaentry> 2992 </qandaentry>
1498 <qandaentry> 2993 <qandaentry>
1499 <question> 2994 <question>
1500 <para>Why doesn't the module also replace the Apache ErrorLog?</para> 2995 <para>
2996 Why doesn't the module also replace the Apache ErrorLog?
2997 </para>
1501 </question> 2998 </question>
1502 <answer> 2999 <answer>
1503 <para>There are circumstances when that would be quite unwise -- for example, if Apache could not reach the MySQL server for some reason and needed to log that fact. Without a text-based error log you'd never know anything was wrong, because Apache would be trying to log a database connection error to the database... you get the point.</para> 3000 <para>