gemspec: support rack 3.x
[raindrops.git] / README
blobeec2c86b529d209f12a2ec6094c119a2b491cffc
1 = raindrops - real-time stats for preforking Rack servers
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.
9 == Features
11 * counters are shared across all forked children and lock-free
13 * counters are kept on separate cache lines to reduce contention under SMP
15 * may expose server statistics as a Rack Middleware endpoint
16   (default: "/_raindrops")
18 * middleware displays the number of actively processing and writing
19   clients from a single request regardless of which worker process
20   it hits.
22 == Linux-only Extra Features!
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).
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.
32 * TCP_Info reporting may be used to check stat for every accepted client
33   on TCP servers
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
38 == Install
40 We recommend GCC 4+ (or compatible) to support the __sync builtins
41 (__sync_{add,sub}_and_fetch()):
43 https://gcc.gnu.org/onlinedocs/gcc/_005f_005fsync-Builtins.html
45 For non-GCC 4+ users, we also support compilation with the libatomic_ops
46 package starting with Raindrops 0.4.0:
48 https://github.com/ivmai/libatomic_ops
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.
53 If you use RubyGems:
55     gem install raindrops
57 == Usage
59 See Raindrops::Middleware and Raindrops::LastDataRecv documentation for
60 use Rack servers.  The entire library is fully-documented and we are
61 responsive on the publicly archived mailbox
62 (mailto:raindrops-public@yhbt.net) if you have any questions or comments.
64 == Development
66 You can get the latest source via git from the following locations:
68   https://yhbt.net/raindrops.git
69   http://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/raindrops.git
70   http://repo.or.cz/w/raindrops.git (gitweb mirror)
72 Snapshots and tarballs are available.
74 Inline patches (from "git format-patch") to the mailbox are
75 preferred because they allow code review and comments in the reply to
76 the patch.
78 We will adhere to mostly the same conventions for patch submissions as
79 git itself.  See the Documentation/SubmittingPatches document
80 distributed with git on on patch submission guidelines to follow.  Just
81 don't email the git mailing list or maintainer with raindrops patches.
83 raindrops is licensed under the LGPL-2.1+
85 == Contact
87 All feedback (bug reports, user/development discussion, patches, pull
88 requests) go to the publicly archived mailbox:
89 mailto:raindrops-public@yhbt.net
91 Mail archives are available over HTTP(S), IMAP(S) and NNTP(S):
93 * https://yhbt.net/raindrops-public/
94 * http://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/raindrops-public/
95 * imaps://yhbt.net/inbox.comp.lang.ruby.raindrops.0
96 * imap://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/inbox.comp.lang.ruby.raindrops.0
97 * nntps://news.public-inbox.org/inbox.comp.lang.ruby.raindrops
98 * nntp://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/inbox.comp.lang.ruby.raindrops
100 Since archives are public, scrub sensitive information and
101 use anonymity tools such as Tor or Mixmaster if you deem necessary.