about summary refs log tree commit homepage
= clogger - configurable request logging for Rack

clogger is Rack middleware for logging HTTP requests.  The log format
is customizable so you can specify exactly which fields to log.


* highly customizable with easy-to-read nginx-like log format variables.

* pre-defines Apache Common Log Format, Apache Combined Log Format and
  Rack::CommonLogger (as distributed by Rack 1.0 and 1.1) formats.
  See Clogger::Format for the predefined formats.

* Untrusted values are escaped (all HTTP headers, request URI components)
  to make life easier for HTTP log parsers. The following bytes are escaped:

    ' (single quote)
    " (double quote)
    all bytes in the range of \x00-\x1F

* multi-instance capable and (optionally) reentrant.  You can use
  clogger in a multi-threaded server, and even multiple cloggers logging
  to different locations and different formats in the same process.

* Pure Ruby version for non-MRI versions of Ruby (or via CLOGGER_PURE=1
  in the environment).  The optional C extension is loaded by default
  under C Ruby and under Rubinius, too.


clogger may be loaded as Rack middleware in your config.ru:

  # ENV['CLOGGER_PURE'] = '1' # uncomment to disable C extension
  require "clogger"
  use Clogger,
      :format => :Combined,
      :path => "/path/to/log",
      :reentrant => true
  run YourApplication.new

If you're using Rails 2.3.x or later, in your config/environment.rb
somewhere inside the "Rails::Initializer.run do |config|" block:

  config.middleware.use 'Clogger',
      :format => :Combined,
      :path => "/path/to/log",
      :reentrant => false

Instead of specifying a :path, you may also specify a :logger object
that receives a "<<" method:

  use Clogger, :logger=> $stdout, :reentrant => true
  run YourApplication.new


* $http_* - HTTP request headers (e.g. $http_user_agent)
* $sent_http_* - HTTP response headers (e.g. $sent_http_content_length)
* $content_length - HTTP request body size
  ($http_content_length is not allowed by Rack)
* $content_type - HTTP request content type
  ($http_content_type is not allowed by Rack)
* $cookie_* - HTTP request cookie (e.g. $cookie_session_id)
  Rack::Request#cookies must have been used by the underlying application
  to parse the cookies into a hash.
* $request_method - the HTTP request method (e.g. GET, POST, HEAD, ...)
* $path_info - path component requested (e.g. /index.html)
* $query_string - request query string (not including leading "?")
* $request_uri - the URI requested ($path_info?$query_string)
* $request - the first line of the HTTP request
  ($request_method $request_uri $http_version)
* $request_time, $request_time{PRECISION}, $request_time{POWER,PRECISION} -
  time taken for request (including response body iteration). PRECISION
  defaults to 3 (milliseconds) if not specified but may be specified
  anywhere from 0(seconds) to 6(microseconds). POWER will raise the time to
  the provided power of 10, useful for converting to micro- or nanoseconds.
  POWER defaults to 0 if not specified but may be specified any from 0 to 9
* $time_iso8601 - current local time in ISO 8601 format,
  e.g. "1970-01-01T00:00:00+00:00"
* $time_local - current local time in Apache log format,
  e.g. "01/Jan/1970:00:00:00 +0000"
* $usec - current time in seconds.microseconds since the Epoch
* $msec - current time in seconds.milliseconds since the Epoch
* $body_bytes_sent - bytes in the response body (Apache: %B)
* $response_length - body_bytes_sent, except "-" instead of "0" (Apache: %b)
* $remote_user - HTTP-authenticated user
* $remote_addr - IP of the requesting client socket
* $status - three-digit HTTP status code (e.g. 200, 404, 302)
* $ip - X-Forwarded-For request header if available, $remote_addr if not
* $pid - process ID of the current process
* $e{Thread.current} - Thread processing the request
* $e{Fiber.current} - Fiber processing the request
* $env{variable_name} - any Rack environment variable (e.g. rack.url_scheme)


* {Ruby}[https://www.ruby-lang.org/], {Rack}[https://rack.github.io/]


The latest development happens in git and is published to the following:

   git clone https://YHBT.net/clogger.git
   git clone https://repo.or.cz/clogger.git

You may also browse and download snapshot tarballs:

* https://YHBT.net/clogger.git
* https://repo.or.cz/w/clogger.git (gitweb)

We use email for coordination and development, see below:


All feedback (bug reports, user/development discussion, patches, pull
requests) is done via publicly-archived email:

* https://YHBT.net/clogger-public/
* imaps://YHBT.net/inbox.comp.lang.ruby.clogger.0
* nntps://news.public-inbox.org/inbox.comp.lang.ruby.clogger

Tor users may also access HTTP, IMAP, and NNTP archives via .onion:

* http://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/clogger-public/
* imap://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/inbox.comp.lang.ruby.clogger.0
* nntp://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/inbox.comp.lang.ruby.clogger

AUTH=ANONYMOUS is supported for IMAP and IMAPS, and any
username + password will work.

No subscription or real names will ever be required to email us.
Do not send HTML email, do not top post.

* mailto:clogger-public@YHBT.net

Homepage: https://YHBT.net/clogger/


For RubyGems users:

  gem install clogger

There is an optional C extension that should be compatible with
MatzRuby.  The extensions should automatically be disabled for users of
other Ruby implementations, but be sure to let us know if that's not the