README

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