raindrops 0.4.1 → 0.5.0

data/lib/raindrops.rb

@@ -1,9 +1,20 @@
 # -*- encoding: binary -*-
+#
+# Each Raindrops object is a container that holds several counters.
+# It is internally a page-aligned, shared memory area that allows
+# atomic increments, decrements, assignments and reads without any
+# locking.
+#
+#   rd = Raindrops.new 4
+#   rd.incr(0, 1)   -> 1
+#   rd.to_ary       -> [ 1, 0, 0, 0 ]
+#
+# Unlike many classes in this package, the core Raindrops class is
+# intended to be portable to all reasonably modern *nix systems
+# supporting mmap().  Please let us know if you have portability
+# issues, patches or pull requests at mailto:raindrops@librelist.com
 class Raindrops
 
-  # Raindrops is currently at version 0.4.1
-  VERSION = '0.4.1'
-
   # Used to represent the number of +active+ and +queued+ sockets for
   # a single listen socket across all threads and processes on a
   # machine.
@@ -18,7 +29,7 @@ class Raindrops
   # +queued+ connections is the number of un-accept()-ed sockets in the
   # queue of a given listen socket.
   #
-  # These stats are currently only available under Linux
+  # These stats are currently only available under \Linux
   class ListenStats < Struct.new(:active, :queued)
 
     # the sum of +active+ and +queued+ sockets
@@ -27,9 +38,11 @@ class Raindrops
     end
   end
 
-  # TODO: pure Ruby version for single processes
-  require 'raindrops_ext'
-
+  autoload :Linux, 'raindrops/linux'
   autoload :Struct, 'raindrops/struct'
   autoload :Middleware, 'raindrops/middleware'
+  autoload :Aggregate, 'raindrops/aggregate'
+  autoload :LastDataRecv, 'raindrops/last_data_recv'
+  autoload :Watcher, 'raindrops/watcher'
 end
+require 'raindrops_ext'

data/lib/raindrops/aggregate.rb

@@ -0,0 +1,8 @@
+# -*- encoding: binary -*-
+#
+# raindrops may use the {aggregate}[http://github.com/josephruscio/aggregate]
+# RubyGem to aggregate statistics from TCP_Info lookups.
+module Raindrops::Aggregate
+  autoload :PMQ, "raindrops/aggregate/pmq"
+  autoload :LastDataRecv, "raindrops/aggregate/last_data_recv"
+end

data/lib/raindrops/aggregate/last_data_recv.rb

@@ -0,0 +1,86 @@
+# -*- encoding: binary -*-
+require "socket"
+#
+#
+# This module is used to extend TCPServer and Kgio::TCPServer objects
+# and aggregate +last_data_recv+ times for all accepted clients. It
+# is designed to be used with Raindrops::LastDataRecv Rack application
+# but can be easily changed to work with other stats collection devices.
+#
+# Methods wrapped include:
+# - TCPServer#accept
+# - TCPServer#accept_nonblock
+# - Kgio::TCPServer#kgio_accept
+# - Kgio::TCPServer#kgio_tryaccept
+module Raindrops::Aggregate::LastDataRecv
+  # :stopdoc:
+  TCP_Info = Raindrops::TCP_Info
+  # :startdoc:
+
+  # The integer value of +last_data_recv+ is sent to this object.
+  # This is usually a duck type compatible with the \Aggregate class,
+  # but can be *anything* that accepts the *<<* method.
+  attr_accessor :raindrops_aggregate
+
+  @@default_aggregate = nil
+
+  # By default, this is a Raindrops::Aggregate::PMQ object
+  # It may be anything that responds to *<<*
+  def self.default_aggregate
+    @@default_aggregate ||= Raindrops::Aggregate::PMQ.new
+  end
+
+  # Assign any object that responds to *<<*
+  def self.default_aggregate=(agg)
+    @@default_aggregate = agg
+  end
+
+  # automatically extends any TCPServer objects used by Unicorn
+  def self.cornify!
+    Unicorn::HttpServer::LISTENERS.each do |sock|
+      sock.extend(self) if TCPServer === sock
+    end
+  end
+
+  # each extended object needs to have TCP_DEFER_ACCEPT enabled
+  # for accuracy.
+  def self.extended(obj)
+    obj.raindrops_aggregate = default_aggregate
+    obj.setsockopt Socket::SOL_TCP, tcp_defer_accept = 9, seconds = 60
+  end
+
+  # :stopdoc:
+
+  def kgio_tryaccept(*args)
+    count! super
+  end
+
+  def kgio_accept(*args)
+    count! super
+  end
+
+  def accept
+    count! super
+  end
+
+  def accept_nonblock
+    count! super
+  end
+
+  # :startdoc:
+
+  # The +last_data_recv+ member of Raindrops::TCP_Info can be used to
+  # infer the time a client spent in the listen queue before it was
+  # accepted.
+  #
+  # We require TCP_DEFER_ACCEPT on the listen socket for
+  # +last_data_recv+ to be accurate
+  def count!(io)
+    if io
+      x = TCP_Info.new(io)
+      @raindrops_aggregate << x.last_data_recv
+    end
+    io
+  end
+end
+

data/lib/raindrops/aggregate/pmq.rb

@@ -0,0 +1,239 @@
+# -*- encoding: binary -*-
+require "tempfile"
+require "aggregate"
+require "posix_mq"
+require "fcntl"
+require "io/extra"
+require "thread"
+
+# \Aggregate + POSIX message queues support for Ruby 1.9 and \Linux
+#
+# This class is duck-type compatible with \Aggregate and allows us to
+# aggregate and share statistics from multiple processes/threads aided
+# POSIX message queues.  This is designed to be used with the
+# Raindrops::LastDataRecv Rack application, but can be used independently
+# on compatible Runtimes.
+#
+# Unlike the core of raindrops, this is only supported on Ruby 1.9 and
+# Linux 2.6.  Using this class requires the following additional RubyGems
+# or libraries:
+#
+# * aggregate (tested with 0.2.2)
+# * io-extra  (tested with 1.2.3)
+# * posix_mq  (tested with 1.0.0)
+#
+# == Design
+#
+# There is one master thread which aggregates statistics.  Individual
+# worker processes or threads will write to a shared POSIX message
+# queue (default: "/raindrops") that the master reads from.  At a
+# predefined interval, the master thread will write out to a shared,
+# anonymous temporary file that workers may read from
+#
+# Setting +:worker_interval+ and +:master_interval+ to +1+ will result
+# in perfect accuracy but at the cost of a high synchronization
+# overhead.  Larger intervals mean less frequent messaging for higher
+# performance but lower accuracy.
+class Raindrops::Aggregate::PMQ
+
+  # :stopdoc:
+  # These constants are for Linux.  This is designed for aggregating
+  # TCP_INFO.
+  RDLOCK = [ Fcntl::F_RDLCK ].pack("s @256")
+  WRLOCK = [ Fcntl::F_WRLCK ].pack("s @256")
+  UNLOCK = [ Fcntl::F_UNLCK ].pack("s @256")
+  # :startdoc:
+
+  # returns the number of dropped messages sent to a POSIX message
+  # queue if non-blocking operation was desired with :lossy
+  attr_reader :nr_dropped
+
+  #
+  # Creates a new Raindrops::Aggregate::PMQ object
+  #
+  #   Raindrops::Aggregate::PMQ.new(options = {})  -> aggregate
+  #
+  # +options+ is a hash that accepts the following keys:
+  #
+  # * :queue - name of the POSIX message queue (default: "/raindrops")
+  # * :worker_interval - interval to send to the master (default: 10)
+  # * :master_interval - interval to for the master to write out (default: 5)
+  # * :lossy - workers drop packets if master cannot keep up (default: false)
+  # * :aggregate - \Aggregate object (default: \Aggregate.new)
+  # * :mq_umask - umask for creatingthe POSIX message queue (default: 0666)
+  #
+  def initialize(params = {})
+    opts = {
+      :queue => ENV["RAINDROPS_MQUEUE"] || "/raindrops",
+      :worker_interval => 10,
+      :master_interval => 5,
+      :lossy => false,
+      :mq_attr => nil,
+      :mq_umask => 0666,
+      :aggregate => Aggregate.new,
+    }.merge! params
+    @master_interval = opts[:master_interval]
+    @worker_interval = opts[:worker_interval]
+    @aggregate = opts[:aggregate]
+    @worker_queue = @worker_interval ? [] : nil
+    @mutex = Mutex.new
+
+    @mq_name = opts[:queue]
+    mq = POSIX_MQ.new @mq_name, :w, opts[:mq_umask], opts[:mq_attr]
+    Tempfile.open("raindrops_pmq") do |t|
+      @wr = File.open(t.path, "wb")
+      @rd = File.open(t.path, "rb")
+    end
+    @cached_aggregate = @aggregate
+    flush_master
+    @mq_send = if opts[:lossy]
+      @nr_dropped = 0
+      mq.nonblock = true
+      mq.method :trysend
+    else
+      mq.method :send
+    end
+  end
+
+  # adds a sample to the underlying \Aggregate object
+  def << val
+    if q = @worker_queue
+      q << val
+      if q.size >= @worker_interval
+        mq_send(q) or @nr_dropped += 1
+        q.clear
+      end
+    else
+      mq_send(val) or @nr_dropped += 1
+    end
+  end
+
+  def mq_send(val) # :nodoc:
+    @cached_aggregate = nil
+    @mq_send.call Marshal.dump(val)
+  end
+
+  #
+  # Starts running a master loop, usually in a dedicated thread or process:
+  #
+  #   Thread.new { agg.master_loop }
+  #
+  # Any worker can call +agg.stop_master_loop+ to stop the master loop
+  # (possibly causing the thread or process to exit)
+  def master_loop
+    buf = ""
+    a = @aggregate
+    nr = 0
+    mq = POSIX_MQ.new @mq_name, :r # this one is always blocking
+    begin
+      if (nr -= 1) < 0
+        nr = @master_interval
+        flush_master
+      end
+      mq.shift(buf)
+      data = begin
+        Marshal.load(buf) or return
+      rescue ArgumentError, TypeError
+        next
+      end
+      Array === data ? data.each { |x| a << x } : a << data
+    rescue Errno::EINTR
+    rescue => e
+      warn "Unhandled exception in #{__FILE__}:#{__LINE__}: #{e}"
+      break
+    end while true
+    ensure
+      flush_master
+  end
+
+  # Loads the last shared \Aggregate from the master thread/process
+  def aggregate
+    @cached_aggregate ||= begin
+      flush
+      Marshal.load(synchronize(@rd, RDLOCK) do |rd|
+        IO.pread rd.fileno, rd.stat.size, 0
+      end)
+    end
+  end
+
+  # Flushes the currently aggregate statistics to a temporary file.
+  # There is no need to call this explicitly as +:worker_interval+ defines
+  # how frequently your data will be flushed for workers to read.
+  def flush_master
+    dump = Marshal.dump @aggregate
+    synchronize(@wr, WRLOCK) do |wr|
+      wr.truncate 0
+      IO.pwrite wr.fileno, dump, 0
+    end
+  end
+
+  # stops the currently running master loop, may be called from any
+  # worker thread or process
+  def stop_master_loop
+    sleep 0.1 until mq_send(false)
+    rescue Errno::EINTR
+      retry
+  end
+
+  def lock! io, type # :nodoc:
+    io.fcntl Fcntl::F_SETLKW, type
+    rescue Errno::EINTR
+      retry
+  end
+
+  # we use both a mutex for thread-safety and fcntl lock for process-safety
+  def synchronize io, type # :nodoc:
+    @mutex.synchronize do
+      begin
+        lock! io, type
+        yield io
+      ensure
+        lock! io, UNLOCK
+      end
+    end
+  end
+
+  # flushes the local queue of the worker process, sending all pending
+  # data to the master.  There is no need to call this explicitly as
+  # +:worker_interval+ defines how frequently your queue will be flushed
+  def flush
+    if q = @local_queue && ! q.empty?
+      mq_send q
+      q.clear
+    end
+    nil
+  end
+
+  # proxy for \Aggregate#count
+  def count; aggregate.count; end
+
+  # proxy for \Aggregate#max
+  def max; aggregate.max; end
+
+  # proxy for \Aggregate#min
+  def min; aggregate.min; end
+
+  # proxy for \Aggregate#sum
+  def sum; aggregate.sum; end
+
+  # proxy for \Aggregate#mean
+  def mean; aggregate.mean; end
+
+  # proxy for \Aggregate#std_dev
+  def std_dev; aggregate.std_dev; end
+
+  # proxy for \Aggregate#outliers_low
+  def outliers_low; aggregate.outliers_low; end
+
+  # proxy for \Aggregate#outliers_high
+  def outliers_high; aggregate.outliers_high; end
+
+  # proxy for \Aggregate#to_s
+  def to_s(*args); aggregate.to_s *args; end
+
+  # proxy for \Aggregate#each
+  def each; aggregate.each { |*args| yield *args }; end
+
+  # proxy for \Aggregate#each_nonzero
+  def each_nonzero; aggregate.each_nonzero { |*args| yield *args }; end
+end

data/lib/raindrops/last_data_recv.rb

@@ -0,0 +1,100 @@
+# -*- encoding: binary -*-
+require "raindrops"
+
+# This is highly experimental!
+#
+# A self-contained Rack application for aggregating in the
+# +tcpi_last_data_recv+ field in +struct tcp_info+ if
+# /usr/include/linux/tcp.h.  This is only useful for \Linux 2.6 and later.
+# This primarily supports Unicorn and derived servers, but may also be
+# used with any Ruby web server using the core TCPServer class in Ruby.
+#
+# Hitting the Rack endpoint configured for this application will return
+# a an ASCII histogram response body with the following headers:
+#
+# - X-Count   - number of requests received
+#
+# The following headers are only present if X-Count is greater than one.
+#
+# - X-Min     - lowest last_data_recv time recorded (in milliseconds)
+# - X-Max     - highest last_data_recv time recorded (in milliseconds)
+# - X-Mean    - mean last_data_recv time recorded (rounded, in milliseconds)
+# - X-Std-Dev - standard deviation of last_data_recv times
+# - X-Outliers-Low - number of low outliers (hopefully many!)
+# - X-Outliers-High - number of high outliers (hopefully zero!)
+#
+# == To use with Unicorn and derived servers (preload_app=false):
+#
+# Put the following in our Unicorn config file (not config.ru):
+#
+#   require "raindrops/last_data_recv"
+#
+# Then follow the instructions below for config.ru:
+#
+# == To use with any Rack server using TCPServer
+#
+# Setup a route for Raindrops::LastDataRecv in your Rackup config file
+# (typically config.ru):
+#
+#   require "raindrops"
+#   map "/raindrops/last_data_recv" do
+#     run Raindrops::LastDataRecv.new
+#   end
+#   map "/" do
+#     use SomeMiddleware
+#     use MoreMiddleware
+#     # ...
+#     run YourAppHere.new
+#   end
+#
+# == To use with any other Ruby web server that uses TCPServer
+#
+# Put the following in any piece of Ruby code loaded after the server has
+# bound its TCP listeners:
+#
+#   ObjectSpace.each_object(TCPServer) do |s|
+#     s.extend Raindrops::Aggregate::LastDataRecv
+#   end
+#
+#   Thread.new do
+#     Raindrops::Aggregate::LastDataRecv.default_aggregate.master_loop
+#   end
+#
+# Then follow the above instructions for config.ru
+#
+class Raindrops::LastDataRecv
+  # :stopdoc:
+
+  # trigger autoloads
+  if defined?(Unicorn)
+    agg = Raindrops::Aggregate::LastDataRecv.default_aggregate
+    AGGREGATE_THREAD = Thread.new { agg.master_loop }
+  end
+  # :startdoc
+
+  def initialize(opts = {})
+    Raindrops::Aggregate::LastDataRecv.cornify! if defined?(Unicorn)
+    @aggregate =
+      opts[:aggregate] || Raindrops::Aggregate::LastDataRecv.default_aggregate
+  end
+
+  def call(_)
+    a = @aggregate
+    count = a.count
+    headers = {
+      "Content-Type" => "text/plain",
+      "X-Count" => count.to_s,
+    }
+    if count > 1
+      headers["X-Min"] = a.min.to_s
+      headers["X-Max"] = a.max.to_s
+      headers["X-Mean"] = a.mean.round.to_s
+      headers["X-Std-Dev"] = a.std_dev.round.to_s
+      headers["X-Outliers-Low"] = a.outliers_low.to_s
+      headers["X-Outliers-High"] = a.outliers_high.to_s
+    end
+    body = a.to_s
+    headers["Content-Length"] = body.size.to_s
+    [ 200, headers, [ body ] ]
+  end
+end