README

   1 = \Clogger - configurable request logging for Rack
   2
   3 \Clogger is Rack middleware for logging HTTP requests.  The log format
   4 is customizable so you can specify exactly which fields to log.
   5
   6 == FEATURES
   7
   8 * highly customizable with easy-to-read nginx-like log format variables.
   9
  10 * pre-defines Apache Common Log Format, Apache Combined Log Format and
  11   Rack::CommonLogger (as distributed by Rack 1.0 and 1.1) formats.
  12   See Clogger::Format for the predefined formats.
  13
  14 * Untrusted values are escaped (all HTTP headers, request URI components)
  15   to make life easier for HTTP log parsers. The following bytes are escaped:
  16
  17     ' (single quote)
  18     " (double quote)
  19     all bytes in the range of \x00-\x1F
  20
  21 * multi-instance capable and (optionally) reentrant.  You can use
  22   \Clogger in a multi-threaded server, and even multiple Cloggers logging
  23   to different locations and different formats in the same process.
  24
  25 * Pure Ruby version for non-MRI versions of Ruby (or via CLOGGER_PURE=1
  26   in the environment).  The optional C extension is loaded by default
  27   and supported under MRI 1.8.7, 1.9.1, 1.9.2 and Rubinius.
  28
  29 == SYNOPSIS
  30
  31 \Clogger may be loaded as Rack middleware in your config.ru:
  32
  33   # ENV['CLOGGER_PURE'] = '1' # uncomment to disable C extension
  34   require "clogger"
  35   use Clogger,
  36       :format => Clogger::Format::Combined,
  37       :path => "/path/to/log",
  38       :reentrant => true
  39   run YourApplication.new
  40
  41 If you're using Rails 2.3.x or later, in your config/environment.rb
  42 somewhere inside the "Rails::Initializer.run do |config|" block:
  43
  44   config.middleware.use 'Clogger',
  45       :format => Clogger::Format::Combined,
  46       :path => "/path/to/log",
  47       :reentrant => false
  48
  49 Instead of specifying a :path, you may also specify a :logger object
  50 that receives a "<<" method:
  51
  52   use Clogger, :logger=> $stdout, :reentrant => true
  53   run YourApplication.new
  54
  55 == VARIABLES
  56
  57 * $http_* - HTTP request headers (e.g. $http_user_agent)
  58 * $sent_http_* - HTTP response headers (e.g. $sent_http_content_length)
  59 * $content_length - HTTP request body size
  60   ($http_content_length is not allowed by Rack)
  61 * $content_type - HTTP request content type
  62   ($http_content_type is not allowed by Rack)
  63 * $cookie_* - HTTP request cookie (e.g. $cookie_session_id)
  64   Rack::Request#cookies must have been used by the underlying application
  65   to parse the cookies into a hash.
  66 * $request_method - the HTTP request method (e.g. GET, POST, HEAD, ...)
  67 * $path_info - path component requested (e.g. /index.html)
  68 * $query_string - request query string (not including leading "?")
  69 * $request_uri - the URI requested ($path_info?$query_string)
  70 * $request - the first line of the HTTP request
  71   ($request_method $request_uri $http_version)
  72 * $request_time, $request_time{PRECISION} - time taken for request
  73   (including response body iteration).  PRECISION defaults to 3
  74   (milliseconds) if not specified but may be specified anywhere from
  75   0(seconds) to 6(microseconds).
  76 * $time_iso8601 - current local time in ISO 8601 format,
  77   e.g. "1970-01-01T00:00:00+00:00"
  78 * $time_local - current local time in Apache log format,
  79   e.g. "01/Jan/1970:00:00:00 +0000"
  80 * $usec - current time in seconds.microseconds since the Epoch
  81 * $msec - current time in seconds.milliseconds since the Epoch
  82 * $body_bytes_sent - bytes in the response body (Apache: %B)
  83 * $response_length - body_bytes_sent, except "-" instead of "0" (Apache: %b)
  84 * $remote_user - HTTP-authenticated user
  85 * $remote_addr - IP of the requesting client socket
  86 * $status - three-digit HTTP status code (e.g. 200, 404, 302)
  87 * $ip - X-Forwarded-For request header if available, $remote_addr if not
  88 * $pid - process ID of the current process
  89 * $e{Thread.current} - Thread processing the request
  90 * $e{Actor.current} - Actor processing the request (Revactor or Rubinius)
  91
  92 == REQUIREMENTS
  93
  94 * {Ruby}[http://ruby-lang.org/], {Rack}[http://rack.rubyforge.org/]
  95
  96 == DEVELOPMENT
  97
  98 The latest development happens in git and is published to the following:
  99
 100    git://bogomips.org/clogger.git
 101    git://repo.or.cz/clogger.git
 102
 103 You may also browse and download snapshot tarballs:
 104
 105 * http://bogomips.org/clogger.git (cgit)
 106 * http://repo.or.cz/w/clogger.git (gitweb)
 107
 108 The mailing list (see below) is central for coordination and
 109 development.  Patches should always be sent inline
 110 (git format-patch -M + git send-email) so we can reply to them inline.
 111
 112 == CONTACT
 113
 114 All feedback (bug reports, user/development discussion, patches, pull
 115 requests) go to the mailing list.
 116
 117 * mailto:clogger@librelist.org
 118
 119 Do not send HTML mail or attachments.  Do not top post.
 120
 121 Homepage: http://clogger.rubyforge.org/
 122
 123 == INSTALL
 124
 125 For Rubygems users:
 126
 127   gem install clogger
 128
 129 If you do not use Rubygems, you may also use setup.rb from the tarballs
 130 on the Rubyforge project page:
 131
 132 * http://rubyforge.org/frs/?group_id=8896
 133
 134 There is an optional C extension that should be compatible with MRI
 135 1.8/1.9.  The extensions should automatically be disabled for users of
 136 other Ruby implementations, but be sure to let us know if that's not the
 137 case.  No pre-built binaries are currently distributed, let us know if
 138 you're interested in helping with the release/support effort.