dogapi 1.0.4 → 1.1.0

data/README.rdoc

@@ -1,35 +1,100 @@
-Ruby client for Datadog API v1.0.3
+= Ruby client for Datadog API v1.1.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
+== From Source
 
 Available at: https://github.com/DataDog/dogapi-rb
 
- $ cd dogapi-rb
- $ rake gem
- $ gem install pkg/dogapi-*.gem
+    $ cd dogapi-rb
+    $ rake gem
+    $ gem install pkg/dogapi-*.gem
 
-== RubyGems
+== Using RubyGems
 
 Gem page: https://rubygems.org/gems/dogapi
 
- $ gem install 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:
+== How to find your API Key
 
- $ export DATADOG_HOST=http://app.datadoghq.com/
+Go to your setup page[https://app.datadoghq.com/account/settings].
 
-Minimal example:
+== A word about hosts and devices
 
- require 'rubygems'
- require 'dogapi'
- 
- dog = Dogapi::Client.new(@api_key)
- dog.emit_point 'some.metric.name', 50.0
+Events and metric data points can be attached to hosts
+to take advantage of automatic tagging with the host's tags.
 
-Further usage examples are available in the source distribution under <code>examples/</code> and <code>tests/</code>.
+If you want to attach events and points to a specific device
+on a host, simply specify the device when calling emit functions.
+
+== Submit an event to Datadog
+
+=== If the event has no duration
+
+    require 'rubygems'
+    require 'dogapi'
+
+    api_key = "abcdef123456"
+
+    dog = Dogapi::Client.new(api_key)
+
+    dog.emit_event(Dogapi::Event.new('Testing done, FTW'), host => "my_host")
+
+=== If the event has a duration
+
+    require 'rubygems'
+    require 'dogapi'
+
+    api_key = "abcdef123456"
+
+    dog = Dogapi::Client.new(api_key)
+
+    dog.start_event(Dogapi::Event.new('My event with a duration'), host => "my_host") do
+    # do your work here...
+    # e.g. sleep 1
+    end
+    # stop_event will be sent automatically
+
+== Submit a metric to Datadog
+
+You want to track a new metric called +some.metric.name+ and have just sampled it from +my_device+ on +my_host+.
+Its value is 50. Here is how you submit the value to Datadog.
+
+    require 'rubygems'
+    require 'dogapi'
+
+    api_key = "abcdef123456"
+
+    dog = Dogapi::Client.new(api_key)
+
+    dog.emit_point 'some.metric.name', 50.0, host => "my_host", device => "my_device"
+
+Let us now assume that you have sampled the metric multiple times and you would like to submit the results.
+You can use the +emit_points+ method (instead of +emit_point+). Since you are submitting more than one
+data point you will need to pass a list of +Time+, +float+ pairs, instead of a simple +float+ value.
+
+    require 'rubygems'
+    require 'dogapi'
+
+    = Actual sampling takes place
+    t1 = Time.now
+    val1 = 50.0
+
+    = some time elapses
+    t2 = Time.now
+    val2 = 51.0
+
+    = some more time elapses
+    t3 = Time.now
+    val3 = -60.0
+
+    api_key = "abcdef123456"
+
+    dog = Dogapi::Client.new(api_key)
+
+    dog.emit_points 'some.metric.name', [[t1, val1], [t2, val2], [t3, val3]], host => "my_host", device => "my_device"

data/lib/dogapi/common.rb

@@ -20,24 +20,21 @@ module Dogapi
 
   # Superclass that deals with the details of communicating with the DataDog API
   class Service
-    def initialize(api_host=find_datadog_host)
+    def initialize(api_key, api_host=Dogapi.find_datadog_host)
+      @api_key = api_key
       @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)
+    def connect
+      uri = URI.parse(@host)
       session = Net::HTTP.new(uri.host, uri.port)
       if 'https' == uri.scheme
         session.use_ssl = true
-        session.verify_mode = OpenSSL::SSL::VERIFY_PEER
-        if File.directory? '/etc/ssl/certs'
-          session.ca_path = '/etc/ssl/certs'
-        end
+        # FIXME - turn off SSL verification for now until we can spend
+        # some time figuring out how to find certs across platforms.
+        # - matt 10/06/2011
+        session.verify_mode = OpenSSL::SSL::VERIFY_NONE
       end
       session.start do |conn|
         yield(conn)
@@ -75,14 +72,9 @@ module Dogapi
     end
   end
 
-  private
-
   def Dogapi.find_datadog_host
-    ENV['DATADOG_HOST'] rescue "app.datadoghq.com"
-  end
-
-  def Dogapi.find_api_key
-    ENV['DATADOG_KEY'] rescue nil
+    # allow env-based overriding, useful for tests
+    ENV["DATADOG_HOST"] || "https://app.datadoghq.com"
   end
 
   def Dogapi.find_localhost

data/lib/dogapi/facade.rb

@@ -18,9 +18,6 @@ module Dogapi
       end
 
       @datadog_host = Dogapi.find_datadog_host()
-      if !@datadog_host
-        raise 'DATADOG_HOST env variable not set'
-      end
 
       @host = host
       @device = device

data/tests/tc_client.rb

@@ -4,17 +4,7 @@ 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
+    @api_key = ENV['DATADOG_KEY']
   end
 
   def setup

data/tests/tc_env.rb

@@ -5,25 +5,19 @@ 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
+    assert_equal "https://app.datadoghq.com", Dogapi.find_datadog_host
   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

@@ -4,17 +4,7 @@ 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
+    @api_key = ENV['DATADOG_KEY']
   end
 
   def setup

data/tests/tc_metric.rb

@@ -5,17 +5,7 @@ require 'dogapi'
 class TestMetricClient < 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
+    @api_key = ENV['DATADOG_KEY']
   end
 
   def setup
@@ -34,14 +24,6 @@ class TestMetricClient < Test::Unit::TestCase
     ]
     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

metadata

@@ -1,12 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: dogapi
 version: !ruby/object:Gem::Version 
-  prerelease: false
+  hash: 19
+  prerelease: 
   segments: 
   - 1
+  - 1
   - 0
-  - 4
-  version: 1.0.4
+  version: 1.1.0
 platform: ruby
 authors: 
 - Datadog, Inc.
@@ -14,16 +15,17 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-10-06 00:00:00 -04:00
-default_executable: 
+date: 2011-10-06 00:00:00 Z
 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
@@ -51,7 +53,6 @@ files:
 - tests/tc_metric.rb
 - tests/ts_dogapi.rb
 - README.rdoc
-has_rdoc: true
 homepage: http://datadoghq.com/
 licenses: 
 - BSD
@@ -66,23 +67,27 @@ rdoc_options:
 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.3.6
+rubygems_version: 1.8.6
 signing_key: 
 specification_version: 3
 summary: Ruby bindings for Datadog's API