clogger v2.2.0 - Rack 2.x compatibility fix
[clogger.git] / README
blob890ba78aaa06c57e9f6433260c8f7f8d26e4605c
1 = clogger - configurable request logging for Rack
3 clogger is Rack middleware for logging HTTP requests.  The log format
4 is customizable so you can specify exactly which fields to log.
6 == FEATURES
8 * highly customizable with easy-to-read nginx-like log format variables.
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.
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:
17     ' (single quote)
18     " (double quote)
19     all bytes in the range of \x00-\x1F
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.
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   under C Ruby and under Rubinius, too.
29 == SYNOPSIS
31 clogger may be loaded as Rack middleware in your config.ru:
33   # ENV['CLOGGER_PURE'] = '1' # uncomment to disable C extension
34   require "clogger"
35   use Clogger,
36       :format => :Combined,
37       :path => "/path/to/log",
38       :reentrant => true
39   run YourApplication.new
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:
44   config.middleware.use 'Clogger',
45       :format => :Combined,
46       :path => "/path/to/log",
47       :reentrant => false
49 Instead of specifying a :path, you may also specify a :logger object
50 that receives a "<<" method:
52   use Clogger, :logger=> $stdout, :reentrant => true
53   run YourApplication.new
55 == VARIABLES
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 * $env{variable_name} - any Rack environment variable (e.g. rack.url_scheme)
93 == REQUIREMENTS
95 * {Ruby}[https://www.ruby-lang.org/], {Rack}[https://rack.github.io/]
97 == DEVELOPMENT
99 The latest development happens in git and is published to the following:
101    git clone git://bogomips.org/clogger.git
102    git clone git://repo.or.cz/clogger.git
104 You may also browse and download snapshot tarballs:
106 * https://bogomips.org/clogger.git
107 * http://repo.or.cz/w/clogger.git (gitweb)
109 The mailing list (see below) is central for coordination and
110 development.  Patches should always be sent inline
111 (git format-patch -M + git send-email) so we can reply to them inline.
113 == CONTACT
115 All feedback (bug reports, user/development discussion, patches, pull
116 requests) go to the public mailing list.
118 * mailto:clogger-public@bogomips.org
120 Do not send HTML mail or attachments.  Do not top post.
122 Homepage: https://bogomips.org/clogger/
124 == INSTALL
126 For RubyGems users:
128   gem install clogger
130 There is an optional C extension that should be compatible with
131 MatzRuby.  The extensions should automatically be disabled for users of
132 other Ruby implementations, but be sure to let us know if that's not the
133 case.