= \Clogger - configurable request logging for Rack \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 and 1.1) 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 * multi-instance capable and (optionally) reentrant. You can use \Clogger in a multi-threaded server, and even multiple Cloggers logging to different locations and different formats in the same process. * Pure Ruby version for non-MRI versions of Ruby (or via CLOGGER_PURE=1 in the environment). The optional C extension is loaded by default and supported under MRI 1.8.7, 1.9.1, 1.9.2 and Rubinius. == SYNOPSIS \Clogger may be loaded as Rack middleware in your config.ru: # ENV['CLOGGER_PURE'] = '1' # uncomment to disable C extension require "clogger" use Clogger, :format => Clogger::Format::Combined, :path => "/path/to/log", :reentrant => true 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, :path => "/path/to/log", :reentrant => false Instead of specifying a :path, you may also specify a :logger object that receives a "<<" method: use Clogger, :logger=> $stdout, :reentrant => true run YourApplication.new == 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_iso8601 - current local time in ISO 8601 format, e.g. "1970-01-01T00:00:00+00:00" * $time_local - current local time in Apache log format, e.g. "01/Jan/1970:00:00:00 +0000" * $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 * $status - three-digit HTTP status code (e.g. 200, 404, 302) * $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}[http://ruby-lang.org/], {Rack}[http://rack.rubyforge.org/] == DEVELOPMENT The latest development happens in git and is published to the following: git://bogomips.org/clogger.git git://repo.or.cz/clogger.git You may also browse and download snapshot tarballs: * http://bogomips.org/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 discussion, patches, pull requests) go to the mailing list. * mailto:clogger@librelist.org Do not send HTML mail or attachments. Do not top post. Homepage: http://clogger.rubyforge.org/ == INSTALL For Rubygems users: gem install clogger If you do not use Rubygems, you may also use setup.rb from the tarballs on the Rubyforge project page: * http://rubyforge.org/frs/?group_id=8896 There is an optional C extension that should be compatible with MRI 1.8/1.9. The extensions should automatically be disabled for users of other Ruby implementations, but be sure to let us know if that's not the case. No pre-built binaries are currently distributed, let us know if you're interested in helping with the release/support effort.