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