statsd-ruby 1.1.1 → 1.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0edd467226454eea7a63a7ed08e3468ac48a2d7438fdf8d291ab266a781c128b
+  data.tar.gz: 82f88de7bf7738e974a8d9f2d70f57f039d31d7f69f9b98c359b7d5c7970f93c
+SHA512:
+  metadata.gz: 3520cc824d180d7304fa883fefa945d3f785d560f313c328fed8f28e4d799728c6ab61cd6b9a855d8023f644f2d328f7f6626e0af7770d8e83d99b2bb0e7a2f8
+  data.tar.gz: f0bc2ade747bee51cca11128a6d6ce21491b13354f519f582f90c94cd09ce1ee26372b52945c8d369dfc5160194cfd967644254350b0dd1567ff28cd64de8206

data/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: Ruby
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        os:
+          - ubuntu
+          - macos
+        ruby:
+          - 2.4
+          - 2.5
+          - 2.6
+          # TODO: - 2.7
+          # TODO: jruby, rbx
+
+    runs-on: ${{ matrix.os }}-latest
+
+    steps:
+    - uses: actions/checkout@v1
+
+    - name: Set up Ruby
+      uses: actions/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        architecture: x64
+
+    - name: Build and test with Rake
+      run: |
+        gem install bundler
+        bundle install
+        bundle exec rake

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2011 Rein Henrichs
+Copyright (c) 2011, 2012, 2013 Rein Henrichs
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -1,17 +1,20 @@
-= statsd-ruby {<img src="https://secure.travis-ci.org/reinh/statsd.png" />}[http://travis-ci.org/reinh/statsd]
+= statsd-ruby Travis: {<img src="https://secure.travis-ci.org/reinh/statsd.svg" />}[http://travis-ci.org/reinh/statsd] CI: {<img src="https://github.com/reinh/statsd/workflows/Ruby/badge.svg" />}[https://github.com/reinh/statsd/actions?query=workflow%3ARuby]
 
 A Ruby client for {StatsD}[https://github.com/etsy/statsd]
 
 = Installing
 
 Bundler:
-  gem "statsd-ruby", :require => "statsd"
+  gem "statsd-ruby"
 
 = Basic Usage
 
   # Set up a global Statsd client for a server on localhost:9125
   $statsd = Statsd.new 'localhost', 9125
 
+  # Set up a global Statsd client for a server on IPv6 port 9125
+  $statsd = Statsd.new '::1', 9125
+
   # Send some stats
   $statsd.increment 'garets'
   $statsd.timing 'glork', 320
@@ -28,14 +31,16 @@ Bundler:
 
 Run the specs with <tt>rake spec</tt>
 
-Run the specs and include live integration specs with <tt>LIVE=true rake spec</tt>. Note: This will test over a real UDP socket.
-
 = Performance
 
-* A short note about DNS: If you use a dns name for the host option, then you will want to use a local caching dns service for optimial performance (e.g. nscd).
+* A short note about DNS: If you use a dns name for the host option, then you will want to use a local caching dns service for optimal performance (e.g. nscd).
+
+= Extensions / Libraries / Extra Docs
+
+* See the wiki[https://github.com/reinh/statsd/wiki]
 
 == Contributing to statsd
- 
+
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
 * Fork the project
@@ -47,15 +52,35 @@ Run the specs and include live integration specs with <tt>LIVE=true rake spec</t
 == Contributors
 
 * Rein Henrichs
-* Ray Krueger
+* Alex Williams
+* Andrew Meyer
+* Chris Gaffney
+* Cody Cutrer
+* Corey Donohoe
+* Dotan Nahum
+* Erez Rabih
+* Eric Chapweske
+* Gabriel Burt
+* Hannes Georg
+* James Tucker
 * Jeremy Kemper
+* John Nunemaker
+* Lann Martin
+* Mahesh Murthy
+* Manu J
+* Matt Sanford
+* Nate Bird
+* Noah Lorang
+* Oscar Del Ben
+* Peter Mounce
+* Ray Krueger
+* Reed Lipman
+* rick
 * Ryan Tomayko
-* Gabriel Burt
-* Rick Olson
+* Schuyler Erle
+* Thomas Whaples
 * Trae Robrock
-* Corey Donohoe
-* James Tucker
 
 == Copyright
 
-Copyright (c) 2011 Rein Henrichs. See LICENSE.txt for further details.
+Copyright (c) 2011, 2012, 2013 Rein Henrichs. See LICENSE.txt for further details.

data/lib/statsd-ruby.rb

@@ -0,0 +1 @@
+require 'statsd'

data/lib/statsd.rb

@@ -1,10 +1,15 @@
 require 'socket'
 require 'forwardable'
+require 'json'
+
+require 'statsd/monotonic_time'
 
 # = Statsd: A Statsd client (https://github.com/etsy/statsd)
 #
-# @example Set up a global Statsd client for a server on localhost:9125
+# @example Set up a global Statsd client for a server on localhost:8125
 #   $statsd = Statsd.new 'localhost', 8125
+# @example Set up a global Statsd client for a server on IPv6 port 8125
+#   $statsd = Statsd.new '::1', 8125
 # @example Send some stats
 #   $statsd.increment 'garets'
 #   $statsd.timing 'glork', 320
@@ -15,8 +20,8 @@ require 'forwardable'
 #   statsd = Statsd.new('localhost').tap{|sd| sd.namespace = 'account'}
 #   statsd.increment 'activate'
 #
-# Statsd instances are thread safe for general usage, by using a thread local
-# UDPSocket and carrying no state. The attributes are stateful, and are not
+# Statsd instances are thread safe for general usage, by utilizing the thread
+# safe nature of UDP sends. The attributes are stateful, and are not
 # mutexed, it is expected that users will not change these at runtime in
 # threaded environments. If users require such use cases, it is recommend that
 # users either mutex around their Statsd object, or create separate objects for
@@ -43,18 +48,27 @@ class Statsd
 
     extend Forwardable
     def_delegators :@statsd,
-      :namespace, :namespace=, :host, :port, :prefix, :postfix
+      :namespace, :namespace=,
+      :host, :host=,
+      :port, :port=,
+      :prefix,
+      :postfix,
+      :delimiter, :delimiter=
 
-    attr_accessor :batch_size
+    attr_accessor :batch_size, :batch_byte_size, :flush_interval
 
-    # @param [Statsd] requires a configured Statsd instance
+    # @param [Statsd] statsd requires a configured Statsd instance
     def initialize(statsd)
       @statsd = statsd
       @batch_size = statsd.batch_size
+      @batch_byte_size = statsd.batch_byte_size
+      @flush_interval = statsd.flush_interval
       @backlog = []
+      @backlog_bytesize = 0
+      @last_flush = Time.now
     end
 
-    # @yields [Batch] yields itself
+    # @yield [Batch] yields itself
     #
     # A convenience method to ensure that data is not lost in the event of an
     # exception being thrown. Batches will be transmitted on the parent socket
@@ -69,20 +83,178 @@ class Statsd
       unless @backlog.empty?
         @statsd.send_to_socket @backlog.join("\n")
         @backlog.clear
+        @backlog_bytesize = 0
+        @last_flush = Time.now
       end
     end
 
     protected
 
     def send_to_socket(message)
+      # this message wouldn't fit; flush the queue. note that we don't have
+      # to do this for message based flushing, because we're incrementing by
+      # one, so the post-queue check will always catch it
+      if (@batch_byte_size && @backlog_bytesize + message.bytesize + 1 > @batch_byte_size) ||
+          (@flush_interval && last_flush_seconds_ago >= @flush_interval)
+        flush
+      end
       @backlog << message
-      if @backlog.size >= @batch_size
+      @backlog_bytesize += message.bytesize
+      # skip the interleaved newline for the first item
+      @backlog_bytesize += 1 if @backlog.length != 1
+      # if we're precisely full now, flush
+      if (@batch_size && @backlog.size == @batch_size) ||
+          (@batch_byte_size && @backlog_bytesize == @batch_byte_size)
         flush
       end
     end
 
+    def last_flush_seconds_ago
+      Time.now - @last_flush
+    end
+
   end
 
+  class Admin
+    # StatsD host. Defaults to 127.0.0.1.
+    attr_reader :host
+
+    # StatsD admin port. Defaults to 8126.
+    attr_reader :port
+
+    class << self
+      # Set to a standard logger instance to enable debug logging.
+      attr_accessor :logger
+    end
+
+    # @attribute [w] host.
+    #   Users should call connect after changing this.
+    def host=(host)
+      @host = host || '127.0.0.1'
+    end
+
+    # @attribute [w] port.
+    #   Users should call connect after changing this.
+    def port=(port)
+      @port = port || 8126
+    end
+
+    # @param [String] host your statsd host
+    # @param [Integer] port your statsd port
+    def initialize(host = '127.0.0.1', port = 8126)
+      @host = host || '127.0.0.1'
+      @port = port || 8126
+      # protects @socket transactions
+      @socket = nil
+      @s_mu = Mutex.new
+      connect
+    end
+
+    # Reads all gauges from StatsD.
+    def gauges
+      read_metric :gauges
+    end
+
+    # Reads all timers from StatsD.
+    def timers
+      read_metric :timers
+    end
+
+    # Reads all counters from StatsD.
+    def counters
+      read_metric :counters
+    end
+
+    # @param[String] item
+    #   Deletes one or more gauges. Wildcards are allowed.
+    def delgauges item
+      delete_metric :gauges, item
+    end
+
+    # @param[String] item
+    #   Deletes one or more timers. Wildcards are allowed.
+    def deltimers item
+      delete_metric :timers, item
+    end
+
+    # @param[String] item
+    #   Deletes one or more counters. Wildcards are allowed.
+    def delcounters item
+      delete_metric :counters, item
+    end
+
+    def stats
+      result = @s_mu.synchronize do
+        # the format of "stats" isn't JSON, who knows why
+        send_to_socket "stats"
+        read_from_socket
+      end
+      items = {}
+      result.split("\n").each do |line|
+        key, val = line.chomp.split(": ")
+        items[key] = val.to_i
+      end
+      items
+    end
+
+    # Reconnects the socket, for when the statsd address may have changed. Users
+    # do not normally need to call this, but calling it may be appropriate when
+    # reconfiguring a process (e.g. from HUP)
+    def connect
+      @s_mu.synchronize do
+        begin
+          @socket.flush rescue nil
+          @socket.close if @socket
+        rescue
+          # Ignore socket errors on close.
+        end
+        @socket = TCPSocket.new(host, port)
+      end
+    end
+
+    private
+
+    def read_metric name
+      result = @s_mu.synchronize do
+        send_to_socket name
+        read_from_socket
+      end
+      # for some reason, the reply looks like JSON, but isn't, quite
+      JSON.parse result.gsub("'", "\"")
+    end
+
+    def delete_metric name, item
+      result = @s_mu.synchronize do
+        send_to_socket "del#{name} #{item}"
+        read_from_socket
+      end
+      deleted = []
+      result.split("\n").each do |line|
+        deleted << line.chomp.split(": ")[-1]
+      end
+      deleted
+    end
+
+    def send_to_socket(message)
+      self.class.logger.debug { "Statsd: #{message}" } if self.class.logger
+      @socket.write(message.to_s + "\n")
+    rescue => boom
+      self.class.logger.error { "Statsd: #{boom.class} #{boom}" } if self.class.logger
+      nil
+    end
+
+
+    def read_from_socket
+      buffer = ""
+      loop do
+        line = @socket.readline
+        break if line == "END\n"
+        buffer += line
+      end
+      @socket.readline # clear the closing newline out of the socket
+      buffer
+    end
+  end
 
   # A namespace to prepend to all statsd calls.
   attr_reader :namespace
@@ -96,12 +268,21 @@ class Statsd
   # StatsD namespace prefix, generated from #namespace
   attr_reader :prefix
 
-  # The default batch size for new batches (default: 10)
+  # The default batch size for new batches. Set to nil to use batch_byte_size (default: 10)
   attr_accessor :batch_size
 
+  # The default batch size, in bytes, for new batches (default: default nil; use batch_size)
+  attr_accessor :batch_byte_size
+
+  # The flush interval, in seconds, for new batches (default: nil)
+  attr_accessor :flush_interval
+
   # a postfix to append to all metrics
   attr_reader :postfix
 
+  # The replacement of :: on ruby module names when transformed to statsd metric names
+  attr_reader :delimiter
+
   class << self
     # Set to a standard logger instance to enable debug logging.
     attr_accessor :logger
@@ -109,11 +290,20 @@ class Statsd
 
   # @param [String] host your statsd host
   # @param [Integer] port your statsd port
-  def initialize(host = '127.0.0.1', port = 8125)
-    self.host, self.port = host, port
+  # @param [Symbol] protocol :tcp for TCP, :udp or any other value for UDP
+  def initialize(host = '127.0.0.1', port = 8125, protocol = :udp)
+    @host = host || '127.0.0.1'
+    @port = port || 8125
+    self.delimiter = "."
     @prefix = nil
     @batch_size = 10
+    @batch_byte_size = nil
+    @flush_interval = nil
     @postfix = nil
+    @socket = nil
+    @protocol = protocol || :udp
+    @s_mu = Mutex.new
+    connect
   end
 
   # @attribute [w] namespace
@@ -135,16 +325,24 @@ class Statsd
 
   # @attribute [w] host
   #   Writes are not thread safe.
+  #   Users should call hup after making changes.
   def host=(host)
     @host = host || '127.0.0.1'
   end
 
   # @attribute [w] port
   #   Writes are not thread safe.
+  #   Users should call hup after making changes.
   def port=(port)
     @port = port || 8125
   end
 
+  # @attribute [w] stat_delimiter
+  #   Allows for custom delimiter replacement for :: when Ruby modules are transformed to statsd metric name
+  def delimiter=(delimiter)
+    @delimiter = delimiter || "."
+  end
+
   # Sends an increment (count = 1) for the given stat to the statsd server.
   #
   # @param [String] stat stat name
@@ -187,6 +385,22 @@ class Statsd
     send_stats stat, value, :g, sample_rate
   end
 
+  # Sends an arbitary set value for the given stat to the statsd server.
+  #
+  # This is for recording counts of unique events, which are useful to
+  # see on graphs to correlate to other values.  For example, a deployment
+  # might get recorded as a set, and be drawn as annotations on a CPU history
+  # graph.
+  #
+  # @param [String] stat stat name.
+  # @param [Numeric] value event value.
+  # @param [Numeric] sample_rate sample rate, 1 for always
+  # @example Report a deployment happening:
+  #   $statsd.set('deployment', DEPLOYMENT_EVENT_CODE)
+  def set(stat, value, sample_rate=1)
+    send_stats stat, value, :s, sample_rate
+  end
+
   # Sends a timing (in ms) for the given stat to the statsd server. The
   # sample_rate determines what percentage of the time this report is sent. The
   # statsd server then uses the sample_rate to correctly track the average
@@ -208,9 +422,10 @@ class Statsd
   # @example Report the time (in ms) taken to activate an account
   #   $statsd.time('account.activate') { @account.activate! }
   def time(stat, sample_rate=1)
-    start = Time.now
+    start = MonotonicTime.time_in_ms
     result = yield
-    timing(stat, ((Time.now - start) * 1000).round, sample_rate)
+  ensure
+    timing(stat, (MonotonicTime.time_in_ms - start).round, sample_rate)
     result
   end
 
@@ -225,14 +440,53 @@ class Statsd
   #     batch.gauge('user.count', User.count)
   #   end
   def batch(&block)
-    Batch.new(self).easy &block
+    Batch.new(self).easy(&block)
+  end
+
+  # Reconnects the socket, useful if the address of the statsd has changed. This
+  # method is not thread safe from a perspective of stat submission. It is safe
+  # from resource leaks. Users do not normally need to call this, but calling it
+  # may be appropriate when reconfiguring a process (e.g. from HUP).
+  def connect
+    @s_mu.synchronize do
+      begin
+        @socket.close if @socket
+      rescue
+        # Errors are ignored on reconnects.
+      end
+
+      case @protocol
+      when :tcp
+        @socket = TCPSocket.new @host, @port
+      else
+        @socket = UDPSocket.new Addrinfo.ip(@host).afamily
+        @socket.connect host, port
+      end
+    end
   end
 
   protected
 
   def send_to_socket(message)
     self.class.logger.debug { "Statsd: #{message}" } if self.class.logger
-    socket.send(message, 0, @host, @port)
+
+    retries = 0
+    n = 0
+    while true
+      # send(2) is atomic, however, in stream cases (TCP) the socket is left
+      # in an inconsistent state if a partial message is written. If that case
+      # occurs, the socket is closed down and we retry on a new socket.
+      message = @protocol == :tcp ? message + "\n" : message
+      n = socket.write(message) rescue (err = $!; 0)
+      if n == message.length
+        break
+      end
+
+      connect
+      retries += 1
+      raise (err || "statsd: Failed to send after #{retries} attempts") if retries >= 5
+    end
+    n
   rescue => boom
     self.class.logger.error { "Statsd: #{boom.class} #{boom}" } if self.class.logger
     nil
@@ -243,13 +497,15 @@ class Statsd
   def send_stats(stat, delta, type, sample_rate=1)
     if sample_rate == 1 or rand < sample_rate
       # Replace Ruby module scoping with '.' and reserved chars (: | @) with underscores.
-      stat = stat.to_s.gsub('::', '.').tr(':|@', '_')
+      stat = stat.to_s.gsub('::', delimiter).tr(':|@', '_')
       rate = "|@#{sample_rate}" unless sample_rate == 1
       send_to_socket "#{prefix}#{stat}#{postfix}:#{delta}|#{type}#{rate}"
     end
   end
 
   def socket
-    Thread.current[:statsd_socket] ||= UDPSocket.new
+    # Subtle: If the socket is half-way through initialization in connect, it
+    # cannot be used yet.
+    @s_mu.synchronize { @socket } || raise(ThreadError, "socket missing")
   end
 end