raindrops.git  about / heads / tags
real-time stats for preforking Rack servers
$ git log --pretty=format:'%h %s (%cs)%d' v0.3.0 --
eed4332 raindrops v0.3.0 - LGPL v2.1 and v3.0 (2010-07-10)
	(tag: v0.3.0)
4e42082 doc: add examples directory to website (2010-07-10)
87dc142 LICENSE: dual license under LGPLv2.1 and LGPLv3 (2010-07-10)
3f7f59f examples/linux-tcp-listener-stats: warn on possibly invalid addresses (2010-07-01)
bb24816 linux_inet_diag: rename "addrs" => "query_addr" (2010-07-01)
590b3d9 examples/linux-tcp-listener-stats: fix usage string (2010-06-29)
06c5595 raindrops 0.2.0 - raining penguins! (2010-05-04)
	(tag: v0.2.0)
ccf41c1 examples: add sample standalone Rack application (2010-05-04)
0a5a13e README: add note about Unicorn 0.98.0 listener_names (2010-05-04)
ad1a354 cleanup a few typos (2010-05-04)
...

$ git cat-file blob v0.3.0:README
= 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.

If you're running Unicorn 0.98.0 or later, you don't have to pass in
the :listeners array, Raindrops will automatically detect the listeners
used by Unicorn master process.

== 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

The mailing list is mirrored to Gmane, all information about the
group is here:

http://gmane.org/info.php?group=gmane.comp.lang.ruby.raindrops.general

Mailing list archives in mbox format may be downloaded here:

http://raindrops.bogomips.org/archives/

# heads (aka `branches'):
$ git for-each-ref --sort=-creatordate refs/heads \
	--format='%(HEAD) %(refname:short) %(subject) (%(creatordate:short))'
* master       linux_inet_diag: avoid errors for users compiling w/o assertions (2024-03-25)
  aggregate-pmq aggregate/pmq: avoid File#stat allocation (2017-03-18)
  freebsd      define Raindrops::TCP hash for TCP states (2017-03-17)
  gc-next      linux_inet_diag: improve compatibility with newer GCs (2013-06-16)

# tags:
$ git for-each-ref --sort=-creatordate refs/tags \
	--format='%(refname:short) %(subject) (%(creatordate:short))'
v0.20.1      raindrops 0.20.1 (2023-02-25) tar.gz
v0.20.0      raindrops 0.20.0 (2021-12-06) tar.gz
v0.19.2      raindrops 0.19.2 (2021-05-25) tar.gz
v0.19.1      raindrops 0.19.1 (2020-01-08) tar.gz
v0.19.0      raindrops 0.19.0 - Rack 2.x middleware compatibility (2017-08-09) tar.gz
v0.18.0      raindrops 0.18.0 (2017-03-23) tar.gz
v0.17.0      raindrops 0.17.0 - rack 2.x updates (2016-07-31) tar.gz
v0.16.0      raindrops 0.16.0 - minor fixes and workarounds (2016-02-29) tar.gz
v0.15.0      raindrops 0.15.0 - non-glibc compat fix on Linux (2015-07-22) tar.gz
v0.14.0      raindrops 0.14.0 - misc doc updates (2015-06-25) tar.gz
...

# associated public inboxes:
# (number on the left is used for dev purposes)
            https://yhbt.net/raindrops-public

git clone https://yhbt.net/raindrops.git