README

   1 = raindrops - real-time stats for preforking Rack servers
   2
   3 Raindrops is a real time stats package to show statistics for Rack HTTP
   4 servers.  It is designed for preforking servers such as Rainbows! and
   5 Unicorn, but should support any Rack HTTP server under Ruby 1.9, 1.8 and
   6 possibly Rubinius (untested) on platforms supporting POSIX shared memory
   7 and compiled with GCC (for atomic builtins).
   8
   9 Raindrops includes a Struct-like Raindrops::Struct class that may be used
  10 standalone to create atomic counters shared across any number of forked
  11 processes under SMP.
  12
  13 == Features
  14
  15 * counters are shared across all forked children and lock-free
  16
  17 * counters are kept on separate cache lines to reduce contention under SMP
  18
  19 * may expose server statistics as a Rack Middleware endpoint
  20   (default: "/_raindrops")
  21
  22 * middleware displays the number of actively processing and writing
  23   clients from a single request regardless of which worker process
  24   it hits.
  25
  26 == Linux-only Extra Features!
  27
  28 * Middleware response includes extra stats for bound TCP and
  29   Unix domain sockets (configurable, it can include stats from
  30   other TCP or UNIX domain socket servers).
  31
  32 * TCP socket stats use efficient inet_diag facilities via netlink
  33   instead of parsing /proc/net/tcp to minimize overhead.
  34   This was fun to discover and write.
  35
  36 == Install
  37
  38 raindrops requires GCC 4.x (or compatible) or later to support the
  39 atomic builtins (__sync_{add,sub}_and_fetch()).  Atomic operations on
  40 other compilers may be supported if there is demand.
  41
  42 If you're using a packaged Ruby distribution, make sure you have a C
  43 compiler and the matching Ruby development libraries and headers.
  44
  45 If you use RubyGems:
  46
  47     gem install raindrops
  48
  49 Otherwise grab the latest tarball from:
  50
  51 http://raindrops.bogomips.org/files/
  52
  53 Unpack it, and run "ruby setup.rb"
  54
  55 == Usage (Rainbows!/Unicorn preload_app=false)
  56
  57 If you're using preload_app=false (the default) in your Rainbows!/Unicorn
  58 config file, you'll need to create the global Stats object before
  59 forking.
  60
  61         require 'raindrops'
  62         $stats ||= Raindrops::Middleware::Stats.new
  63
  64 In your Rack config.ru:
  65
  66         use Raindrops::Middleware, :stats => $stats
  67
  68 == Usage (Rainbows!/Unicorn preload_app=true)
  69
  70 If you're using preload_app=true in your Rainbows!/Unicorn
  71 config file, just add the middleware to your stack:
  72
  73 In your Rack config.ru:
  74
  75         use Raindrops::Middleware
  76
  77 == Usage (Linux-extras)
  78
  79 To get bound listener statistics under Linux, you need to specify the
  80 listener names for your server.  You can even include listen sockets for
  81 *other* servers on the same machine.  This can be handy for monitoring
  82 your nginx proxy as well.
  83
  84 In your Rack config.ru, just pass the :listeners argument as an array of
  85 strings (along with any other arguments).  You can specify any
  86 combination of TCP or Unix domain socket names:
  87
  88         use Raindrops::Middleware, :listeners => %w(0.0.0.0:80 /tmp/.sock)
  89
  90 See the tests/ and examples/ directory for more examples
  91
  92 == Development
  93
  94 You can get the latest source via git from the following locations:
  95
  96   git://git.bogomips.org/raindrops.git
  97   git://repo.or.cz/raindrops.git (mirror)
  98
  99 You may browse the code from the web and download the latest snapshot
 100 tarballs here:
 101
 102 * http://git.bogomips.org/cgit/raindrops.git (cgit)
 103 * http://repo.or.cz/w/raindrops.git (gitweb)
 104
 105 Inline patches (from "git format-patch") to the mailing list are
 106 preferred because they allow code review and comments in the reply to
 107 the patch.
 108
 109 We will adhere to mostly the same conventions for patch submissions as
 110 git itself.  See the Documentation/SubmittingPatches document
 111 distributed with git on on patch submission guidelines to follow.  Just
 112 don't email the git mailing list or maintainer with raindrops patches.
 113
 114 == Contact
 115
 116 All feedback (bug reports, user/development discussion, patches, pull
 117 requests) go to the mailing list: mailto:raindrops@librelist.com