dogstatsd 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4541fbd03602c695372479982c0e530ca2bb8d1c
+  data.tar.gz: c7ce14813d97c3077695d73bd31ee33de178ed4c
+SHA512:
+  metadata.gz: 7142447c162ad59a7737dc90b748ea3fb6eb27c8a03d17155bdcc8673ef20988e2f4aa5a9f736696182f1ee6e0dc383a8ace632b85da144321800cf9ebca4c18
+  data.tar.gz: cc2250c86c1688d31016fd0175674316321ee3e26c89cd377b7c69ad22180f90951ad65e3640f52742fea21dc5033d2d9ec496926f5e43d62af3b0cd2ddd861a

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Rein Henrichs
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,89 @@
+
+dogstatsd
+=========
+
+A client for DogStatsD, an extension of the StatsD metric server for Datadog.
+
+[![Build Status](https://secure.travis-ci.org/DataDog/dogstatsd-ruby.png)](http://travis-ci.org/DataDog/dogstatsd-ruby)
+
+Quick Start Guide
+-----------------
+
+First install the library:
+
+    gem install dogstatsd
+
+Then start instrumenting your code:
+
+``` ruby
+# Load the dogstats module.
+require 'dogstatsd'
+
+# Create a stats instance.
+statsd = Dogstatsd.new('localhost', 8125)
+
+# Increment a counter.
+statsd.increment('page.views')
+
+# Record a gauge 50% of the time.
+statsd.gauge('users.online', 123, :sample_rate=>0.5)
+
+# Sample a histogram
+statsd.histogram('file.upload.size', 1234)
+
+# Time a block of code
+statsd.time('page.render') do
+  render_page('home.html')
+end
+
+# Send several metrics at the same time
+# All metrics will be buffered and sent in one packet when the block completes
+statsd.batch do |s|
+  s.increment('page.views')
+  s.gauge('users.online', 123)
+end
+
+# Tag a metric.
+statsd.histogram('query.time', 10, :tags => ["version:1"])
+```
+
+You can also post events to your stream. You can tag them, set priority and even aggregate them with other events.
+
+Aggregation in the stream is made on hostname/event_type/source_type/aggregation_key.
+
+``` ruby
+# Post a simple message
+statsd.event("There might be a storm tomorrow", "A friend warned me earlier.")
+
+# Cry for help
+statsd.event("SO MUCH SNOW", "Started yesterday and it won't stop !!", :alert_type => "error", :tags => ["urgent", "endoftheworld"])
+```
+
+
+
+Documentation
+-------------
+
+Full API documentation is available
+[here](http://www.rubydoc.info/github/DataDog/dogstatsd-ruby/master/frames).
+
+
+Feedback
+--------
+
+To suggest a feature, report a bug, or general discussion, head over
+[here](http://github.com/DataDog/dogstatsd-ruby/issues/).
+
+
+[Change Log](CHANGELOG.md)
+----------------------------
+
+
+Credits
+-------
+
+dogstatsd-ruby is forked from Rien Henrichs [original Statsd
+client](https://github.com/reinh/statsd).
+
+Copyright (c) 2011 Rein Henrichs. See LICENSE.txt for
+further details.

data/lib/dogstatsd.rb

@@ -0,0 +1,377 @@
+require 'socket'
+
+# = Dogstatsd: A Dogstatsd client (https://www.datadoghq.com)
+#
+# @example Set up a global Dogstatsd client for a server on localhost:8125
+#   require 'dogstatsd'
+#   $statsd = Dogstatsd.new 'localhost', 8125
+# @example Send some stats
+#   $statsd.increment 'page.views'
+#   $statsd.timing 'page.load', 320
+#   $statsd.gauge 'users.online', 100
+# @example Use {#time} to time the execution of a block
+#   $statsd.time('account.activate') { @account.activate! }
+# @example Create a namespaced statsd client and increment 'account.activate'
+#   statsd = Dogstatsd.new 'localhost', 8125, :namespace => 'account'
+#   statsd.increment 'activate'
+# @example Create a statsd client with global tags
+#   statsd = Dogstatsd.new 'localhost', 8125, :tags => 'tag1:true'
+class Dogstatsd
+
+  VERSION = '2.0.0'
+
+  DEFAULT_HOST = '127.0.0.1'
+  DEFAULT_PORT = 8125
+
+  # Create a dictionary to assign a key to every parameter's name, except for tags (treated differently)
+  # Goal: Simple and fast to add some other parameters
+  OPTS_KEYS = [
+        ['date_happened', 'd'],
+        ['hostname', 'h'],
+        ['aggregation_key', 'k'],
+        ['priority', 'p'],
+        ['source_type_name', 's'],
+        ['alert_type', 't']
+  ]
+
+  # Service check options
+  SC_OPT_KEYS = [
+        ['timestamp', 'd:'],
+        ['hostname', 'h:'],
+        ['tags', '#'],
+        ['message', 'm:']
+  ]
+  OK        = 0
+  WARNING   = 1
+  CRITICAL  = 2
+  UNKNOWN   = 3
+
+  # A namespace to prepend to all statsd calls. Defaults to no namespace.
+  attr_reader :namespace
+
+  # StatsD host. Defaults to 127.0.0.1.
+  attr_reader :host
+
+  # StatsD port. Defaults to 8125.
+  attr_reader :port
+
+  # Global tags to be added to every statsd call. Defaults to no tags.
+  attr_reader :tags
+
+  # Buffer containing the statsd message before they are sent in batch
+  attr_reader :buffer
+
+  # Maximum number of metrics in the buffer before it is flushed
+  attr_accessor :max_buffer_size
+
+  class << self
+    # Set to a standard logger instance to enable debug logging.
+    attr_accessor :logger
+  end
+
+  # @param [String] host your statsd host
+  # @param [Integer] port your statsd port
+  # @option opts [String] :namespace set a namespace to be prepended to every metric name
+  # @option opts [Array<String>] :tags tags to be added to every metric
+  def initialize(host = DEFAULT_HOST, port = DEFAULT_PORT, opts = {}, max_buffer_size=50)
+    self.host, self.port = host, port
+    @prefix = nil
+    @socket = UDPSocket.new
+    self.namespace = opts[:namespace]
+    self.tags = opts[:tags]
+    @buffer = Array.new
+    self.max_buffer_size = max_buffer_size
+    alias :send_stat :send_to_socket
+  end
+
+  def namespace=(namespace) #:nodoc:
+    @namespace = namespace
+    @prefix = namespace.nil? ? nil : "#{namespace}."
+  end
+
+  def host=(host) #:nodoc:
+    @host = host || '127.0.0.1'
+  end
+
+  def port=(port) #:nodoc:
+    @port = port || 8125
+  end
+
+  def tags=(tags) #:nodoc:
+    @tags = tags || []
+  end
+
+  # Sends an increment (count = 1) for the given stat to the statsd server.
+  #
+  # @param [String] stat stat name
+  # @param [Hash] opts the options to create the metric with
+  # @option opts [Numeric] :sample_rate sample rate, 1 for always
+  # @option opts [Array<String>] :tags An array of tags
+  # @see #count
+  def increment(stat, opts={})
+    count stat, 1, opts
+  end
+
+  # Sends a decrement (count = -1) for the given stat to the statsd server.
+  #
+  # @param [String] stat stat name
+  # @param [Hash] opts the options to create the metric with
+  # @option opts [Numeric] :sample_rate sample rate, 1 for always
+  # @option opts [Array<String>] :tags An array of tags
+  # @see #count
+  def decrement(stat, opts={})
+    count stat, -1, opts
+  end
+
+  # Sends an arbitrary count for the given stat to the statsd server.
+  #
+  # @param [String] stat stat name
+  # @param [Integer] count count
+  # @param [Hash] opts the options to create the metric with
+  # @option opts [Numeric] :sample_rate sample rate, 1 for always
+  # @option opts [Array<String>] :tags An array of tags
+  def count(stat, count, opts={})
+    send_stats stat, count, :c, opts
+  end
+
+  # Sends an arbitary gauge value for the given stat to the statsd server.
+  #
+  # This is useful for recording things like available disk space,
+  # memory usage, and the like, which have different semantics than
+  # counters.
+  #
+  # @param [String] stat stat name.
+  # @param [Numeric] value gauge value.
+  # @param [Hash] opts the options to create the metric with
+  # @option opts [Numeric] :sample_rate sample rate, 1 for always
+  # @option opts [Array<String>] :tags An array of tags
+  # @example Report the current user count:
+  #   $statsd.gauge('user.count', User.count)
+  def gauge(stat, value, opts={})
+    send_stats stat, value, :g, opts
+  end
+
+  # Sends a value to be tracked as a histogram to the statsd server.
+  #
+  # @param [String] stat stat name.
+  # @param [Numeric] value histogram value.
+  # @param [Hash] opts the options to create the metric with
+  # @option opts [Numeric] :sample_rate sample rate, 1 for always
+  # @option opts [Array<String>] :tags An array of tags
+  # @example Report the current user count:
+  #   $statsd.histogram('user.count', User.count)
+  def histogram(stat, value, opts={})
+    send_stats stat, value, :h, opts
+  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
+  # timing for the stat.
+  #
+  # @param [String] stat stat name
+  # @param [Integer] ms timing in milliseconds
+  # @param [Hash] opts the options to create the metric with
+  # @option opts [Numeric] :sample_rate sample rate, 1 for always
+  # @option opts [Array<String>] :tags An array of tags
+  def timing(stat, ms, opts={})
+    send_stats stat, ms, :ms, opts
+  end
+
+  # Reports execution time of the provided block using {#timing}.
+  #
+  # If the block fails, the stat is still reported, then the error
+  # is reraised
+  #
+  # @param [String] stat stat name
+  # @param [Hash] opts the options to create the metric with
+  # @option opts [Numeric] :sample_rate sample rate, 1 for always
+  # @option opts [Array<String>] :tags An array of tags
+  # @yield The operation to be timed
+  # @see #timing
+  # @example Report the time (in ms) taken to activate an account
+  #   $statsd.time('account.activate') { @account.activate! }
+  def time(stat, opts={})
+    start = Time.now
+    result = yield
+    time_since(stat, start, opts)
+    result
+  rescue
+    time_since(stat, start, opts)
+    raise
+  end
+  # Sends a value to be tracked as a set to the statsd server.
+  #
+  # @param [String] stat stat name.
+  # @param [Numeric] value set value.
+  # @param [Hash] opts the options to create the metric with
+  # @option opts [Numeric] :sample_rate sample rate, 1 for always
+  # @option opts [Array<String>] :tags An array of tags
+  # @example Record a unique visitory by id:
+  #   $statsd.set('visitors.uniques', User.id)
+  def set(stat, value, opts={})
+    send_stats stat, value, :s, opts
+  end
+
+
+  # This method allows you to send custom service check statuses.
+  #
+  # @param [String] name Service check name
+  # @param [String] status Service check status.
+  # @param [Hash] opts the additional data about the service check
+    # @option opts [Integer, nil] :timestamp (nil) Assign a timestamp to the event. Default is now when none
+    # @option opts [String, nil] :hostname (nil) Assign a hostname to the event.
+    # @option opts [Array<String>, nil] :tags (nil) An array of tags
+    # @option opts [String, nil] :message (nil) A message to associate with this service check status
+  # @example Report a critical service check status
+  #   $statsd.service_check('my.service.check', Dogstatsd::CRITICAL, :tags=>['urgent'])
+  def service_check(name, status, opts={})
+    service_check_string = format_service_check(name, status, opts)
+    send_to_socket service_check_string
+  end
+  def format_service_check(name, status, opts={})
+    sc_string = "_sc|#{name}|#{status}"
+
+    SC_OPT_KEYS.each do |name_key|
+      if opts[name_key[0].to_sym]
+        if name_key[0] == 'tags'
+          tags = opts[:tags]
+          tags.each do |tag|
+            rm_pipes tag
+          end
+          tags = "#{tags.join(",")}" unless tags.empty?
+          sc_string << "|##{tags}"
+        elsif name_key[0] == 'message'
+          message = opts[:message]
+          rm_pipes message
+          escape_service_check_message message
+          sc_string << "|m:#{message}"
+        else
+          value = opts[name_key[0].to_sym]
+          rm_pipes value
+          sc_string << "|#{name_key[1]}#{value}"
+        end
+      end
+    end
+    return sc_string
+  end
+
+  # This end point allows you to post events to the stream. You can tag them, set priority and even aggregate them with other events.
+  #
+  # Aggregation in the stream is made on hostname/event_type/source_type/aggregation_key.
+  # If there's no event type, for example, then that won't matter;
+  # it will be grouped with other events that don't have an event type.
+  #
+  # @param [String] title Event title
+  # @param [String] text Event text. Supports \n
+  # @param [Hash] opts the additional data about the event
+  # @option opts [Integer, nil] :date_happened (nil) Assign a timestamp to the event. Default is now when none
+  # @option opts [String, nil] :hostname (nil) Assign a hostname to the event.
+  # @option opts [String, nil] :aggregation_key (nil) Assign an aggregation key to the event, to group it with some others
+  # @option opts [String, nil] :priority ('normal') Can be "normal" or "low"
+  # @option opts [String, nil] :source_type_name (nil) Assign a source type to the event
+  # @option opts [String, nil] :alert_type ('info') Can be "error", "warning", "info" or "success".
+  # @option opts [Array<String>] :tags tags to be added to every metric
+  # @example Report an awful event:
+  #   $statsd.event('Something terrible happened', 'The end is near if we do nothing', :alert_type=>'warning', :tags=>['end_of_times','urgent'])
+  def event(title, text, opts={})
+    event_string = format_event(title, text, opts)
+    raise "Event #{title} payload is too big (more that 8KB), event discarded" if event_string.length > 8 * 1024
+
+    send_to_socket event_string
+  end
+
+  # Send several metrics in the same UDP Packet
+  # They will be buffered and flushed when the block finishes
+  #
+  # @example Send several metrics in one packet:
+  #   $statsd.batch do |s|
+  #      s.gauge('users.online',156)
+  #      s.increment('page.views')
+  #    end
+  def batch()
+    alias :send_stat :send_to_buffer
+    yield self
+    flush_buffer
+    alias :send_stat :send_to_socket
+  end
+
+  def format_event(title, text, opts={})
+    escape_event_content title
+    escape_event_content text
+    event_string_data = "_e{#{title.length},#{text.length}}:#{title}|#{text}"
+
+    # We construct the string to be sent by adding '|key:value' parts to it when needed
+    # All pipes ('|') in the metadata are removed. Title and Text can keep theirs
+    OPTS_KEYS.each do |name_key|
+      if name_key[0] != 'tags' && opts[name_key[0].to_sym]
+        value = opts[name_key[0].to_sym]
+        rm_pipes value
+        event_string_data << "|#{name_key[1]}:#{value}"
+      end
+    end
+    full_tags = tags + (opts[:tags] || [])
+    # Tags are joined and added as last part to the string to be sent
+    unless full_tags.empty?
+      full_tags.each do |tag|
+        rm_pipes tag
+      end
+      event_string_data << "|##{full_tags.join(',')}"
+    end
+
+    raise "Event #{title} payload is too big (more that 8KB), event discarded" if event_string_data.length > 8 * 1024
+    return event_string_data
+  end
+
+  private
+
+  def escape_event_content(msg)
+    msg.gsub! "\n", "\\n"
+  end
+
+  def rm_pipes(msg)
+    msg.gsub! "|", ""
+  end
+
+  def escape_service_check_message(msg)
+    msg.gsub! 'm:', 'm\:'
+    msg.gsub! "\n", "\\n"
+  end
+
+  def time_since(stat, start, opts)
+    timing(stat, ((Time.now - start) * 1000).round, opts)
+  end
+
+  def send_stats(stat, delta, type, opts={})
+    sample_rate = opts[: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(':|@', '_')
+      rate = "|@#{sample_rate}" unless sample_rate == 1
+      ts = (tags || []) + (opts[:tags] || [])
+      tags = "|##{ts.join(",")}" unless ts.empty?
+      send_stat "#{@prefix}#{stat}:#{delta}|#{type}#{rate}#{tags}"
+    end
+  end
+
+  def send_to_buffer(message)
+    @buffer << message
+    if @buffer.length >= @max_buffer_size
+      flush_buffer
+    end
+  end
+
+  def flush_buffer()
+    send_to_socket(@buffer.join("\n"))
+    @buffer = Array.new
+  end
+
+  def send_to_socket(message)
+    self.class.logger.debug { "Dogstatsd: #{message}" } if self.class.logger
+    @socket.send(message, 0, @host, @port)
+  rescue => boom
+    self.class.logger.error { "Dogstatsd: #{boom.class} #{boom}" } if self.class.logger
+    nil
+  end
+end
+

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: dogstatsd
+version: !ruby/object:Gem::Version
+  version: 2.0.0
+platform: ruby
+authors:
+- Rein Henrichs
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-07-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A Ruby DogStastd client
+email: code@datadoghq.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.md
+files:
+- LICENSE.txt
+- README.md
+- lib/dogstatsd.rb
+homepage: http://github.com/datadog/dogstatsd-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: A Ruby DogStatsd client
+test_files: []
+has_rdoc: