Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/pat/clogger-rack2

Patched Clogger that supports Rack v2
https://github.com/pat/clogger-rack2

Last synced: about 7 hours ago
JSON representation

Patched Clogger that supports Rack v2

Awesome Lists containing this project

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

  under C Ruby and under Rubinius, too.



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



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

* $env{variable_name} - any Rack environment variable (e.g. rack.url_scheme)



== REQUIREMENTS



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



== DEVELOPMENT



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



   git clone git://bogomips.org/clogger.git

   git clone git://repo.or.cz/clogger.git



You may also browse and download snapshot tarballs:



* https://bogomips.org/clogger.git

* 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 public mailing list.



* mailto:[email protected]



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



Homepage: https://bogomips.org/clogger/



== INSTALL



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

case.