README.txt

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