diff options
Diffstat (limited to 'README')
-rw-r--r-- | README | 133 |
1 files changed, 4 insertions, 129 deletions
@@ -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 | |||
4 | Homepage | ||
5 | -------- | ||
6 | http://www.grubbybaby.com/mod_log_sql/ | ||
7 | |||
8 | |||
9 | Approach | ||
10 | -------- | ||
11 | This project was formerly known as mod_log_mysql. It has been renamed | ||
12 | to mod_log_sql in order to reflect the project goal of | ||
13 | database-inspecificity. The module currently supports MySQL, and | ||
14 | development for other database backends is underway. | ||
15 | |||
16 | In order to save speed and overhead, links are kept alive in between | ||
17 | queries. This module uses one SQL link per httpd process. Among other | ||
18 | things, this means that this module supports logging into only one | ||
19 | MySQL server, and for now, also, only one SQL database. But that's a | ||
20 | small tradeoff compared to the blinding speed of this module. | ||
21 | |||
22 | Virtual hosts are supported in the same manner they are in the regular | ||
23 | logging modules. You define some basic 'global' directives in the | ||
24 | main server config, then you define more specific 'local' directives | ||
25 | inside each virtualhost stanza. | ||
26 | |||
27 | SQL links are opened by each child process when it is born. Error reporting | ||
28 | is robust throughout and will let you know about database issues | ||
29 | in the standard Apache error-log for the server or virtual server. | ||
30 | |||
31 | A robust "preserve" capability has now been implemented. This permits | ||
32 | the module to preserve any failed INSERT commands to a local file on | ||
33 | its machine. In any situation that the database is unavailable -- e.g. | ||
34 | the network fails, you reboot the db host, etc. -- mod_log_sql will | ||
35 | note this in the error log and begin appending its log entries to the | ||
36 | preserve file (which is created with the user & group ID of the running | ||
37 | Apache process, e.g. "nobody" on many Linux installations). At the time | ||
38 | that your MySQL server returns to service, each of these preserve files | ||
39 | is easily imported because it is simply a series of SQL insert statements: | ||
40 | |||
41 | # mysql -uadminuser -p mydbname < /tmp/mysql-preserve | ||
42 | |||
43 | |||
44 | |||
45 | Supported directives | ||
46 | -------------------- | ||
47 | |||
48 | Please see the web-based documentation for full explanation of all | ||
49 | supported run-time directives. | ||
50 | |||
51 | http://www.grubbybaby.com/mod_log_sql/directives.html | ||
52 | |||
53 | See the FAQ for some handy examples: | ||
54 | |||
55 | http://www.grubbybaby.com/mod_log_sql/faq.html | ||
56 | |||
57 | |||
58 | What gets logged by default? | ||
59 | ---------------------------- | ||
60 | |||
61 | All the data that would be contained in the "Combined Log Format" | ||
62 | is logged by default, plus a little extra. Your best bet is to | ||
63 | begin by accepting this default, then later customize the log | ||
64 | configuration based on your needs. | ||
65 | |||
66 | The online documentation of the run-time directives includes a full | ||
67 | explanation of what you can log, including examples. | ||
68 | |||
69 | |||
70 | Notes | ||
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 | |||
117 | Author / Maintainer | ||
118 | ------------------- | ||
119 | |||
120 | The actual logging code was taken from the already existing flat file | ||
121 | text modules, so all that credit goes to the Apache Server group. | ||
122 | |||
123 | The MySQL routines and directives were added by Zeev Suraski | ||
124 | <bourbon@netvision.net.il>. | ||
125 | |||
126 | All changes from 1.06+ and the new documentation were added by | ||
127 | Chris Powell <chris@grubbybaby.com>. It seems that the module had fallen | ||
128 | into the "unmaintained" category -- it hadn't been updated since 1998 -- | ||
129 | so Chris adopted it as the new maintainer. | ||
130 | 2 | ||
3 | This document has been superseded by the new documentation | ||
4 | in the Documentation/ directory. There you will find | ||
5 | PS, plaintext, and HTML versions of the documentation. | ||