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 Rubinius on platforms supporting POSIX shared memory.
   7
   8 Raindrops includes a Struct-like Raindrops::Struct class that may be used
   9 standalone to create atomic counters shared across any number of forked
  10 processes under SMP.
  11
  12 == Features
  13
  14 * counters are shared across all forked children and lock-free
  15
  16 * counters are kept on separate cache lines to reduce contention under SMP
  17
  18 * may expose server statistics as a Rack Middleware endpoint
  19   (default: "/_raindrops")
  20
  21 * middleware displays the number of actively processing and writing
  22   clients from a single request regardless of which worker process
  23   it hits.
  24
  25 == Linux-only Extra Features!
  26
  27 * Middleware response includes extra stats for bound TCP and
  28   Unix domain sockets (configurable, it can include stats from
  29   other TCP or UNIX domain socket servers).
  30
  31 * TCP socket stats use efficient inet_diag facilities via netlink
  32   instead of parsing /proc/net/tcp to minimize overhead.
  33   This was fun to discover and write.
  34
  35 Users of older Linux kernels need to ensure that the the "inet_diag"
  36 and "tcp_diag" kernel modules are loaded as they do not autoload correctly
  37
  38 == Install
  39
  40 We recommend GCC 4+ (or compatible) to support the
  41 {atomic builtins}[http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html]
  42 (__sync_{add,sub}_and_fetch()).  For non-GCC 4+ users, we also support
  43 compilation with the
  44 {libatomic_ops}[http://www.hpl.hp.com/research/linux/atomic_ops/]
  45 package starting with Raindrops 0.4.0.
  46
  47 If you're using a packaged Ruby distribution, make sure you have a C
  48 compiler and the matching Ruby development libraries and headers.
  49
  50 If you use RubyGems:
  51
  52     gem install raindrops
  53
  54 Otherwise grab the latest tarball from:
  55
  56 http://raindrops.bogomips.org/files/
  57
  58 Unpack it, and run "ruby setup.rb"
  59
  60 == Usage (Rainbows!/Unicorn preload_app=false)
  61
  62 If you're using preload_app=false (the default) in your Rainbows!/Unicorn
  63 config file, you'll need to create the global Stats object before
  64 forking.
  65
  66         require 'raindrops'
  67         $stats ||= Raindrops::Middleware::Stats.new
  68
  69 In your Rack config.ru:
  70
  71         use Raindrops::Middleware, :stats => $stats
  72
  73 == Usage (Rainbows!/Unicorn preload_app=true)
  74
  75 If you're using preload_app=true in your Rainbows!/Unicorn
  76 config file, just add the middleware to your stack:
  77
  78 In your Rack config.ru:
  79
  80         use Raindrops::Middleware
  81
  82 == Usage (Linux-extras)
  83
  84 To get bound listener statistics under Linux, you need to specify the
  85 listener names for your server.  You can even include listen sockets for
  86 *other* servers on the same machine.  This can be handy for monitoring
  87 your nginx proxy as well.
  88
  89 In your Rack config.ru, just pass the :listeners argument as an array of
  90 strings (along with any other arguments).  You can specify any
  91 combination of TCP or Unix domain socket names:
  92
  93         use Raindrops::Middleware, :listeners => %w(0.0.0.0:80 /tmp/.sock)
  94
  95 See the tests/ and examples/ directory for more examples.
  96
  97 If you're running Unicorn 0.98.0 or later, you don't have to pass in
  98 the :listeners array, Raindrops will automatically detect the listeners
  99 used by Unicorn master process.
 100
 101 == Development
 102
 103 You can get the latest source via git from the following locations:
 104
 105   git://bogomips.org/raindrops.git
 106   git://repo.or.cz/raindrops.git (mirror)
 107
 108 You may browse the code from the web and download the latest snapshot
 109 tarballs here:
 110
 111 * http://bogomips.org/raindrops.git (cgit)
 112 * http://repo.or.cz/w/raindrops.git (gitweb)
 113
 114 Inline patches (from "git format-patch") to the mailing list are
 115 preferred because they allow code review and comments in the reply to
 116 the patch.
 117
 118 We will adhere to mostly the same conventions for patch submissions as
 119 git itself.  See the Documentation/SubmittingPatches document
 120 distributed with git on on patch submission guidelines to follow.  Just
 121 don't email the git mailing list or maintainer with raindrops patches.
 122
 123 raindrops is currently dual-licensed under the LGPLv2.1 and LGPLv3.  To
 124 allow for a transition to future versions of the LGPL, contributors are
 125 required to sign-off changes allowing allowing the project leader to
 126 relicense raindrops under newer versions of the LGPL (which should be
 127 similar in spirit to the existing LGPL).
 128
 129 == Contact
 130
 131 All feedback (bug reports, user/development discussion, patches, pull
 132 requests) go to the mailing list: mailto:raindrops@librelist.com
 133
 134 The mailing list is mirrored to Gmane, all information about the
 135 group is here:
 136
 137 http://gmane.org/info.php?group=gmane.comp.lang.ruby.raindrops.general
 138
 139 Mailing list archives in mbox format may be downloaded here:
 140
 141 http://raindrops.bogomips.org/archives/