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