summaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
authorGravatar Christopher Powell 2002-11-14 03:51:37 +0000
committerGravatar Christopher Powell 2002-11-14 03:51:37 +0000
commitda2aa667865606ade6a47d060ab12c851231933c (patch)
treea4e618ae9daa56f162d6b588ec8ec8face9c2fb3 /README
parent78adb60ccfd9497d5fbc899674ab1263609933b6 (diff)
Monster changes en route to 1.17. Esp. with new documentation.
Diffstat (limited to 'README')
-rw-r--r--README133
1 files changed, 4 insertions, 129 deletions
diff --git a/README b/README
index 077b6c4..fd1cdc7 100644
--- a/README
+++ b/README
@@ -1,130 +1,5 @@
1$Id: README,v 1.6 2002/05/14 21:47:15 helios Exp $ 1$Id: README,v 1.7 2002/11/14 03:51:34 helios Exp $
2
3
4Homepage
5--------
6http://www.grubbybaby.com/mod_log_sql/
7
8
9Approach
10--------
11This project was formerly known as mod_log_mysql. It has been renamed
12to mod_log_sql in order to reflect the project goal of
13database-inspecificity. The module currently supports MySQL, and
14development for other database backends is underway.
15
16In order to save speed and overhead, links are kept alive in between
17queries. This module uses one SQL link per httpd process. Among other
18things, this means that this module supports logging into only one
19MySQL server, and for now, also, only one SQL database. But that's a
20small tradeoff compared to the blinding speed of this module.
21
22Virtual hosts are supported in the same manner they are in the regular
23logging modules. You define some basic 'global' directives in the
24main server config, then you define more specific 'local' directives
25inside each virtualhost stanza.
26
27SQL links are opened by each child process when it is born. Error reporting
28is robust throughout and will let you know about database issues
29in the standard Apache error-log for the server or virtual server.
30
31A robust "preserve" capability has now been implemented. This permits
32the module to preserve any failed INSERT commands to a local file on
33its machine. In any situation that the database is unavailable -- e.g.
34the network fails, you reboot the db host, etc. -- mod_log_sql will
35note this in the error log and begin appending its log entries to the
36preserve file (which is created with the user & group ID of the running
37Apache process, e.g. "nobody" on many Linux installations). At the time
38that your MySQL server returns to service, each of these preserve files
39is easily imported because it is simply a series of SQL insert statements:
40
41 # mysql -uadminuser -p mydbname < /tmp/mysql-preserve
42
43
44
45Supported directives
46--------------------
47
48Please see the web-based documentation for full explanation of all
49supported run-time directives.
50
51 http://www.grubbybaby.com/mod_log_sql/directives.html
52
53See the FAQ for some handy examples:
54
55 http://www.grubbybaby.com/mod_log_sql/faq.html
56
57
58What gets logged by default?
59----------------------------
60
61All the data that would be contained in the "Combined Log Format"
62is logged by default, plus a little extra. Your best bet is to
63begin by accepting this default, then later customize the log
64configuration based on your needs.
65
66The online documentation of the run-time directives includes a full
67explanation of what you can log, including examples.
68
69
70Notes
71-----
72
73* You will customarily set most of your run-time configuration directives
74 on a per-virtualserver basis, with only MySQLMassVirtualHosting,
75 MySQLLoginInfo, MySQLDatabase, MySQLSocketFile, MySQLCreateTables,
76 and MySQLMassVirtualHosting 'outside' in the main server config. Any
77 directives other than those in the main config do NOT get inherited
78 by the virutal servers.
79
80* The 'time_stamp' field is stored in an UNSIGNED INTEGER column, in the
81 standard unix "seconds since 1/1/1970 12:00:00" format. This is
82 superior to storing the access time as a string due to size
83 requirements: an UNSIGNED INT type fits in 4 bytes, whereas the Apache date
84 string (e.g. "18/Nov/2001:13:59:52 -0800") requires 26 bytes --
85 significantly larger, and those extra 22 bytes will add up over the
86 thousands of accesses that a busy server will experience. Besides,
87 an INT type is far more flexible for comparisons, etc.
88
89 In MySQL 3.21 and above you can easily convert this to a human
90 readable format using from_unixtime(), e.g.:
91
92 select remote_host,request_uri,from_unixtime(time_stamp) from access_log;
93
94 The enclosed perl program make_combined_log.pl shows how you can
95 extract your access records in a format that is completely Combined
96 Log Format compliant. You can then feed this to your favorite web
97 log analysis tool.
98
99* The table's string values can be CHAR or VARCHAR, at a length of your choice.
100 VARCHAR is superior because it truncates long strings; CHAR types are
101 fixed-length and will be padded with spaces. Just like the
102 time_stamp described above, that kind of space waste will add up over
103 thousands of records.
104
105* Be careful not to go overboard setting fields to NOT NULL. If a field is
106 marked NOT NULL then it must contain data in the INSERT or the INSERT
107 will fail.
108
109* Apache normally logs numeric fields with a '-' character to mean "not
110 applicable," e.g. bytes_sent on a request with a 304 response code.
111 Since '-' is an illegal character in an SQL numeric field, such
112 fields are assigned the value 0 instead of '-' which, of course,
113 makes perfect sense anyway.
114
115
116
117Author / Maintainer
118-------------------
119
120The actual logging code was taken from the already existing flat file
121text modules, so all that credit goes to the Apache Server group.
122
123The MySQL routines and directives were added by Zeev Suraski
124<bourbon@netvision.net.il>.
125
126All changes from 1.06+ and the new documentation were added by
127Chris Powell <chris@grubbybaby.com>. It seems that the module had fallen
128into the "unmaintained" category -- it hadn't been updated since 1998 --
129so Chris adopted it as the new maintainer.
130 2
3This document has been superseded by the new documentation
4in the Documentation/ directory. There you will find
5PS, plaintext, and HTML versions of the documentation.