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 unicorn, but
   5 should support any Rack HTTP server on platforms supporting POSIX shared
   6 memory.  It may also be used as a generic scoreboard for sharing atomic
   7 counters across multiple processes.
   8
   9 == Features
  10
  11 * counters are shared across all forked children and lock-free
  12
  13 * counters are kept on separate cache lines to reduce contention under SMP
  14
  15 * may expose server statistics as a Rack Middleware endpoint
  16   (default: "/_raindrops")
  17
  18 * middleware displays the number of actively processing and writing
  19   clients from a single request regardless of which worker process
  20   it hits.
  21
  22 == Linux-only Extra Features!
  23
  24 * Middleware response includes extra stats for bound TCP and
  25   Unix domain sockets (configurable, it can include stats from
  26   other TCP or UNIX domain socket servers).
  27
  28 * TCP socket stats use efficient inet_diag facilities via netlink
  29   instead of parsing /proc/net/tcp to minimize overhead.
  30   This was fun to discover and write.
  31
  32 * TCP_Info reporting may be used to check stat for every accepted client
  33   on TCP servers
  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 __sync builtins
  41 (__sync_{add,sub}_and_fetch()):
  42
  43         http://gcc.gnu.org/onlinedocs/gcc/_005f_005fsync-Builtins.html
  44
  45 For non-GCC 4+ users, we also support compilation with the libatomic_ops
  46 package starting with Raindrops 0.4.0:
  47
  48         https://github.com/ivmai/libatomic_ops
  49
  50 If you're using a packaged Ruby distribution, make sure you have a C
  51 compiler and the matching Ruby development libraries and headers.
  52
  53 If you use RubyGems:
  54
  55     gem install raindrops
  56
  57 Otherwise grab the latest tarball from:
  58
  59 http://raindrops.bogomips.org/files/
  60
  61 Unpack it, and run "ruby setup.rb"
  62
  63 == Usage
  64
  65 See Raindrops::Middleware and Raindrops::LastDataRecv documentation for
  66 use Rack servers.  The entire library is fully-documented and we are
  67 responsive on the mailing list (mailto:raindrops-public@bogomips.org) if
  68 you have any questions or comments.
  69
  70 == Development
  71
  72 You can get the latest source via git from the following locations:
  73
  74   git://bogomips.org/raindrops.git
  75   git://repo.or.cz/raindrops.git (mirror)
  76
  77 You may browse the code from the web and download the latest snapshot
  78 tarballs here:
  79
  80 * http://bogomips.org/raindrops.git
  81 * http://repo.or.cz/w/raindrops.git (gitweb)
  82
  83 Inline patches (from "git format-patch") to the mailing list are
  84 preferred because they allow code review and comments in the reply to
  85 the patch.
  86
  87 We will adhere to mostly the same conventions for patch submissions as
  88 git itself.  See the Documentation/SubmittingPatches document
  89 distributed with git on on patch submission guidelines to follow.  Just
  90 don't email the git mailing list or maintainer with raindrops patches.
  91
  92 raindrops is licensed under the LGPL-2.1+
  93
  94 == Contact
  95
  96 All feedback (bug reports, user/development discussion, patches, pull
  97 requests) go to the mailing list: mailto:raindrops-public@bogomips.org
  98
  99 Mailing list archives are available over HTTP and NNTP:
 100
 101 http://bogomips.org/raindrops-public/
 102 nntp://news.public-inbox.org/inbox.comp.lang.ruby.raindrops