From ec60974ca79594150b33692683b2d8bb800a896f Mon Sep 17 00:00:00 2001 From: Edward Rudd Date: Thu, 4 Mar 2004 05:41:12 +0000 Subject: complete DB separation from core module code. 99% updated documentation (needs 2 tables added) moved DB connection code for Apache 2 from open_logs to child_init. removed more #ifdef debug lines --- CHANGELOG | 14 +- Documentation/manual.xml | 866 ++++++++++++++++++++++++----------------------- functions.h | 14 +- mod_log_sql.c | 40 +-- mod_log_sql_mysql.c | 10 +- 5 files changed, 481 insertions(+), 463 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index d16549b..06ff1bd 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,9 +1,17 @@ -$Id: CHANGELOG,v 1.14 2004/02/29 23:36:17 urkle Exp $ +$Id: CHANGELOG,v 1.15 2004/03/04 05:41:12 urkle Exp $ 1.96: ? * fixed LogSQLPreserveFile config parameter -* reworked safe_create_tables +* reworked safe_create_tables and core SQL insert routine. * renamed log_sql_* variables and typedefs to logsql_* -* beginnings of abstraction layer +* separated all mysql specific code to separate code module (DB abstraction) +* separated TODO from Changelog +* fixed default value of socket file. it's really /var/lib/mysql/mysql.sock not + /tmp/mysql.sock +* Documentation completely converted to Docbook +* Documentation updated. (still needs more work done) +* LogSQLDelayedInserts config option removed +* Added DB generic LogSQLDBParam. Usage is LogSQLDBParam param value + example: LogSQLDBParam tcpport 12345 1.95: 2004-02-05 * audit and update of extract_* functions to acheive same output as diff --git a/Documentation/manual.xml b/Documentation/manual.xml index daafd69..5ff595e 100644 --- a/Documentation/manual.xml +++ b/Documentation/manual.xml @@ -47,14 +47,14 @@ - + Introduction Summary - 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 section in the FAQ for further discussion and examples of the advantages to SQL.) + 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 for further discussion and examples of the advantages to SQL.) 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. - + Approach 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. 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. @@ -63,7 +63,7 @@ What gets logged by default? - 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 . + 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 . Miscellaneous Notes @@ -123,8 +123,8 @@ Platform Specific Notes This section is currently not applicable as the new autoconf setup should auto-detect everything for your server. The win32 compilation, however, is still on my todo list. This section needs to be overhauled so do not rely completely on any information presented in it. And anyone who compiles the mod_log_sql on these platforms, please report any issues/resolutions to compiling the module. These installation documents assume a relatively modern GNU/Linux scenario. mod_log_sql has been ported to other platforms; following are notes on compiling the module for those platforms. - - Solaris + + Solaris The nanosleep() function used in mod_log_sql relies on linking aginst the librt library. Make the following alterations before proceeding: @@ -151,7 +151,7 @@ Digital Unix - Digital Unix, like Solaris, needs to be linked against librt; see section . Here are further notes from a user successfully running the module on Digital Unix: + Digital Unix, like Solaris, needs to be linked against librt; see section . Here are further notes from a user successfully running the module on Digital Unix: Instead of trying to get the module to remember where the MySQL libraries were, I instead compiled apache with the information: LDFLAGS='-rpath /isp/mysql/lib/mysql' ./configure ... Everything worked as expected after that. (The error I got without this was "/sbin/loader: Fatal Error: cannot map libmysqlclient.so" ) Digital Unix (v4.0f, at least ) appears to follow the same requirements needed by Solaris, so simply adding librt to the module made it compile without errors. As for the warnings, here's the text: mod_log_sql.c: In function `extract_request_duration': mod_log_sql.c:292: warning: long int format, different type arg (arg 4) mod_log_sql.c: In function `extract_request_timestamp': mod_log_sql.c:497: warning: long int format, different type arg (arg 4) Poking around in the code, it looks like the compiler was complaining that what time() is returning doesn't play nicely with %ld by default. I just typecast them as (long)'s and the warnings went away ( not that the module wasn't working correctly without them ). The module works very well so far in testing... hasn't dropped a single log entry yet. My thanks to Jim Turner for permitting me to quote him here, and for being the first known user of mod_log_sql on Digital Unix @@ -189,7 +189,7 @@ $ cd mod_log_sql-1.9 This is the directory to search for the libmysqlclient library and the MySQL headers. The default is to search /usr/include, /usr/include/mysql, /usr/local/include, and /usr/local/include/mysql for MySQL headers.. And /usr/lib. /usr/lib/mysql, /usr/local/lib, and /usr/local/lin/mysql for the MySQL libraries. - Specifying this argument will search $directory/include and $directory/mysql for MySQL headers. And $directory/lib and $directory/lib/mysql for MySQL libraries. + Specifying this testargument will search $directory/include and $directory/mysql for MySQL headers. And $directory/lib and $directory/lib/mysql for MySQL libraries. @@ -264,12 +264,12 @@ AddModule mod_log_sql_ssl.c - - Configuration - - Preparing MySQL for logging + + Configuration + + Preparing MySQL for logging You have to prepare the database to receive data from mod_log_sql, and set up run-time directives in httpd.conf to control how and what mod_log_sql logs. - This section will discuss how to get started with a basic configuration. Full documentation of all available run-time directives is available in section . + This section will discuss how to get started with a basic configuration. Full documentation of all available run-time directives is available in section . 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. @@ -280,7 +280,7 @@ AddModule mod_log_sql_ssl.c Enter password: mysql> create database apachelogs; - + 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). mysql> use apachelogs Database changed @@ -291,10 +291,10 @@ mysql> source create_tables.sql mysql> grant insert,create on apachelogs.* to loguser@my.apachemachine.com identified by 'l0gger'; - 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 and use the following GRANT statement instead of the one above: + 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 and use the following GRANT statement instead of the one above: mysql> grant insert on apachelogs.* to loguser@my.apachemachine.com identified by 'l0gger'; - + Enable full logging of your MySQL 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: log=/var/log/mysql-messages Then restart MySQL @@ -342,7 +342,7 @@ LogSQLCreateTables on Visit your web site in a browser to trigger some hits, then confirm that the entries are being successfully logged: # mysql -hdbmachine.foo.com -umysqladmin -p -e "select * from access_log" apachelogs Enter password: - 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 of the FAQ on how to debug and fix the situation. + 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 of the FAQ on how to debug and fix the situation. You can now activate the advanced features of mod_log_sql, which are described in the next section. @@ -354,7 +354,7 @@ Enter password: Instructing the module what to log 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. - After LogSQLTransferLogFormat you supply a string of characters that tell the module what information to log. In the configuration directive reference (section ) 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: + After LogSQLTransferLogFormat you supply a string of characters that tell the module what information to log. In the configuration directive reference (section ) 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: LogSQLTransferLogFormat hUS But a more appropriate string to use is LogSQLTransferLogFormat AbHhmRSsTUuv @@ -370,8 +370,8 @@ Enter password: - - Instructing the module what NOT to log using filtering directives + + Instructing the module what NOT to log using filtering directives 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. It is important to remember that each of these three directives is purely optional. mod_log_sql's default is to log everything. 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." @@ -438,8 +438,8 @@ LogSQLRequestIgnore statistics.html bluedot.jpg 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. 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. - - Logging many-to-one data in separate tables + + Logging many-to-one data in separate tables 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. 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. @@ -603,8 +603,8 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';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:delete from access_log where machine_id like 'test%'; - - Optimizing for a busy database + + Optimizing for a busy database 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. 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. 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. @@ -620,397 +620,421 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg'; - 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 section in the FAQ -- you have been warned. + 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 -- you have been warned. If you are experiencing issues which could be solved by delayed inserts, then set LogSqlDelayedInserts On in the httpd.conf. All regular INSERT statements are now INSERT DELAYED, and you should see no more blocking of the module. - - Configuration Directive Reference + + Configuration Directive Reference 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. - - - LogSQLCookieLogTable - - - LogSQLCookieLogTable - table-name - - Example: LogSQLCookieLogTable cookie_log - Default: cookies - Context: virtual host - 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. - - You must create the table (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to "on". - - - - - LogSQLCreateTables - - - LogSQLCreateTables - flag - - Example: LogSQLCreateTables On - Default: Off - Context: main server config - 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). - 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. - - This is defined only once in the httpd.conf file. - - - - - LogSQLDatabase - - - LogSQLDatabase - database - - Example: LogSQLDatabase loggingdb - Context: main server config - Defines the database that is used for logging. "database" must be a valid db on the MySQL host defined in LogSQLLoginInfo - - This is defined only once in the httpd.conf file. - This directive Must be defined for logging to be enabled. - - - - - LogForcePreserve - - - LogSQLForcePreserve - flag - - Example: LogForcePreserve On - Default: Off - Context: main server config - 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. - 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. - - This is defined only once in the httpd.conf file. - - - - - LogSQLHeadersInLogTable - - - LogSQLHeadersInLogTable - table-name - - Example: LogSQLHeadersInLogTable headers - Default: headers_in - Context: virtual host - 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. - - Note that you must create the table (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to "on". - - - - - LogSQLHeadersOutLogTable - - - LogSQLHeadersOutLogTable - table-name - - Example: LogSQLHeadersOutLogTable headers - Default: headers_out - Context: virtual host - 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. - - Note that you must create the table (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to "on". - - - - - LogSQLLoginInfo - - - LogSQLLoginInfo - host - user - password - - Example: LogSQLLoginInfo foobar.baz.com logwriter passw0rd - Context: main server config - Defines the general parameters of the MySQL host to which you will be logging. "host" is the hostname or IP address of the MySQL machine, and is simply "localhost" if the database lives on the same machine as Apache. "user" is the MySQL userid (not a Unix userid!) with INSERT privileges on the table defined in LogSQLTransferLogTable. "password" is that user's password. - - This is defined only once in the httpd.conf file. - This directive Must be defined for logging to be enabled. - - - - - LogSQLMachineID - - - LogSQLMachineID - machineID - - Example: LogSQLMachineID web01 - Context: main server config - 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. - - This is defined only once in the httpd.conf file. - - - - - LogSQLMassVirtualHosting - - - LogSQLMassVirtualHosting - flag - - Example: LogSQLMassVirtualHosting On - Default: Off - Context: main server config - 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: - - - the on-the-fly table creation feature is activated automatically - - - 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) - - - 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. - - - 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. - - This is defined only once in the httpd.conf file. - - - - - LogSQLNotesLogTable - - - LogSQLNotesLogTable - table-name - - Example: LogSQLNotesLogTable notes-log - Default: notes - Context: virtual_host - 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. - - This table must be created (see create-tables.sql included in the package), or LogSQLCreateTables must be set to 'On'. - - - - - LogSQlPreserveFile - - - LogSQLPreserveFile - filename - - Example: LogSQLPreserveFile offline-preserve - Default: /tmp/sql-preserve - Context: virtual host - 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: - # mysql -uadminuser -p mydbname < /tmp/sql-preserve - If you do not define LogSQLPreserveFile then all virtual servers will log to the same default preserve file (/tmp/sql-preserve). 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. - 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. - 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 & group ID of the running Apache process (e.g. 'nobody' on many Linux distributions). - - - - LogSQLRemhostIgnore - - - LogSQLRemhostIgnore - hostname - - Example: LogSQLRemhostIgnore localnet.com - Context: virtual host - Lists a series of strings that, if present in the REMOTE_HOST, will cause that request to not 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 for some tips for using this directive. - 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. - - - - LogSQLRequestAccept - - - LogSQLRequestAccept - hostname - - Example: LogSQLRequestAccept .html .php .jpg - Default: if not specified, all requests are 'accepted' - Context: virtual host - 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. - 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 for some tips for using this directive. - 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. - This directive is completely optional. It is more general than LogSQLRequestIgnore and is evaluated before LogSQLRequestIgnore . If this directive is not used, all 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. - - - - LogSQLRequestIgnore - - - LogSQLRequestIgnore - hostname - - Example: LogSQLRequestIgnore root.exe cmd.exe default.ida favicon.ico - Context: virtual host - Lists a series of strings that, if present in the URI, will cause that request to NOT 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 for some tips for using this directive. - 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. - - - - LogSQLSocketFile - - - LogSQlSocketFile - filename - - Example: LogSQLSocketFile /tmp/mysql.sock - Default: /var/lib/mysql/mysql.sock - Context: main server config - 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. - 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. - - This is defined only once in the httpd.conf file. - - - - - LogSQLTCPPort - - - LogSQLTCPPort - port-number - - Example: LogSQLTCPPort 3309 - Default: 3306 - Context: main server config - 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. - - This is defined only once in the httpd.conf file. - - - - - LogSQLTransferLogFormat - - - LogSQLTransferLogFormat - format-string - - Example: LogSQLTransferLogFormat huSUTv - Default: AbHhmRSsTUuv - Context: virtual host - 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: - TODO: Insert Log Format Types Table - - - - LogSQLTransferLogTable - - - LogSQLTransferLogTable - table-name - - Example: LogSQLTransferLogTable access_log_table - Context: virtual host - 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 LogSQLDatabase. - This directive is not 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. - - Requires unless LogSQLMassVirtualHosting is set to On - - - - - LogSQLWhichCookie - - - LogSQLWhichCookie - cookiename - - Example; LogSQLWhichCookie Clicks - Context: virtual host - 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. - 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. - - You must include a 'c' character in LogSQLTransferLogFormat for this directive to take effect. - 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. - - - - - LogSQLWhichCookies - - - LogSQLWhichCookies - cookie-name - - Example: logSQLWhichCookies userlogin cookie1 cookie2 - Context: virtual host - Defines the list of cookies you would like logged. This works in conjunction with LogSQLCookieLogTable. 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 cookie table with data. - - The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'. - - - - - LogSQLWhichHeadersIn - - - LogSQLWhichHeadersIn - header-name - - Example: LogSQLWhichHeadersIn UserAgent Accept-Encodeing Host - Context: virtual host - 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. - - The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'. - - - - - LogSQLWhichHeadersOut - - - LogSQLWhichHeadersOut - header-name - - Example: LogSQLWhichHeadersOut Expires Content-Type Cache-Control - Context: virtual host - 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. - - The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'. - - - - - LogSQLWhichNotes - - - LogSQLWhichNotes - note-name - - Example: LogSQLWhichNotes mod_gzip_result mod_gzip_ompression_ratio - Context: virtual host - 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. - - The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'. - - - - DataBase Configuration - + LogSQLLoginInfo + + + LogSQLLoginInfo + host + user + password + + Example: LogSQLLoginInfo foobar.baz.com logwriter passw0rd + Context: main server config + Defines the general parameters of the MySQL host to which you will be logging. "host" is the hostname or IP address of the MySQL machine, and is simply "localhost" if the database lives on the same machine as Apache. "user" is the MySQL userid (not a Unix userid!) with INSERT privileges on the table defined in LogSQLTransferLogTable. "password" is that user's password. + + This is defined only once in the httpd.conf file. + This directive Must be defined for logging to be enabled. Or the use of LogSQLDBParam + + + + + LogSQLDBParam + + + LogSQLDBParam + parameter-name + value + + Example: LogSQLDBParam database loggingdb + Context: main server config + This is the new method of specifying Database connection credentials and settings. This can be used to define all Database specific options and allows for a specific database driver to define new configuration attributes without modifying the mod_log_sql core. This is the preferred configuration mechanism. + + Each parameter-name may only be defined once. + Either this directive defining the minimum of 'database','host','user','passwd' or the use of LogSQlLoginInfo and LogSQLDatabase + + + + + LogSQLCreateTables + + + LogSQLCreateTables + flag + + Example: LogSQLCreateTables On + Default: Off + Context: main server config + 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). + 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. + + This is defined only once in the httpd.conf file. + + + + + LogSQLSocketFile [Deprecated] + + + LogSQLSocketFile + filename + + Example: LogSQLSocketFile /tmp/mysql.sock + Default: (database specific) + Default (MySQL): /var/lib/mysql/mysql.sock + Context: main server config + 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. + 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. + + This directive is deprecated in favor of LogSQLDBParam socketfile [socketfilename] + This is defined only once in the httpd.conf file. + + + + + LogSQLTCPPort [Deprecated] + + + LogSQLTCPPort + port-number + + Example: LogSQLTCPPort 3309 + Default: (database specific) + Default (MySQL): 3306 + Context: main server config + 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. + + This directive is deprecated in favor of LogSQLDBParam tcpport [port-number] + This is defined only once in the httpd.conf file. + + + + + LogSQLDatabase [Deprecated] + + + LogSQLDatabase + database + + Example: LogSQLDatabase loggingdb + Context: main server config + Defines the database that is used for logging. "database" must be a valid db on the MySQL host defined in LogSQLLoginInfo + + This directive is deprecated in favor of LogSQLDBParam database [database-name] + This is defined only once in the httpd.conf file. + This directive Must be defined for logging to be enabled. + + + + + LogSQLForcePreserve + + + LogSQLForcePreserve + flag + + Example: LogForcePreserve On + Default: Off + Context: main server config + 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. + 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. + + This is defined only once in the httpd.conf file. + + + + + LogSQLMachineID + + + LogSQLMachineID + machineID + + Example: LogSQLMachineID web01 + Context: main server config + 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. + + This is defined only once in the httpd.conf file. + + + + + LogSQlPreserveFile + + + LogSQLPreserveFile + filename + + Example: LogSQLPreserveFile offline-preserve + Default: /tmp/sql-preserve + Context: virtual host + 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: + # mysql -uadminuser -p mydbname < /tmp/sql-preserve + If you do not define LogSQLPreserveFile then all virtual servers will log to the same default preserve file (/tmp/sql-preserve). 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. + 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. + 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 & group ID of the running Apache process (e.g. 'nobody' on many Linux distributions). + + + + + + Table Names + + + LogSQLTransferLogTable + + + LogSQLTransferLogTable + table-name + + Example: LogSQLTransferLogTable access_log_table + Context: virtual host + 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 LogSQLDatabase. + This directive is not 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. + + Requires unless LogSQLMassVirtualHosting is set to On + + + + + LogSQLCookieLogTable + + + LogSQLCookieLogTable + table-name + + Example: LogSQLCookieLogTable cookie_log + Default: cookies + Context: virtual host + 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. + + You must create the table (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to "on". + + + + + LogSQLHeadersInLogTable + + + LogSQLHeadersInLogTable + table-name + + Example: LogSQLHeadersInLogTable headers + Default: headers_in + Context: virtual host + 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. + + Note that you must create the table (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to "on". + + + + + LogSQLHeadersOutLogTable + + + LogSQLHeadersOutLogTable + table-name + + Example: LogSQLHeadersOutLogTable headers + Default: headers_out + Context: virtual host + 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. + + Note that you must create the table (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to "on". + + + + + LogSQLNotesLogTable + + + LogSQLNotesLogTable + table-name + + Example: LogSQLNotesLogTable notes-log + Default: notes + Context: virtual_host + 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. + + This table must be created (see create-tables.sql included in the package), or LogSQLCreateTables must be set to 'On'. + + + + + LogSQLMassVirtualHosting + + + LogSQLMassVirtualHosting + flag + + Example: LogSQLMassVirtualHosting On + Default: Off + Context: main server config + 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: + + + the on-the-fly table creation feature is activated automatically + + + 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) + + + 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. + + + 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. + + This is defined only once in the httpd.conf file. + + + + + + + Configuring What Is logged + + + LogSQLRemhostIgnore + + + LogSQLRemhostIgnore + hostname + + Example: LogSQLRemhostIgnore localnet.com + Context: virtual host + Lists a series of strings that, if present in the REMOTE_HOST, will cause that request to not 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 for some tips for using this directive. + 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. + + + + LogSQLRequestAccept + + + LogSQLRequestAccept + hostname + + Example: LogSQLRequestAccept .html .php .jpg + Default: if not specified, all requests are 'accepted' + Context: virtual host + 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. + 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 for some tips for using this directive. + 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. + This directive is completely optional. It is more general than LogSQLRequestIgnore and is evaluated before LogSQLRequestIgnore . If this directive is not used, all 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. + + + + LogSQLRequestIgnore - + + LogSQLRequestIgnore + hostname + + Example: LogSQLRequestIgnore root.exe cmd.exe default.ida favicon.ico + Context: virtual host + Lists a series of strings that, if present in the URI, will cause that request to NOT 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 for some tips for using this directive. + 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. + + + + LogSQLTransferLogFormat + + + LogSQLTransferLogFormat + format-string + + Example: LogSQLTransferLogFormat huSUTv + Default: AbHhmRSsTUuv + Context: virtual host + 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: + TODO: Insert Log Format Types Table + + + + LogSQLWhichCookie + + + LogSQLWhichCookie + cookiename + + Example; LogSQLWhichCookie Clicks + Context: virtual host + 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. + 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. + + You must include a 'c' character in LogSQLTransferLogFormat for this directive to take effect. + 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. + + + + + LogSQLWhichCookies + + + LogSQLWhichCookies + cookie-name + + Example: logSQLWhichCookies userlogin cookie1 cookie2 + Context: virtual host + Defines the list of cookies you would like logged. This works in conjunction with LogSQLCookieLogTable. 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 cookie table with data. + + The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'. + + + + + LogSQLWhichHeadersIn + + + LogSQLWhichHeadersIn + header-name + + Example: LogSQLWhichHeadersIn UserAgent Accept-Encodeing Host + Context: virtual host + 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. + + The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'. + + + + + LogSQLWhichHeadersOut + + + LogSQLWhichHeadersOut + header-name + + Example: LogSQLWhichHeadersOut Expires Content-Type Cache-Control + Context: virtual host + 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. + + The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'. + + + + + LogSQLWhichNotes + + + LogSQLWhichNotes + note-name + + Example: LogSQLWhichNotes mod_gzip_result mod_gzip_ompression_ratio + Context: virtual host + 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. + + The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'. + @@ -1022,7 +1046,7 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg'; General module questions - + Why log to an SQL database? @@ -1212,7 +1236,7 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg'; Does mod_log_sql work with Apache 2.x? - Yes. A port of mod_log_sql is available for Apache 2.x, and is currently available and maintained at OutOfOrder.CC + Yes. A port of mod_log_sql is available for Apache 2.x as of mod_log_sql 1.90 @@ -1255,7 +1279,7 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg'; PHP and mod_log_sql can be configured to happily coexist. The solution is to configure PHP to link against the real MySQL libraries: recompile PHP using --with-mysql=/your/path. Apache will run properly once the modules are all using the same version of the MySQL libraries. - + Apache appears to start up fine, but nothing is getting logged in the database @@ -1266,17 +1290,17 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg'; Improper privileges set up in the MySQL database - You aren't hitting a VirtualHost that has a LogSQLTransferLogTable entry + You are not hitting a VirtualHost that has a LogSQLTransferLogTable entry - You didn't specify the right database host or login information + You did not specify the right database host or login information Another factor is preventing a connection to the database It is improper to ask for help before you have followed these steps. - First examine the MySQL log that you established in step of section . Ensure that the INSERT statements are not being rejected because of a malformed table name or other typographical error. By enabling that log, you instructed MySQL to log every connection and command it receives -- if you see no INSERT attempts in the log, the module isn't successfully connecting to the database. If you see nothing at all in the log -- not even a record of your administrative connection attempts, then you did not enable the log correctly. If you do see INSERT attempts but they are failing, the log should tell you why. + First examine the MySQL log that you established in step of section . Ensure that the INSERT statements are not being rejected because of a malformed table name or other typographical error. By enabling that log, you instructed MySQL to log every connection and command it receives -- if you see no INSERT attempts in the log, the module isn't successfully connecting to the database. If you see nothing at all in the log -- not even a record of your administrative connection attempts, then you did not enable the log correctly. If you do see INSERT attempts but they are failing, the log should tell you why. Second, confirm that your LogSQL* directives are all correct. Third, examine the Apache error logs for messages from mod_log_sql; the module will offer hints as to why it cannot connect, etc. The next thing to do is to change the LogLevel directive in the main server config as well as in each VirtualHost config: @@ -1297,7 +1321,7 @@ ErrorLog /var/log/httpd/server-messages My database cannot handle all the open connections from mod_log_sql, is there anything I can do? - The rule of thumb: if you have n webservers each configured to support y MaxClients, then your database must be able to handle n\times y simultenous connections in the worst case. Certainly you must use common sense, consider reasonable traffic expectations and structure things accordingly. + The rule of thumb: if you have n webservers each configured to support y MaxClients, then your database must be able to handle n times y simultaneous connections in the worst case. Certainly you must use common sense, consider reasonable traffic expectations and structure things accordingly. Tweaking my.cnf to scale to high connection loads is imperative. But if hardware limitations prevent your MySQL server from gracefully handling the number of incoming connections, it would be beneficial to upgrade the memory or CPU on that server in order to handle the load. @@ -1306,7 +1330,7 @@ ErrorLog /var/log/httpd/server-messages Jeremy Zawodny, a highly respected MySQL user and contributor to Linux Magazine, has this very helpful and highly appropriate article on tuning MySQL: MySQL, Linux, and Thread Caching - Please remember that mod_log_sql's overriding principle is performance -- that is what the target audience demands and expects. Other database logging solutions do not open and maintain many database connections, but their performance suffers drastically. For example, pgLOGd funnels all log connections through a separate daemon that connects to the database, but that bottlenecks the entire process. mod_log_sql achieves performance numbers an order of magnitude greater than the alternatives because it dispenses with the overhead associated with rapid connection cycling, and it doesn't attempt to shoehorn all the database traffic through a single extra daemon or proxy process. + Please remember that mod_log_sql's overriding principle is performance -- that is what the target audience demands and expects. Other database logging solutions do not open and maintain many database connections, but their performance suffers drastically. For example, pgLOGd funnels all log connections through a separate daemon that connects to the database, but that bottlenecks the entire process. mod_log_sql achieves performance numbers an order of magnitude greater than the alternatives because it dispenses with the overhead associated with rapid connection cycling, and it does not attempt to shoehorn all the database traffic through a single extra daemon or proxy process. Currently connection pooling is being implemented as part of the Database Abstraction layer to allow multiple httpd processes to share connections. @@ -1317,7 +1341,7 @@ ErrorLog /var/log/httpd/server-messages Why do I occasionally see a "lost connection to MySQL server" message in my Apache error log? - This message may appear every now and then in your Apache error log, especially on very lightly loaded servers. This doesn't mean that anything is necessarily wrong. Within each httpd child process, mod_log_sql will open (and keep open) a connection to the MySQL server. MySQL, however, will close connections that haven't been used in a while; the default timeout is 8 hours. When this occurs, mod_log_sql will notice and re-open the connection. That event is what is being logged, and looks like this: + This message may appear every now and then in your Apache error log, especially on very lightly loaded servers. This does not mean that anything is necessarily wrong. Within each httpd child process, mod_log_sql will open (and keep open) a connection to the MySQL server. MySQL, however, will close connections that have not been used in a while; the default timeout is 8 hours. When this occurs, mod_log_sql will notice and re-open the connection. That event is what is being logged, and looks like this: [Tue Nov 12 19:04:10 2002] [error] mod_log_sql: first attempt failed, API said: error 2013, Lost connection to MySQL server during query [Tue Nov 12 19:04:10 2002] [error] mod_log_sql: reconnect successful @@ -1429,8 +1453,8 @@ mysql> optimize table access_log; If you have exhausted all the tuning possibilities on your existing server, it is probably time you evaluated the benefits of clustering two or more webservers together in a load-balanced fashion. In fact, users of such a setup are mod_log_sql's target audience! - - + + What is the issue with activating delayed inserts? @@ -1449,7 +1473,7 @@ mysql> optimize table access_log; Instead of delayed inserts, you may wish to utilize InnoDB tables (instead of the standard MyISAM tables). InnoDB tables suppot row-level locking and are recommended for high-volume databases. - If after understanding these problems you still wish to enable delayed inserts, section discusses how. + If after understanding these problems you still wish to enable delayed inserts, section discusses how. @@ -1474,7 +1498,7 @@ rm -f /var/log/httpd/templog See? Easy. - + How can I log mod_usertrack cookies? @@ -1532,8 +1556,8 @@ rm -f /var/log/httpd/templog As of version 1.17, you have a choice in how you want cookie logging handled. - If you are interested in logging only one cookie per request, follow the instructions in section above. That cookie will be logged to a column in the regular access_log table, and the actual cookie you want to log is specified with LogSQLWhichCookie. Don't forget to specify the 'c' character in LogSQLTransferLogFormat. - If, however, you need to log multiple cookies per request, you must employ the LogSQLWhichCookies (note the plural) directive. The cookies you specify will be logged to a separate table (as discussed in section ), and entries in that table will be linked to the regular access_log entries via the unique ID that is supplied by mod_unique_id. Without mod_unique_id the information will still be logged but you will be unable to correlate which cookies go with which access-requests. Furthermore, with LogSQLWhichCookies, you do not need to include the 'c' character in LogSQLTransferLogFormat. + If you are interested in logging only one cookie per request, follow the instructions in FAQ entry above. That cookie will be logged to a column in the regular access_log table, and the actual cookie you want to log is specified with LogSQLWhichCookie. Don't forget to specify the 'c' character in LogSQLTransferLogFormat. + If, however, you need to log multiple cookies per request, you must employ the LogSQLWhichCookies (note the plural) directive. The cookies you specify will be logged to a separate table (as discussed in section ), and entries in that table will be linked to the regular access_log entries via the unique ID that is supplied by mod_unique_id. Without mod_unique_id the information will still be logged but you will be unable to correlate which cookies go with which access-requests. Furthermore, with LogSQLWhichCookies, you do not need to include the 'c' character in LogSQLTransferLogFormat. LogSQLWhichCookie and LogSQLWhichCookies can coexist without conflict because they operate on entireley different tables, but you're better off choosing the one you need. @@ -1556,7 +1580,7 @@ mysql> alter table access_log add column ssl_maxkeysize smallint unsigned; You also need to make sure you have the mod_log_sql_ssl module loaded as well. - The last three characters (Qqz) in the directive are the SSL ones; see section in the directives documentation for details of the LogSQLTransferLogFormat directive. + The last three characters (Qqz) in the directive are the SSL ones; see section in the directives documentation for details of the LogSQLTransferLogFormat directive. Restart Apache, then perform some hits on your server. Then run the following select statement: mysql> select remote_host,request_uri,ssl_cipher,ssl_keysize,ssl_maxkeysize from access_log where ssl_cipher is not null;
diff --git a/functions.h b/functions.h index 917a1f9..696ef60 100644 --- a/functions.h +++ b/functions.h @@ -1,4 +1,4 @@ -/* $Header: /home/cvs/mod_log_sql/functions.h,v 1.2 2004/02/05 21:59:46 urkle Exp $ */ +/* $Header: /home/cvs/mod_log_sql/functions.h,v 1.3 2004/03/04 05:41:12 urkle Exp $ */ /* Begin the individual functions that, given a request r, * extract the needed information from it and return the * value to the calling entity. @@ -175,18 +175,14 @@ static const char *extract_specific_cookie(request_rec *r, char *a) char *cookiebuf; if (a != NULL) { - #ifdef DEBUG - log_error(APLOG_MARK,APLOG_DEBUG, - r->server,"watching for cookie '%s'", a); - #endif + log_error(APLOG_MARK,APLOG_DEBUG, + r->server,"watching for cookie '%s'", a); /* Fetch out the cookie header */ cookiestr = (char *)apr_table_get(r->headers_in, "cookie2"); if (cookiestr != NULL) { - #ifdef DEBUG - log_error(APLOG_MARK,APLOG_DEBUG,r->server, - "Cookie2: [%s]", cookiestr); - #endif + log_error(APLOG_MARK,APLOG_DEBUG,r->server, + "Cookie2: [%s]", cookiestr); /* Does the cookie string contain one with our name? */ isvalid = strstr(cookiestr, a); if (isvalid != NULL) { diff --git a/mod_log_sql.c b/mod_log_sql.c index faac51e..bce803e 100644 --- a/mod_log_sql.c +++ b/mod_log_sql.c @@ -1,4 +1,4 @@ -/* $Id: mod_log_sql.c,v 1.17 2004/03/02 05:34:50 urkle Exp $ */ +/* $Id: mod_log_sql.c,v 1.18 2004/03/04 05:41:12 urkle Exp $ */ /* --------* * DEFINES * * --------*/ @@ -149,12 +149,13 @@ LOGSQL_DECLARE(void) log_sql_register_item(server_rec *s, apr_pool_t *p, static logsql_opendb_ret log_sql_opendb_link(server_rec* s) { logsql_opendb_ret result; - if (global_config.forcepreserve) + if (global_config.forcepreserve) { global_config.db.connected = 1; return LOGSQL_OPENDB_PRESERVE; - - if (global_config.db.connected) + } + if (global_config.db.connected) { return LOGSQL_OPENDB_ALREADY; + } /* database host user @@ -196,7 +197,7 @@ static void preserve_entry(request_rec *r, const char *query) result = (fp)?0:1; #endif if (result != APR_SUCCESS) { - log_error(APLOG_MARK,APLOG_ERR,r->server,"mod_log_sql: attempted append of local preserve file but failed."); + log_error(APLOG_MARK,APLOG_ERR,r->server,"attempted append of local preserve file '%s' but failed.",cls->preserve_file); } else { #if defined(WITH_APACHE20) apr_file_printf(fp,"%s;\n", query); @@ -205,9 +206,7 @@ static void preserve_entry(request_rec *r, const char *query) fprintf(fp,"%s;\n", query); ap_pfclose(r->pool, fp); #endif - #ifdef DEBUG - log_error(APLOG_MARK,APLOG_DEBUG,r->server,"mod_log_sql: entry preserved in %s", cls->preserve_file); - #endif + log_error(APLOG_MARK,APLOG_DEBUG,r->server,"mod_log_sql: entry preserved in %s", cls->preserve_file); } } @@ -367,17 +366,16 @@ static void log_sql_child_exit(server_rec *s, apr_pool_t *p) /* Child Init */ #if defined(WITH_APACHE20) static void log_sql_child_init(apr_pool_t *p, server_rec *s) -{ - apr_pool_cleanup_register(p, NULL, log_sql_close_link, log_sql_close_link); -} - -static int log_sql_open(apr_pool_t *pc, apr_pool_t *p, apr_pool_t *pt, server_rec *s) #elif defined(WITH_APACHE13) static void log_sql_child_init(server_rec *s, apr_pool_t *p) #endif { logsql_opendb_ret retval; - /* Open a link to the database */ +# if defined(WITH_APACHE20) + /* Register cleanup hook to close DDB connection (apache 2 doesn't have child_exit) */ + apr_pool_cleanup_register(p, NULL, log_sql_close_link, log_sql_close_link); +# endif + /* Open a link to the database */ retval = log_sql_opendb_link(s); switch (retval) { case LOGSQL_OPENDB_FAIL: @@ -391,9 +389,6 @@ static void log_sql_child_init(server_rec *s, apr_pool_t *p) log_error(APLOG_MARK,APLOG_DEBUG,s,"mod_log_sql: open_logdb_link said that preservation is forced"); break; } -#if defined(WITH_APACHE20) - return OK; -#endif } /* post_config / module_init */ @@ -403,12 +398,6 @@ static int log_sql_post_config(apr_pool_t *p, apr_pool_t *plog, apr_pool_t *ptem static void log_sql_module_init(server_rec *s, apr_pool_t *p) #endif { - /* Initialize Global configuration */ - if (!apr_table_get(global_config.db.parms,"socketfile")) - apr_table_setn(global_config.db.parms,"socketfile","/tmp/mysql.sock"); - if (!apr_table_get(global_config.db.parms,"tcpport")) - apr_table_setn(global_config.db.parms,"tcpport","3306"); - /* TODO: Add local_address, remote_address, server_name, connection_status */ /* Register handlers */ log_sql_register_item(s,p,'A', extract_agent, "agent", 1, 1); @@ -1063,10 +1052,6 @@ static const command_rec log_sql_cmds[] = { (void *)"database", RSRC_CONF, "The name of the database database for logging") , - AP_INIT_TAKE1("LogSQLDelayedInserts", set_dbparam_slot, - (void *)"insertdelayed", RSRC_CONF, - "Whether to use delayed inserts") - , AP_INIT_TAKE1("LogSQLTableType", set_dbparam_slot, (void *)"tabletype", RSRC_CONF, "What kind of table to create (MyISAM, InnoDB,...) when creating tables") @@ -1086,7 +1071,6 @@ static const command_rec log_sql_cmds[] = { static void register_hooks(apr_pool_t *p) { ap_hook_post_config(log_sql_post_config, NULL, NULL, APR_HOOK_REALLY_FIRST); ap_hook_child_init(log_sql_child_init, NULL, NULL, APR_HOOK_MIDDLE); - ap_hook_open_logs(log_sql_open, NULL, NULL, APR_HOOK_MIDDLE); ap_hook_log_transaction(log_sql_transaction, NULL, NULL, APR_HOOK_MIDDLE); } diff --git a/mod_log_sql_mysql.c b/mod_log_sql_mysql.c index d0666fe..86c259a 100644 --- a/mod_log_sql_mysql.c +++ b/mod_log_sql_mysql.c @@ -1,4 +1,4 @@ -/* $Id: mod_log_sql_mysql.c,v 1.2 2004/03/02 05:34:50 urkle Exp $ */ +/* $Id: mod_log_sql_mysql.c,v 1.3 2004/03/04 05:41:12 urkle Exp $ */ #include "mysql.h" #include "mysqld_error.h" @@ -35,13 +35,19 @@ logsql_opendb_ret log_sql_mysql_connect(server_rec *s, logsql_dbconnection *db) const char *user = apr_table_get(db->parms,"user"); const char *passwd = apr_table_get(db->parms,"passwd"); const char *database = apr_table_get(db->parms,"database"); - unsigned int tcpport = atoi(apr_table_get(db->parms,"tcpport")); + const char *s_tcpport = apr_table_get(db->parms,"tcpport"); + unsigned int tcpport = (s_tcpport)?atoi(s_tcpport):3306; const char *socketfile = apr_table_get(db->parms,"socketfile"); MYSQL *dblink = db->handle; dblink = mysql_init(dblink); db->handle = (void *)dblink; + + if (!socketfile) { + socketfile = "/var/lib/mysql/mysql.sock"; + } + if (mysql_real_connect(dblink, host, user, passwd, database, tcpport, socketfile, 0)) { log_error(APLOG_MARK,APLOG_DEBUG,s,"HOST: '%s' PORT: '%d' DB: '%s' USER: '%s' SOCKET: '%s'", -- cgit