diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 137 |
1 files changed, 137 insertions, 0 deletions
@@ -0,0 +1,137 @@ += Clogger - configurable request logging for Rack + +* http://clogger.rubyforge.org/ +* mailto:clogger@librelist.com + +== DESCRIPTION + +Clogger is Rack middleware for logging HTTP requests. The log format +is customizable so you can specify exactly which fields to log. + +== FEATURES + +* highly customizable with easy-to-read nginx-like log format variables. + +* pre-defines Apache Common Log Format, Apache Combined Log Format and + Rack::CommonLogger (as distributed by Rack 1.0) formats. + See Clogger::Format for the predefined formats. + +* Untrusted values are escaped (all HTTP headers, request URI components) + to make life easier for HTTP log parsers. The following bytes are escaped: + + ' (single quote) + " (double quote) + all bytes in the range of \x00-\x1F + +== SYNOPSIS + +Clogger may be loaded as Rack middleware in your config.ru: + + require "clogger" + use Clogger, + :format => Clogger::Format::Combined, + :logger => File.open("/path/to/log", "ab") + run YourApplication.new + +If you're using Rails 2.3.x or later, in your config/environment.rb +somewhere inside the "Rails::Initializer.run do |config|" block: + + config.middleware.use 'Clogger', + :format => Clogger::Format::Combined, + :logger => File.open("/path/to/log", "ab") + +== VARIABLES + +* $http_* - HTTP request headers (e.g. $http_user_agent) +* $sent_http_* - HTTP response headers (e.g. $sent_http_content_length) +* $content_length - HTTP request body size + ($http_content_length is not allowed by Rack) +* $content_type - HTTP request content type + ($http_content_type is not allowed by Rack) +* $cookie_* - HTTP request cookie (e.g. $cookie_session_id) + Rack::Request#cookies must have been used by the underlying application + to parse the cookies into a hash. +* $request_method - the HTTP request method (e.g. GET, POST, HEAD, ...) +* $path_info - path component requested (e.g. /index.html) +* $query_string - request query string (not including leading "?") +* $request_uri - the URI requested ($path_info?$query_string) +* $request - the first line of the HTTP request + ($request_method $request_uri $http_version) +* $request_time, $request_time{PRECISION} - time taken for request + (including response body iteration). PRECISION defaults to 3 + (milliseconds) if not specified but may be specified anywhere from + 0(seconds) to 6(microseconds). +* $time_local, $time_local{FORMAT} - current local time, FORMAT defaults to + "%d/%b/%Y:%H:%M:%S %z" but accepts any strftime(3)-compatible format +* $time_utc, $time_utc{FORMAT} - like $time_local, except with UTC +* $usec - current time in seconds.microseconds since the Epoch +* $msec - current time in seconds.milliseconds since the Epoch +* $body_bytes_sent - bytes in the response body (Apache: %B) +* $response_length - body_bytes_sent, except "-" instead of "0" (Apache: %b) +* $remote_user - HTTP-authenticated user +* $remote_addr - IP of the requesting client socket +* $ip - X-Forwarded-For request header if available, $remote_addr if not +* $pid - process ID of the current process +* $e{Thread.current} - Thread processing the request +* $e{Actor.current} - Actor processing the request (Revactor or Rubinius) + +== REQUIREMENTS + +* Ruby, Rack + +== DEVELOPMENT + +The latest development happens in git and is published to the following: + + git://git.bogomips.org/clogger.git + git://repo.or.cz/clogger.git + +You may also browse and download snapshot tarballs: + +* http://git.bogomips.org/cgit/clogger.git (cgit) +* http://repo.or.cz/w/clogger.git (gitweb) + +The mailing list (see below) is central for coordination and +development. Patches should always be sent inline +(git format-patch -M + git send-email) so we can reply to them inline. + +== CONTACT + +All feedback (bug reports, user/development dicussion, patches, pull +requests) go to the mailing list. + +* mailto:clogger@librelist.com + +Do not send HTML mail or attachments. Do not top post. + +== INSTALL + +For all Rubygems users: + + gem install clogger + +If you're using MRI 1.8/1.9 and have a build environment, you can also try: + + gem install clogger_ext + +If you do not use Rubygems, you may also use setup.rb from tarballs from +the Rubyforge project page: + +* http://rubyforge.org/frs/?group_id=8896 + +== LICENSE + +Copyright (C) 2009 Eric Wong <normalperson@yhbt.net> and contributors. + +Clogger is free software; you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the +Free Software Foundation, version 3.0. + +Clogger is distributed in the hope that it will be useful, but WITHOUT ANY +WARRANTY; without even the implied warranty of MERCHANTABILITY or +FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public +License for more details. + +You should have received a copy of the GNU Lesser General Public License +along with Clogger; if not, write to the Free Software Foundation, Inc., +51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 |