dogapi 1.0.1

data/README.rdoc

@@ -0,0 +1,34 @@
+Ruby client for Datadog API v1.0.0
+
+The Ruby client is a library suitable for inclusion in existing Ruby projects or for development of standalone scripts. It provides an abstraction on top of Datadog's raw HTTP interface for reporting events and metrics.
+
+= Installation
+
+== Source
+
+Available at: https://github.com/DataDog/dogapi-rb
+
+ $ cd dogapi-rb
+ $ rake gem
+ $ gem install pkg/dogapi-1.0.0.gem
+
+== RubyGems
+
+Gem page: https://rubygems.org/gems/dogapi
+
+ $ gem install dogapi
+
+= Usage
+
+The client expects the +DATADOG_HOST+ environment variable to be set to the host you will be submitting data to:
+
+ $ export DATADOG_HOST=http://app.datadoghq.com/
+
+Minimal example:
+
+ require 'dogapi'
+ 
+ dog = Dogapi::Client.new(@api_key)
+ dog.emit_point 'some.metric.name', 50.0
+
+Further usage examples are available in the source distribution under <code>examples/</code> and <code>tests/</code>.

data/lib/dogapi.rb

@@ -0,0 +1,4 @@
+require 'dogapi/common'
+require 'dogapi/facade'
+require 'dogapi/event'
+require 'dogapi/metric'

data/lib/dogapi/common.rb

@@ -0,0 +1,86 @@
+require 'cgi'
+require 'net/http'
+require 'pp'
+require 'socket'
+require 'uri'
+
+require 'rubygems'
+require 'json'
+
+module Dogapi
+
+  # Metadata class to hold the scope of an API call
+  class Scope
+    attr_reader :host, :device
+    def initialize(host=nil, device=nil)
+      @host = host
+      @device = device
+    end
+  end
+
+  # Superclass that deals with the details of communicating with the DataDog API
+  class Service
+    def initialize(api_host=find_datadog_host)
+      @host = api_host
+    end
+
+    # Manages the HTTP connection
+    def connect(api_key=nil, host=nil)
+
+      @api_key = api_key
+      host = host || @host
+
+      uri = URI.parse(host)
+      Net::HTTP.start(uri.host, uri.port) do |conn|
+        if 'https' == uri.scheme
+          conn.use_ssl = true
+        end
+        yield(conn)
+      end
+    end
+
+    # Prepares the request and handles the response
+    #
+    # +method+ is an implementation of Net::HTTP::Request (e.g. Net::HTTP::Post)
+    #
+    # +params+ is a Hash that will be converted to request parameters
+    def request(method, url, params)
+      if !params.has_key? :api_key
+        params[:api_key] = @api_key
+      end
+
+      resp_obj = nil
+      connect do |conn|
+        req = method.new(url)
+        req.set_form_data params
+        resp = conn.request(req)
+        begin
+          resp_obj = JSON.parse(resp.body)
+        rescue
+          raise 'Invalid JSON Response: ' + resp.body
+        end
+
+        if resp_obj.has_key? 'error'
+          request_string = params.pretty_inspect
+          error_string = resp_obj['error']
+          raise "Failed request\n#{request_string}#{error_string}"
+        end
+      end
+      resp_obj
+    end
+  end
+
+  private
+
+  def Dogapi.find_datadog_host
+    ENV['DATADOG_HOST'] rescue nil
+  end
+
+  def Dogapi.find_api_key
+    ENV['DATADOG_KEY'] rescue nil
+  end
+
+  def Dogapi.find_localhost
+    Socket.gethostname
+  end
+end

data/lib/dogapi/event.rb

@@ -0,0 +1,119 @@
+require 'net/http'
+
+require 'rubygems'
+require 'json'
+
+module Dogapi
+
+  # Metadata class for storing the details of an event
+  class Event
+    attr_reader :metric,
+      :date_detected,
+      :date_happened,
+      :alert_type,
+      :event_type,
+      :event_object,
+      :msg_title,
+      :msg_text,
+      :json_payload
+
+  # Optional arguments:
+  #  :metric        => String
+  #  :date_detected => time in seconds since the epoch (defaults to now)
+  #  :date_happened => time in seconds since the epoch (defaults to now)
+  #  :alert_type    => String
+  #  :event_type    => String
+  #  :event_object  => String
+  #  :msg_title     => String
+  #  :json_payload  => String
+    def initialize(msg_text, options={})
+      defaults = {
+        :metric => '',
+        :date_detected => Time.now.to_i,
+        :date_happened => Time.now.to_i,
+        :alert_type => '',
+        :event_type => '',
+        :event_object => '',
+        :msg_title => '',
+        :json_payload => ''
+      }
+      options = defaults.merge(options)
+
+      @msg_text = msg_text
+      @metric = options[:metric]
+      @date_detected = options[:date_detected]
+      @date_happened = options[:date_happened]
+      @alert_type = options[:alert_type]
+      @event_type = options[:event_type]
+      @event_object = options[:event_object]
+      @msg_title = options[:msg_title]
+      @json_payload = options[:json_payload]
+    end
+  end
+
+  # Event-specific client affording more granular control than the simple Dogapi::Client
+  class EventService < Dogapi::Service
+
+    API_VERSION = "1.0.0"
+
+    # Records an Event with no duration
+    def submit(api_key, event, scope=nil, source_type=nil)
+      scope = scope || Dogapi::Scope.new()
+      params = {
+        :api_key => api_key,
+        :api_version  =>  API_VERSION,
+
+        :host =>    scope.host,
+        :device =>  scope.device,
+
+        :metric =>  event.metric,
+        :date_detected => event.date_detected,
+        :date_happened => event.date_happened,
+        :alert_type => event.alert_type,
+        :event_type => event.event_type,
+        :event_object => event.event_object,
+        :msg_title => event.msg_title,
+        :msg_text => event.msg_text,
+        :json_payload => event.json_payload,
+      }
+
+      if source_type
+        params[:source_type] = source_type
+      end
+
+      request Net::HTTP::Post, '/event/submit', params
+    end
+
+    # Manages recording an event with a duration
+    #
+    # 0. The start time is recorded immediately
+    # 0. The given block is executed with access to the response of the start request
+    # 0. The end time is recorded once the block completes execution
+    def start(api_key, event, scope, source_type=nil)
+      response = submit api_key, event, scope, source_type
+      success = nil
+
+      begin
+        yield response
+      rescue
+        success = false
+        raise
+      else
+        success = true
+      ensure
+        return finish api_key, response['id'], success
+      end
+    end
+
+    private
+
+    def finish(api_key, event_id, successful=nil)
+      params = {
+        :api_key => api_key,
+        :event_id => event_id
+      }
+
+      request Net::HTTP::Post, '/event/ended', params
+    end
+  end
+end

data/lib/dogapi/facade.rb

@@ -0,0 +1,125 @@
+require 'time'
+require 'dogapi/metric'
+
+module Dogapi
+
+  # A simple DogAPI client
+  #
+  # See Dogapi::EventService and Dogapi::MetricService for the thick underlying clients
+  class Client
+
+    # Create a new Client optionally specifying a default host and device
+    def initialize(api_key, host=nil, device=nil)
+
+      if api_key
+        @api_key = api_key
+      else
+        raise 'Please provide an API key to submit your data'
+      end
+
+      @datadog_host = Dogapi.find_datadog_host()
+      if !@datadog_host
+        raise 'DATADOG_HOST env variable not set'
+      end
+
+      @host = host
+      @device = device
+
+      @metric_svc = Dogapi::MetricService.new(@datadog_host)
+      @event_svc = Dogapi::EventService.new(@datadog_host)
+    end
+
+    # Record a single point of metric data
+    #
+    # Optional arguments:
+    #  :timestamp => Ruby stdlib Time
+    #  :host      => String
+    #  :device    => String
+    def emit_point(metric, value, options={})
+      defaults = {:timestamp => Time.now, :host => nil, :device => nil}
+      options = defaults.merge(options)
+
+      self.emit_points metric,
+                       [[options[:timestamp], value]],
+                       :host => options[:host],
+                       :device => options[:device]
+    end
+
+    # Record a set of points of metric data
+    #
+    # +points+ is an array of <tt>[Time, value]</tt> doubles
+    #
+    # Optional arguments:
+    #  :host   => String
+    #  :device => String
+    def emit_points(metric, points, options={})
+      defaults = {:host => nil, :device => nil}
+      options = defaults.merge(options)
+
+      scope = override_scope options[:host], options[:device]
+
+      points.each do |p|
+        p[0].kind_of? Time or raise "Not a Time"
+        p[1].to_f # TODO: stupid to_f will never raise and exception
+      end
+
+      @metric_svc.submit @api_key, scope, metric, points
+    end
+
+    # Record an event with no duration
+    #
+    # If <tt>:source_type</tt> is unset, a generic "system" event will be reported
+    #
+    # Optional arguments:
+    #  :host        => String
+    #  :device      => String
+    #  :source_type => String
+    def emit_event(event, options={})
+      defaults = {:host => nil, :device => nil, :source_type => nil}
+      options = defaults.merge(options)
+
+      scope = override_scope options[:host], options[:device]
+
+      @event_svc.submit(@api_key, event, scope, options[:source_type])
+    end
+
+    # Record an event with a duration
+    #
+    # 0. The start time is recorded immediately
+    # 0. The given block is executed
+    # 0. The end time is recorded once the block completes execution
+    #
+    # If <tt>:source_type</tt> is unset, a generic "system" event will be reported
+    #
+    # Optional arguments:
+    #  :host        => String
+    #  :device      => String
+    #  :source_type => String
+    def start_event(event, options={})
+      defaults = {:host => nil, :device => nil, :source_type => nil}
+      options = defaults.merge(options)
+
+      scope = override_scope options[:host], options[:device]
+
+      @event_svc.start(@api_key, event, scope, options[:source_type]) do
+        yield
+      end
+    end
+
+    private
+
+    def override_scope(host, device)
+      if host
+        h = host
+      else
+        h = @host
+      end
+      if device
+        d = device
+      else
+        d = @device
+      end
+      Scope.new(h, d)
+    end
+  end
+end

data/lib/dogapi/metric.rb

@@ -0,0 +1,30 @@
+require 'net/http'
+
+require 'rubygems'
+require 'json'
+
+module Dogapi
+
+  class MetricService < Dogapi::Service
+
+    API_VERSION = "1.0.0"
+
+    # Records some number of points for a given metric
+    def submit(api_key, scope, metric, points)
+      series = [{
+        :host    =>  scope.host,
+        :device  =>  scope.device,
+        :metric  =>  metric,
+        :points  =>  points.map { |p| [p[0].to_i, p[1]] }
+      }]
+
+      params = {
+        :api_key      =>  api_key,
+        :api_version  =>  API_VERSION,
+        :series       =>  series.to_json
+      }
+
+      request Net::HTTP::Post, '/series/submit', params
+    end
+  end
+end

data/tests/tc_client.rb

@@ -0,0 +1,47 @@
+require 'test/unit'
+require 'dogapi'
+
+class TestClient < Test::Unit::TestCase
+
+  def config_client_test_env
+    @api_key = Dogapi.find_api_key
+    if !@api_key
+      @api_key = 'apikey_2'
+      ENV['DATADOG_KEY'] = @api_key
+    end
+
+    @host = Dogapi.find_datadog_host
+    if !@host
+      @host = 'localhost:5000'
+      ENV['DATADOG_HOST'] = @host
+    end
+  end
+
+  def setup
+    config_client_test_env
+  end
+
+  def test_simple_client
+    dog = Dogapi::Client.new(@api_key)
+
+    dog.emit_point 'test.dogclient.emit_point',
+                   999,
+                   :host => 'test.dogclient.fake',
+                   :device => 'eth0'
+
+    dog.emit_points 'test.dogclient.emit_points',
+                    [[Time.now - 60, 10], [Time.now - 30, 20], [Time.now, 30]],
+                    :host => 'test.dogclient.fake',
+                    :device => 'eth0'
+
+    my_event = Dogapi::Event.new('Testing Event API')
+    dog.emit_event my_event,
+      :host => 'test.dogclient.fake',
+      :device => 'eth0'
+
+    my_event = Dogapi::Event.new('Testing Event API with a duration')
+    dog.start_event(my_event, :host =>'test.dogclient.fake', :device => 'eth0') do
+      sleep 1
+    end
+  end
+end

data/tests/tc_env.rb

@@ -0,0 +1,29 @@
+require 'test/unit'
+require 'dogapi'
+
+class TestEnvironment < Test::Unit::TestCase
+
+  def setup
+    @host = ENV['DATADOG_HOST']
+    @key = ENV['DATADOG_KEY']
+  end
+
+  def teardown
+    ENV['DATADOG_HOST'] = @host
+    ENV['DATADOG_KEY'] = @key
+  end
+
+  def test_unset
+    ENV['DATADOG_HOST'] = nil
+    ENV['DATADOG_KEY'] = nil
+    assert_equal nil, Dogapi.find_datadog_host
+    assert_equal nil, Dogapi.find_api_key
+  end
+
+  def test_set
+    ENV['DATADOG_HOST'] = 'test.host'
+    ENV['DATADOG_KEY'] = 'test_key'
+    assert_equal 'test.host', Dogapi.find_datadog_host
+    assert_equal 'test_key', Dogapi.find_api_key
+  end
+end

data/tests/tc_event.rb

@@ -0,0 +1,46 @@
+require 'test/unit'
+require 'dogapi'
+
+class TestEventClient < Test::Unit::TestCase
+
+  def config_client_test_env
+    @api_key = Dogapi.find_api_key
+    if !@api_key
+      @api_key = 'apikey_2'
+      ENV['DATADOG_KEY'] = @api_key
+    end
+
+    @host = Dogapi.find_datadog_host
+    if !@host
+      @host = 'localhost:5000'
+      ENV['DATADOG_HOST'] = @host
+    end
+  end
+
+  def setup
+    config_client_test_env
+  end
+
+  def submit_event(scope=nil, source_type=nil)
+    event_service = Dogapi::EventService.new(@host)
+    tok = '#' + (rand(10000)+1).to_s
+    test_message = 'event_test_' + tok
+    event = Dogapi::Event.new(test_message, :event_type => 'test-event-type')
+    res = event_service.submit(@api_key, event, scope, source_type)
+    assert_not_equal(res['id'], nil)
+  end
+
+  def test_submit_event
+    submit_event
+  end
+
+  def test_submit_scoped_event
+    submit_event(Dogapi::Scope.new('scoped-testhost', 'testdevice'))
+  end
+
+  def test_submit_event
+    submit_event(Dogapi::Scope.new('typed-testhost', 'testdevice'), 'Nagios')
+    submit_event(Dogapi::Scope.new('typed-testhost', 'testdevice'), 'GitHub')
+  end
+
+end

data/tests/tc_metric.rb

@@ -0,0 +1,47 @@
+require 'test/unit'
+require 'time'
+require 'dogapi'
+
+class TestEnvironment < Test::Unit::TestCase
+
+  def config_client_test_env
+    @api_key = Dogapi.find_api_key
+    if !@api_key
+      @api_key = 'apikey_2'
+      ENV['DATADOG_KEY'] = @api_key
+    end
+
+    @host = Dogapi.find_datadog_host
+    if !@host
+      @host = 'localhost:5000'
+      ENV['DATADOG_HOST'] = @host
+    end
+  end
+
+  def setup
+    config_client_test_env
+  end
+
+  def test_submit_metric
+    metric_service = Dogapi::MetricService.new(@host)
+    scope = Dogapi::Scope.new('test.dogclient.fake', 'eth0')
+    metric = 'test.dogclient.metric.submit_metric'
+    points = [
+      [Time.now-90, 1.0],
+      [Time.now-60, 2.0],
+      [Time.now-30, 4.0],
+      [Time.now,    8.0]
+    ]
+    res = metric_service.submit(@api_key, scope, metric, points)
+    assert_equal(res['status'], 'ok')
+    assert_equal(res['results'].size, 1)
+    r = res['results'][0]
+    assert_equal(r['host'], scope.host)
+    if scope.device
+      assert_equal(r['device'], scope.device)
+    end
+    assert_equal(r['metric'], metric)
+    assert_equal(r['length'], points.size)
+  end
+
+end

data/tests/ts_dogapi.rb

@@ -0,0 +1,6 @@
+require 'test/unit'
+
+require 'tc_env'
+require 'tc_client'
+require 'tc_event'
+require 'tc_metric'

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification 
+name: dogapi
+version: !ruby/object:Gem::Version 
+  hash: 21
+  prerelease: 
+  segments: 
+  - 1
+  - 0
+  - 1
+  version: 1.0.1
+platform: ruby
+authors: 
+- Datadog, Inc.
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-03-21 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 1
+        segments: 
+        - 1
+        - 5
+        - 1
+        version: 1.5.1
+  type: :runtime
+  version_requirements: *id001
+description: 
+email: packages@datadoghq.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- lib/dogapi/common.rb
+- lib/dogapi/event.rb
+- lib/dogapi/facade.rb
+- lib/dogapi/metric.rb
+- lib/dogapi.rb
+- tests/tc_client.rb
+- tests/tc_env.rb
+- tests/tc_event.rb
+- tests/tc_metric.rb
+- tests/ts_dogapi.rb
+- README.rdoc
+has_rdoc: true
+homepage: http://datadoghq.com/
+licenses: 
+- BSD
+post_install_message: 
+rdoc_options: 
+- --title
+- DogAPI -- DataDog Client
+- --main
+- README.rdoc
+- --line-numbers
+- --inline-source
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Ruby bindings for Datadog's API
+test_files: 
+- tests/ts_dogapi.rb