Merge lp:~ricardokirkner/txstatsd/gauge-with-delta into lp:txstatsd

[Ricardo Kirkner]

added support for gauges with delta values

Support gauges with delta values.

This feature is supported by recent statsd versions, but not yet supported by txstatsd.

For reference:

Statsd Server
https://github.com/etsy/statsd/blob/master/docs/metric_types.md#gauges

Statsd client
http://statsd.readthedocs.org/en/latest/types.html#gauge-deltas

[Lucio Torre (lucio.torre)]

this api seems like counters, have you looked at that?

review: Needs Information

[Ricardo Kirkner (ricardokirkner)]

> this api seems like counters, have you looked at that?

Haven't looked into txstatsd counters in detail yet, but will do. I added this gauge delta support because it's supported by the "official" statsd server, so clients (other than txstatsd) are starting to support it.

[Ricardo Kirkner (ricardokirkner)]

> > this api seems like counters, have you looked at that?
>
> Haven't looked into txstatsd counters in detail yet, but will do. I added this
> gauge delta support because it's supported by the "official" statsd server, so
> clients (other than txstatsd) are starting to support it.

counters are supposed to be reset to 0 every 10s (ie, after every flush)... gauges are not; if the value didn't change statsd will send the latest available value.
Even if counters implement the same api as gauges for this in txstatsd, it's not possible to use non-txstatsd clients with a txstatsd server as the standard api for counters in statsd doesn't support deltas. This is why I'm adding delta support for gauges (so that we can use other statsd clients with a txstatsd server)

[James Westby (james-w)]

This looks ok to me, with 1 comment.

[James Westby (james-w)]

review: Approve

[Ubuntu One Auto Pilot (otto-pilot)]

Voting does not meet specified criteria. Required: Approve >= 1, Disapprove == 0, Needs Fixing == 0, Needs Information == 0, Resubmit == 0, Pending == 0. Got: 1 Approve, 1 Needs Information.

[Lucio Torre (lucio.torre)]

review: Approve

=== modified file 'txstatsd/metrics/gaugemetric.py'
--- txstatsd/metrics/gaugemetric.py	2012-06-28 17:29:26 +0000
+++ txstatsd/metrics/gaugemetric.py	2014-10-03 19:54:06 +0000
@@ -37,9 +37,12 @@
         """
         Metric.__init__(self, connection, name, sample_rate=sample_rate)
 
-    def mark(self, value):
+    def mark(self, value, delta=False):
         """Report the C{value} for this gauge."""
-        self.send("%s|g" % value)
+        if delta and value > 0:
+            self.send("+%s|g" % value)
+        else:
+            self.send("%s|g" % value)
 
 
 class GaugeMetricReporter(object):
@@ -57,8 +60,11 @@
         self.prefix = prefix
         self.value = 0
 
-    def mark(self, value):
-        self.value = value
+    def mark(self, value, delta=False):
+        if delta:
+            self.value += value
+        else:
+            self.value = value
 
     def report(self, timestamp):
         return [(self.prefix + self.name + ".value", self.value, timestamp)]

=== modified file 'txstatsd/metrics/metrics.py'
--- txstatsd/metrics/metrics.py	2012-06-28 17:29:26 +0000
+++ txstatsd/metrics/metrics.py	2014-10-03 19:54:06 +0000
@@ -84,7 +84,7 @@
         """
         self.report(name, "error", "sli")
 
-    def gauge(self, name, value, sample_rate=1):
+    def gauge(self, name, value, sample_rate=1, delta=False):
         """Report an instantaneous reading of a particular value."""
         name = self.fully_qualify_name(name)
         if not name in self._metrics:
@@ -92,7 +92,7 @@
                                        name,
                                        sample_rate)
             self._metrics[name] = gauge_metric
-        self._metrics[name].mark(value)
+        self._metrics[name].mark(value, delta=delta)
 
     def meter(self, name, value=1, sample_rate=1):
         """Mark the occurrence of a given number of events."""

=== modified file 'txstatsd/server/processor.py'
--- txstatsd/server/processor.py	2013-10-15 20:56:49 +0000
+++ txstatsd/server/processor.py	2014-10-03 19:54:06 +0000
@@ -191,15 +191,25 @@
         if not len(values) == 1:
             return self.fail(message)
 
+        delta = False
+        value = values[0]
+        if value.startswith('+') or value.startswith('-'):
+            delta = True
         try:
-            value = float(values[0])
+            value = float(value)
         except (TypeError, ValueError):
             self.fail(message)
 
-        self.compose_gauge_metric(key, value)
+        self.compose_gauge_metric(key, value, delta=delta)
 
-    def compose_gauge_metric(self, key, value):
+    def compose_gauge_metric(self, key, value, delta=False):
         metric = [value, key]
+        if delta:
+            for item in reversed(self.gauge_metrics):
+                if item[1] == key:
+                    old_value = item[0]
+                    metric = [old_value + value, key]
+                    break
         self.gauge_metrics.append(metric)
 
     def process_meter_metric(self, key, composite, message):

=== modified file 'txstatsd/tests/test_metrics.py'
--- txstatsd/tests/test_metrics.py	2013-03-06 21:50:26 +0000
+++ txstatsd/tests/test_metrics.py	2014-10-03 19:54:06 +0000
@@ -49,11 +49,23 @@
         self.metrics = Metrics(self.connection, 'txstatsd.tests')
 
     def test_gauge(self):
-        """Test reporting of a gauge metric sample."""
+        """Test reporting of an absolute gauge metric sample."""
         self.metrics.gauge('gauge', 102)
         self.assertEqual(self.connection.data,
                          b'txstatsd.tests.gauge:102|g')
 
+    def test_gauge_with_positive_delta(self):
+        """Test reporting of a relative gauge metric sample."""
+        self.metrics.gauge('gauge', 102, delta=True)
+        self.assertEqual(self.connection.data,
+                         b'txstatsd.tests.gauge:+102|g')
+
+    def test_gauge_with_negative_delta(self):
+        """Test reporting of a relative gauge metric sample."""
+        self.metrics.gauge('gauge', -102, delta=True)
+        self.assertEqual(self.connection.data,
+                         b'txstatsd.tests.gauge:-102|g')
+
     def test_meter(self):
         """Test reporting of a meter metric sample."""
         self.metrics.meter('meter', 3)

=== modified file 'txstatsd/tests/test_processor.py'
--- txstatsd/tests/test_processor.py	2013-10-15 20:56:49 +0000
+++ txstatsd/tests/test_processor.py	2014-10-03 19:54:06 +0000
@@ -113,6 +113,76 @@
             [9.6, 'gorets'],
             self.processor.gauge_metrics.pop())
 
+    def test_receive_gauge_metrics_positive_delta(self):
+        """
+        A gauge metric message takes the form:
+        '<name>:count|g' if the value is considered absolute
+        '<name>:[+-]count|g' if the value is considered relative
+        'g' indicates this is a gauge metrics message.
+        """
+        self.processor.process("gorets:9.6|g")
+        self.processor.process("gorets:+1|g")
+        self.assertEqual(2, len(self.processor.gauge_metrics))
+        self.assertEqual(
+            [10.6, 'gorets'],
+            self.processor.gauge_metrics.pop())
+
+    def test_receive_gauge_metrics_positive_delta_without_initial_value(self):
+        """
+        A gauge metric message takes the form:
+        '<name>:count|g' if the value is considered absolute
+        '<name>:[+-]count|g' if the value is considered relative
+        'g' indicates this is a gauge metrics message.
+        """
+        self.processor.process("gorets:+1|g")
+        self.assertEqual(1, len(self.processor.gauge_metrics))
+        self.assertEqual(
+            [1, 'gorets'],
+            self.processor.gauge_metrics.pop())
+
+    def test_receive_gauge_metrics_multiple_deltas(self):
+        """
+        A gauge metric message takes the form:
+        '<name>:count|g' if the value is considered absolute
+        '<name>:[+-]count|g' if the value is considered relative
+        'g' indicates this is a gauge metrics message.
+        """
+        self.processor.process("gorets:+1|g")
+        self.processor.process("gorets:+1|g")
+        self.processor.process("gorets:+1|g")
+        self.processor.process("gorets:+1|g")
+        self.assertEqual(4, len(self.processor.gauge_metrics))
+        self.assertEqual(
+            [4, 'gorets'],
+            self.processor.gauge_metrics.pop())
+
+    def test_receive_gauge_metrics_negative_delta(self):
+        """
+        A gauge metric message takes the form:
+        '<name>:count|g' if the value is considered absolute
+        '<name>:[+-]count|g' if the value is considered relative
+        'g' indicates this is a gauge metrics message.
+        """
+        self.processor.process("gorets:9.6|g")
+        self.processor.process("gorets:-1.2|g")
+        self.assertEqual(2, len(self.processor.gauge_metrics))
+        self.assertEqual(
+            [8.4, 'gorets'],
+            self.processor.gauge_metrics.pop())
+
+    def test_receive_gauge_metrics_negative_delta_without_initial_value(self):
+        """
+        A gauge metric message takes the form:
+        '<name>:count|g' if the value is considered absolute
+        '<name>:[+-]count|g' if the value is considered relative
+        'g' indicates this is a gauge metrics message.
+        """
+        self.processor.process("gorets:-1.2|g")
+        self.assertEqual(1, len(self.processor.gauge_metrics))
+        self.assertEqual(
+            [-1.2, 'gorets'],
+            self.processor.gauge_metrics.pop())
+
     def test_receive_distinct_metric(self):
         """
         A distinct metric message takes the form: