initial

1 files changed, 117 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..4e5c9db
--- /dev/null
+++ b/README
@@ -0,0 +1,117 @@
+= raindrops - real-time stats for preforking Rack servers
+
+Raindrops is a real time stats package to show statistics for Rack HTTP
+servers.  It is designed for preforking servers such as Rainbows! and
+Unicorn, but should support any Rack HTTP server under Ruby 1.9, 1.8 and
+possibly Rubinius (untested) on platforms supporting POSIX shared memory
+and compiled with GCC (for atomic builtins).
+
+Raindrops includes a Struct-like Raindrops::Struct class that may be used
+standalone to create atomic counters shared across any number of forked
+processes under SMP.
+
+== Features
+
+* counters are shared across all forked children and lock-free
+
+* counters are kept on separate cache lines to reduce contention under SMP
+
+* may expose server statistics as a Rack Middleware endpoint
+  (default: "/_raindrops")
+
+* middleware displays the number of actively processing and writing
+  clients from a single request regardless of which worker process
+  it hits.
+
+== Linux-only Extra Features!
+
+* Middleware response includes extra stats for bound TCP and
+  Unix domain sockets (configurable, it can include stats from
+  other TCP or UNIX domain socket servers).
+
+* TCP socket stats use efficient inet_diag facilities via netlink
+  instead of parsing /proc/net/tcp to minimize overhead.
+  This was fun to discover and write.
+
+== Install
+
+raindrops requires GCC 4.x (or compatible) or later to support the
+atomic builtins (__sync_{add,sub}_and_fetch()).  Atomic operations on
+other compilers may be supported if there is demand.
+
+If you're using a packaged Ruby distribution, make sure you have a C
+compiler and the matching Ruby development libraries and headers.
+
+If you use RubyGems:
+
+    gem install raindrops
+
+Otherwise grab the latest tarball from:
+
+http://raindrops.bogomips.org/files/
+
+Unpack it, and run "ruby setup.rb"
+
+== Usage (Rainbows!/Unicorn preload_app=false)
+
+If you're using preload_app=false (the default) in your Rainbows!/Unicorn
+config file, you'll need to create the global Stats object before
+forking.
+
+        require 'raindrops'
+        $stats ||= Raindrops::Middleware::Stats.new
+
+In your Rack config.ru:
+
+        use Raindrops::Middleware, :stats => $stats
+
+== Usage (Rainbows!/Unicorn preload_app=true)
+
+If you're using preload_app=true in your Rainbows!/Unicorn
+config file, just add the middleware to your stack:
+
+In your Rack config.ru:
+
+        use Raindrops::Middleware
+
+== Usage (Linux-extras)
+
+To get bound listener statistics under Linux, you need to specify the
+listener names for your server.  You can even include listen sockets for
+*other* servers on the same machine.  This can be handy for monitoring
+your nginx proxy as well.
+
+In your Rack config.ru, just pass the :listeners argument as an array of
+strings (along with any other arguments).  You can specify any
+combination of TCP or Unix domain socket names:
+
+        use Raindrops::Middleware, :listeners => %w(0.0.0.0:80 /tmp/.sock)
+
+See the tests/ and examples/ directory for more examples
+
+== Development
+
+You can get the latest source via git from the following locations:
+
+  git://git.bogomips.org/raindrops.git
+  git://repo.or.cz/raindrops.git (mirror)
+
+You may browse the code from the web and download the latest snapshot
+tarballs here:
+
+* http://git.bogomips.org/cgit/raindrops.git (cgit)
+* http://repo.or.cz/w/raindrops.git (gitweb)
+
+Inline patches (from "git format-patch") to the mailing list are
+preferred because they allow code review and comments in the reply to
+the patch.
+
+We will adhere to mostly the same conventions for patch submissions as
+git itself.  See the Documentation/SubmittingPatches document
+distributed with git on on patch submission guidelines to follow.  Just
+don't email the git mailing list or maintainer with raindrops patches.
+
+== Contact
+
+All feedback (bug reports, user/development discussion, patches, pull
+requests) go to the mailing list: mailto:raindrops@librelist.com