README

   1 = raindrops - real-time stats for preforking Rack servers
   2
   3 Raindrops is a real-time stats toolkit 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.  It may also be
   7 used as a generic scoreboard for sharing atomic counters across multiple
   8 processes.
   9
  10 == Features
  11
  12 * counters are shared across all forked children and lock-free
  13
  14 * counters are kept on separate cache lines to reduce contention under SMP
  15
  16 * may expose server statistics as a Rack Middleware endpoint
  17   (default: "/_raindrops")
  18
  19 * middleware displays the number of actively processing and writing
  20   clients from a single request regardless of which worker process
  21   it hits.
  22
  23 == Linux-only Extra Features!
  24
  25 * Middleware response includes extra stats for bound TCP and
  26   Unix domain sockets (configurable, it can include stats from
  27   other TCP or UNIX domain socket servers).
  28
  29 * TCP socket stats use efficient inet_diag facilities via netlink
  30   instead of parsing /proc/net/tcp to minimize overhead.
  31   This was fun to discover and write.
  32
  33 * TCP_Info reporting may be used to check stat for every accepted client
  34   on TCP servers
  35
  36 Users of older Linux kernels need to ensure that the the "inet_diag"
  37 and "tcp_diag" kernel modules are loaded as they do not autoload correctly
  38
  39 == Install
  40
  41 We recommend GCC 4+ (or compatible) to support the
  42 {atomic builtins}[http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html]
  43 (__sync_{add,sub}_and_fetch()).  For non-GCC 4+ users, we also support
  44 compilation with the
  45 {libatomic_ops}[http://www.hpl.hp.com/research/linux/atomic_ops/]
  46 package starting with Raindrops 0.4.0.
  47
  48 If you're using a packaged Ruby distribution, make sure you have a C
  49 compiler and the matching Ruby development libraries and headers.
  50
  51 If you use RubyGems:
  52
  53     gem install raindrops
  54
  55 Otherwise grab the latest tarball from:
  56
  57 http://raindrops.bogomips.org/files/
  58
  59 Unpack it, and run "ruby setup.rb"
  60
  61 == Usage
  62
  63 See Raindrops::Middleware and Raindrops::LastDataRecv documentation for
  64 use Rack servers.  The entire library is fully-documented and we are
  65 responsive on the mailing list (mailto:raindrops@librelist.org) if you
  66 have any questions or comments.
  67
  68 == Development
  69
  70 You can get the latest source via git from the following locations:
  71
  72   git://bogomips.org/raindrops.git
  73   git://repo.or.cz/raindrops.git (mirror)
  74
  75 You may browse the code from the web and download the latest snapshot
  76 tarballs here:
  77
  78 * http://bogomips.org/raindrops.git (cgit)
  79 * http://repo.or.cz/w/raindrops.git (gitweb)
  80
  81 Inline patches (from "git format-patch") to the mailing list are
  82 preferred because they allow code review and comments in the reply to
  83 the patch.
  84
  85 We will adhere to mostly the same conventions for patch submissions as
  86 git itself.  See the Documentation/SubmittingPatches document
  87 distributed with git on on patch submission guidelines to follow.  Just
  88 don't email the git mailing list or maintainer with raindrops patches.
  89
  90 raindrops is currently dual-licensed under the LGPLv2.1 and LGPLv3.  To
  91 allow for a transition to future versions of the LGPL, contributors are
  92 required to sign-off changes allowing allowing the project leader to
  93 relicense raindrops under newer versions of the LGPL (which should be
  94 similar in spirit to the existing LGPL).
  95
  96 == Contact
  97
  98 All feedback (bug reports, user/development discussion, patches, pull
  99 requests) go to the mailing list: mailto:raindrops@librelist.org
 100
 101 The mailing list is mirrored to Gmane, all information about the
 102 group is here:
 103
 104 http://gmane.org/info.php?group=gmane.comp.lang.ruby.raindrops.general
 105
 106 Mailing list archives in mbox format may be downloaded here:
 107
 108 http://raindrops.bogomips.org/archives/