clogger.git  about / heads / tags
configurable request logging for Rack
$ git log --pretty=format:'%h %s (%cs)%d' v1.0.1 --
d6328a6 clogger 1.0.1 - portability fixes (2011-06-22)
	(tag: v1.0.1)
7e3694c ext: fix portability defines for some installs (2011-06-22)
5979a9b tests: add full URL example (2011-05-11)
bcb9fb8 change from LGPLv2.1+ to LGPLv2.1 + LGPLv3 (2011-04-26)
edd2bd2 clogger 1.0.0 - \o/ (2011-04-21)
	(tag: v1.0.0)
b7459a2 README: stop promoting strftime()-compatible formats (2011-04-19)
0a2cb50 $time_local and $time_utc are locale-independent (2011-04-19)
8303d47 add support for $time_iso8601 format (2011-04-16)
a84b132 extconf: unnecessary dir_config statement (2011-03-21)
b086541 :format may be a Symbol for less typing (2011-03-16)
...

$ git cat-file blob v1.0.1:README
= \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.

== FEATURES

* 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
  and supported under MRI 1.8.7, 1.9.1, 1.9.2 and Rubinius.

== SYNOPSIS

\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 => 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 => 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

== VARIABLES

* $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} - 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).
* $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{Actor.current} - Actor processing the request (Revactor or Rubinius)

== REQUIREMENTS

* {Ruby}[http://ruby-lang.org/], {Rack}[http://rack.rubyforge.org/]

== DEVELOPMENT

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

   git://bogomips.org/clogger.git
   git://repo.or.cz/clogger.git

You may also browse and download snapshot tarballs:

* http://bogomips.org/clogger.git (cgit)
* http://repo.or.cz/w/clogger.git (gitweb)

The mailing list (see below) is central for coordination and
development.  Patches should always be sent inline
(git format-patch -M + git send-email) so we can reply to them inline.

== CONTACT

All feedback (bug reports, user/development discussion, patches, pull
requests) go to the mailing list.

* mailto:clogger@librelist.com

Do not send HTML mail or attachments.  Do not top post.

Homepage: http://clogger.rubyforge.org/

== INSTALL

For Rubygems users:

  gem install clogger

If you do not use Rubygems, you may also use setup.rb from the tarballs
on the Rubyforge project page:

* http://rubyforge.org/frs/?group_id=8896

There is an optional C extension that should be compatible with MRI
1.8/1.9.  The extensions should automatically be disabled for users of
other Ruby implementations, but be sure to let us know if that's not the
case.  No pre-built binaries are currently distributed, let us know if
you're interested in helping with the release/support effort.

# heads (aka `branches'):
$ git for-each-ref --sort=-creatordate refs/heads \
	--format='%(HEAD) %(refname:short) %(subject) (%(creatordate:short))'
* master       switch to TypedData macros for allocation (2024-02-01)
  respond_to-priv SQUASH/WIP - use rb_funcallv to handle second respond_to arg (2017-05-21)

# tags:
$ git for-each-ref --sort=-creatordate refs/tags \
	--format='%(refname:short) %(subject) (%(creatordate:short))'
v2.4.0       clogger 2.4.0 (2022-06-16) tar.gz
v2.3.1       clogger 2.3.1 (2021-05-25) tar.gz
v2.3.0       clogger 2.3.0 - $request_time{POWER,PRECISION} support (2020-08-10) tar.gz
v2.2.1       clogger 2.2.1 - move away from .org TLD (2020-01-08) tar.gz
v2.2.0       clogger v2.2.0 - Rack 2.x compatibility fix (2017-05-23) tar.gz
v2.1.0       clogger 2.1.0 - rack 2.x compatibility and more! (2016-07-28) tar.gz
v2.0.2       clogger 2.0.2 - bugfixes for pure Ruby users (2015-02-27) tar.gz
v2.0.1       clogger 2.0.1 - doc updates and new mailing list (2015-01-13) tar.gz
v2.0.0       clogger 2.0.0 - updated website URL, cleanups (2014-05-12) tar.gz
v1.4.0       clogger 1.4.0 - updated website URL, cleanups (2014-05-12) tar.gz
...

# associated public inboxes:
# (number on the left is used for dev purposes)
            https://yhbt.net/clogger-public

git clone https://yhbt.net/clogger.git