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 == Install
  36
  37 We recommend GCC 4+ (or compatible) to support the
  38 {atomic builtins}[http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html]
  39 (__sync_{add,sub}_and_fetch()).  For non-GCC 4+ users, we also support
  40 compilation with the
  41 {libatomic_ops}[http://www.hpl.hp.com/research/linux/atomic_ops/]
  42 package starting with Raindrops 0.4.0.
  43
  44 If you're using a packaged Ruby distribution, make sure you have a C
  45 compiler and the matching Ruby development libraries and headers.
  46
  47 If you use RubyGems:
  48
  49     gem install raindrops
  50
  51 Otherwise grab the latest tarball from:
  52
  53 http://raindrops.bogomips.org/files/
  54
  55 Unpack it, and run "ruby setup.rb"
  56
  57 == Usage (Rainbows!/Unicorn preload_app=false)
  58
  59 If you're using preload_app=false (the default) in your Rainbows!/Unicorn
  60 config file, you'll need to create the global Stats object before
  61 forking.
  62
  63         require 'raindrops'
  64         $stats ||= Raindrops::Middleware::Stats.new
  65
  66 In your Rack config.ru:
  67
  68         use Raindrops::Middleware, :stats => $stats
  69
  70 == Usage (Rainbows!/Unicorn preload_app=true)
  71
  72 If you're using preload_app=true in your Rainbows!/Unicorn
  73 config file, just add the middleware to your stack:
  74
  75 In your Rack config.ru:
  76
  77         use Raindrops::Middleware
  78
  79 == Usage (Linux-extras)
  80
  81 To get bound listener statistics under Linux, you need to specify the
  82 listener names for your server.  You can even include listen sockets for
  83 *other* servers on the same machine.  This can be handy for monitoring
  84 your nginx proxy as well.
  85
  86 In your Rack config.ru, just pass the :listeners argument as an array of
  87 strings (along with any other arguments).  You can specify any
  88 combination of TCP or Unix domain socket names:
  89
  90         use Raindrops::Middleware, :listeners => %w(0.0.0.0:80 /tmp/.sock)
  91
  92 See the tests/ and examples/ directory for more examples.
  93
  94 If you're running Unicorn 0.98.0 or later, you don't have to pass in
  95 the :listeners array, Raindrops will automatically detect the listeners
  96 used by Unicorn master process.
  97
  98 == Development
  99
 100 You can get the latest source via git from the following locations:
 101
 102   git://bogomips.org/raindrops.git
 103   git://repo.or.cz/raindrops.git (mirror)
 104
 105 You may browse the code from the web and download the latest snapshot
 106 tarballs here:
 107
 108 * http://bogomips.org/raindrops.git (cgit)
 109 * http://repo.or.cz/w/raindrops.git (gitweb)
 110
 111 Inline patches (from "git format-patch") to the mailing list are
 112 preferred because they allow code review and comments in the reply to
 113 the patch.
 114
 115 We will adhere to mostly the same conventions for patch submissions as
 116 git itself.  See the Documentation/SubmittingPatches document
 117 distributed with git on on patch submission guidelines to follow.  Just
 118 don't email the git mailing list or maintainer with raindrops patches.
 119
 120 raindrops is currently dual-licensed under the LGPLv2.1 and LGPLv3.  To
 121 allow for a transition to future versions of the LGPL, contributors are
 122 required to sign-off changes allowing allowing the project leader to
 123 relicense raindrops under newer versions of the LGPL (which should be
 124 similar in spirit to the existing LGPL).
 125
 126 == Contact
 127
 128 All feedback (bug reports, user/development discussion, patches, pull
 129 requests) go to the mailing list: mailto:raindrops@librelist.com
 130
 131 The mailing list is mirrored to Gmane, all information about the
 132 group is here:
 133
 134 http://gmane.org/info.php?group=gmane.comp.lang.ruby.raindrops.general
 135
 136 Mailing list archives in mbox format may be downloaded here:
 137
 138 http://raindrops.bogomips.org/archives/