README

   1 = clogger - configurable request logging for Rack
   2
   3 clogger is Rack middleware for logging HTTP requests.  The log format
   4 is customizable so you can specify exactly which fields to log.
   5
   6 == FEATURES
   7
   8 * highly customizable with easy-to-read nginx-like log format variables.
   9
  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.
  13
  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:
  16
  17     ' (single quote)
  18     " (double quote)
  19     all bytes in the range of \x00-\x1F
  20
  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.
  24
  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.
  28
  29 == SYNOPSIS
  30
  31 clogger may be loaded as Rack middleware in your config.ru:
  32
  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
  40
  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:
  43
  44   config.middleware.use 'Clogger',
  45       :format => :Combined,
  46       :path => "/path/to/log",
  47       :reentrant => false
  48
  49 Instead of specifying a :path, you may also specify a :logger object
  50 that receives a "<<" method:
  51
  52   use Clogger, :logger=> $stdout, :reentrant => true
  53   run YourApplication.new
  54
  55 == VARIABLES
  56
  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}, $request_time{POWER,PRECISION} -
  73   time taken for request (including response body iteration). PRECISION
  74   defaults to 3 (milliseconds) if not specified but may be specified
  75   anywhere from 0(seconds) to 6(microseconds). POWER will raise the time to
  76   the provided power of 10, useful for converting to micro- or nanoseconds.
  77   POWER defaults to 0 if not specified but may be specified any from 0 to 9
  78 * $time_iso8601 - current local time in ISO 8601 format,
  79   e.g. "1970-01-01T00:00:00+00:00"
  80 * $time_local - current local time in Apache log format,
  81   e.g. "01/Jan/1970:00:00:00 +0000"
  82 * $usec - current time in seconds.microseconds since the Epoch
  83 * $msec - current time in seconds.milliseconds since the Epoch
  84 * $body_bytes_sent - bytes in the response body (Apache: %B)
  85 * $response_length - body_bytes_sent, except "-" instead of "0" (Apache: %b)
  86 * $remote_user - HTTP-authenticated user
  87 * $remote_addr - IP of the requesting client socket
  88 * $status - three-digit HTTP status code (e.g. 200, 404, 302)
  89 * $ip - X-Forwarded-For request header if available, $remote_addr if not
  90 * $pid - process ID of the current process
  91 * $e{Thread.current} - Thread processing the request
  92 * $e{Fiber.current} - Fiber processing the request
  93 * $env{variable_name} - any Rack environment variable (e.g. rack.url_scheme)
  94
  95 == REQUIREMENTS
  96
  97 * {Ruby}[https://www.ruby-lang.org/], {Rack}[https://rack.github.io/]
  98
  99 == DEVELOPMENT
 100
 101 The latest development happens in git and is published to the following:
 102
 103    git clone https://YHBT.net/clogger.git
 104    git clone https://repo.or.cz/clogger.git
 105
 106 You may also browse and download snapshot tarballs:
 107
 108 * https://YHBT.net/clogger.git
 109 * https://repo.or.cz/w/clogger.git (gitweb)
 110
 111 We use email for coordination and development, see below:
 112
 113 == CONTACT
 114
 115 All feedback (bug reports, user/development discussion, patches, pull
 116 requests) is done via publicly-archived email:
 117
 118 * https://YHBT.net/clogger-public/
 119 * imaps://YHBT.net/inbox.comp.lang.ruby.clogger.0
 120 * nntps://news.public-inbox.org/inbox.comp.lang.ruby.clogger
 121
 122 Tor users may also access HTTP, IMAP, and NNTP archives via .onion:
 123
 124 * http://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/clogger-public/
 125 * imap://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/inbox.comp.lang.ruby.clogger.0
 126 * nntp://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/inbox.comp.lang.ruby.clogger
 127
 128 AUTH=ANONYMOUS is supported for IMAP and IMAPS, and any
 129 username + password will work.
 130
 131 No subscription or real names will ever be required to email us.
 132 Do not send HTML email, do not top post.
 133
 134 * mailto:clogger-public@YHBT.net
 135
 136 Homepage: https://YHBT.net/clogger/
 137
 138 == INSTALL
 139
 140 For RubyGems users:
 141
 142   gem install clogger
 143
 144 There is an optional C extension that should be compatible with
 145 MatzRuby.  The extensions should automatically be disabled for users of
 146 other Ruby implementations, but be sure to let us know if that's not the
 147 case.