Clarified get_samples behavior

checks/__init__.py

@@ -1,9 +1,14 @@
-"""
-    Datadog agent
+"""Base class for Checks.
+
+If you are writing your own checks you should subclass the Check class.
+
+The typicall workflow works like this:
+1. Create your Check class
+2. Declare your metrics as gauges or counters
+3. Call save_sample for each metric
+4. Call get_metrics() to get results
+5. Plug the results into checks/common.py
 
-    Licensed under Simplified BSD License (see LICENSE)
-    (C) Boxed Ice 2010 all rights reserved
-    (C) Datadog, Inc 2011 All Rights Reserved
 """
 
 import logging
@@ -132,11 +137,14 @@ def save_sample(self, metric, value, timestamp=None, tags=None):
             value = float(value)
         except ValueError, ve:
             raise NaN(ve)
-
-        # sort tags
+        
+        # Sort and validate tags
         if tags is not None:
-            tags.sort()
-            tags = tuple(tags)
+            if type(tags) != type([]):
+                raise CheckException("Tags must be a list of string")
+            else:
+                tags.sort()
+                tags = tuple(tags)
 
         # Data eviction rules
         if self.is_gauge(metric):
@@ -177,6 +185,12 @@ def _rate(cls, sample1, sample2):
 
     def get_sample_with_timestamp(self, metric, tags=None):
         "Get (timestamp-epoch-style, value)"
+
+        # Get the proper tags
+        if tags is not None and type(tags) == type([]):
+            tags.sort()
+            tags = tuple(tags)
+
         # Never seen this metric
         if metric not in self._sample_store:
             raise UnknownValue()
@@ -201,7 +215,7 @@ def get_sample(self, metric, tags=None):
         return x[1]
 
     def get_samples_with_timestamps(self):
-        "Return all values {metric: (ts, value)}"
+        "Return all values {metric: (ts, value)} for non-tagged metrics"
         values = {}
         for m in self._sample_store:
             try:
@@ -211,7 +225,7 @@ def get_samples_with_timestamps(self):
         return values
 
     def get_samples(self):
-        "Return all values {metric: value}"
+        "Return all values {metric: value} for non-tagged metrics"
         values = {}
         for m in self._sample_store:
             try:
@@ -222,14 +236,21 @@ def get_samples(self):
         return values
 
     def get_metrics(self):
-        """This is the new format to send metrics backs
+        """Get all metrics, including the ones that are tagged.
+        This is the preferred method to retrieve metrics
+        
+        @return the list of samples
+        @rtype [(metric_name, timestamp, value, {"tags": ["tag1", "tag2]}), ...]
         """
         metrics = []
         for m in self._sample_store:
             try:
                 for t in self._sample_store[m]:
                    ts, val = self.get_sample_with_timestamp(m, t)
-                   metrics.append((m, int(ts), val, {"tags": list(t)}))
+                   if t is None:
+                       metrics.append((m, int(ts), val, {}))
+                   else:
+                       metrics.append((m, int(ts), val, {"tags": list(t)}))
             except:
                 pass
         return metrics

tests/test_common.py

@@ -27,6 +27,8 @@ def test_gauge(self):
         # with explicit timestamp
         self.c.save_sample("test-metric", 3.0, 1298066183.607717)
         self.assertEquals(self.c.get_sample_with_timestamp("test-metric"), (1298066183.607717, 3.0))
+        # get_samples()
+        self.assertEquals(self.c.get_samples(), {"test-metric": 3.0})
 
     def testEdgeCases(self):
         self.assertRaises(CheckException, self.c.get_sample, "unknown-metric")
@@ -41,6 +43,7 @@ def test_counter(self):
         self.c.save_sample("test-counter", 2.0, 2.0)
         self.assertEquals(self.c.get_sample("test-counter"), 1.0)
         self.assertEquals(self.c.get_sample_with_timestamp("test-counter"), (2.0, 1.0))
+        self.assertEquals(self.c.get_samples(), {"test-counter": 1.0})
         self.c.save_sample("test-counter", -2.0, 3.0)
         self.assertRaises(UnknownValue, self.c.get_sample_with_timestamp, "test-counter")
 
@@ -53,6 +56,8 @@ def test_tags(self):
         # Only 1 point recording for this combination of tags, won't be sent
         self.c.save_sample("test-counter", 3.0, 3.0, tags = ["tag1", "tag3"])
         self.c.save_sample("test-metric", 3.0, now, tags = ["tag3", "tag4"])
+        # Arg checks
+        self.assertRaises(CheckException, self.c.save_sample, "test-metric", 4.0, now + 5, tags = "abc")
         # This is a different combination of tags
         self.c.save_sample("test-metric", 3.0, now, tags = ["tag5", "tag3"])
         results = self.c.get_metrics()
@@ -62,6 +67,8 @@ def test_tags(self):
                            ("test-metric", now, 3.0, {"tags": ["tag3", "tag4"]}),
                            ("test-metric", now, 3.0, {"tags": ["tag3", "tag5"]}),
                            ])
+        # Tagged metrics are not available through get_samples anymore
+        self.assertEquals(self.c.get_samples(), {})
 
     def test_samples(self):
         self.assertEquals(self.c.get_samples(), {})