Support gauge deltas. Fixes #21.

5 files changed, 48 insertions, 3 deletions

diff --git a/CHANGES b/CHANGES
index 37b7dd8..e621e25 100644
--- a/CHANGES
+++ b/CHANGES
@@ -6,6 +6,8 @@ Version 2.0
 
 - Add Pipeline subclass for batching.
 - Added an _after method subclasses can use to change behavior.
+- Add support for gauge deltas.
+
 
 Version 1.0
 -----------
@@ -14,12 +16,14 @@ Version 1.0
 - Encode socket data in ASCII.
 - Tag v1.
 
+
 Version 0.5.1
 -------------
 
 - Stop supporting IPv6. StatsD doesn't support it, and it breaks things.
 - incr, decr, and gauge now support floating point values.
 
+
 Version 0.5.0
 -------------
 
diff --git a/docs/reference.rst b/docs/reference.rst
index 845f239..df74e75 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -131,7 +131,7 @@ call.  See also the :ref:`chapter on timing <timing-chapter>`.
 
 ::
 
-    StatsClient().gauge(stat, value, rate=1)
+    StatsClient().gauge(stat, value, rate=1, delta=False)
 
 Set a :ref:`gauge <gauge-type>` value.
 
@@ -143,6 +143,10 @@ Set a :ref:`gauge <gauge-type>` value.
   this percentage of the time. The statsd server does *not* take the
   sample rate into account for gauges. Use with care.
 
+* ``delta``: whether or not to consider this a delta value or an
+  absolute value. See the :ref:`gauge <gauge-type>` type for more
+  detail.
+
 .. note::
 
    Gauges were added to the statsd server in commit 0ed78be_. If you try
diff --git a/docs/types.rst b/docs/types.rst
index b6d4daa..66c742c 100644
--- a/docs/types.rst
+++ b/docs/types.rst
@@ -126,5 +126,23 @@ data back to the statsd server, but use it with care, especially with
 gauges that may not be updated very often.
 
 
+Gauge Deltas
+------------
+
+Gauges may be *updated* (as opposed to *set*) by setting the ``delta``
+keyword argument to ``True``. For example::
+
+    statsd.gauge('foo', 70)  # Set the 'foo' gauge to 70.
+    statsd.gauge('foo', 1, delta=True)  # Set 'foo' to 71.
+    statsd.gauge('foo', -3, delta=True)  # Set 'foo' to 68.
+
+.. note::
+
+   Support for gauge deltas was added to the server in 3eecd18_. You
+   will need to be running at least that version for the ``delta`` kwarg
+   to have any effect.
+
+
 .. _statsd: https://github.com/etsy/statsd
 .. _Graphite: http://graphite.wikidot.com/
+.. _3eecd18: https://github.com/etsy/statsd/commit/3eecd18
diff --git a/statsd/client.py b/statsd/client.py
index cef1669..e88d23a 100644
--- a/statsd/client.py
+++ b/statsd/client.py
@@ -68,9 +68,13 @@ class StatsClient(object):
         """Decrement a stat by `count`."""
         self.incr(stat, -count, rate)
 
-    def gauge(self, stat, value, rate=1):
+    def gauge(self, stat, value, rate=1, delta=False):
         """Set a gauge value."""
-        data = self._prepare(stat, '%s|g' % value, rate)
+        if delta:
+            value = '%+g|g' % value
+        else:
+            value = '%g|g' % value
+        data = self._prepare(stat, value, rate)
         if data is not None:
             self._after(data)
 
diff --git a/statsd/tests.py b/statsd/tests.py
index eeaf575..4e9cd3d 100644
--- a/statsd/tests.py
+++ b/statsd/tests.py
@@ -131,6 +131,21 @@ def test_gauge():
     _sock_check(sc, 3, 'foo:70|g|@0.5')
 
 
+def test_gauge_delta():
+    sc = _client()
+    sc.gauge('foo', 12, delta=True)
+    _sock_check(sc, 1, 'foo:+12|g')
+
+    sc.gauge('foo', -13, delta=True)
+    _sock_check(sc, 2, 'foo:-13|g')
+
+    sc.gauge('foo', 1.2, delta=True)
+    _sock_check(sc, 3, 'foo:+1.2|g')
+
+    sc.gauge('foo', -1.3, delta=True)
+    _sock_check(sc, 4, 'foo:-1.3|g')
+
+
 @mock.patch.object(random, 'random', lambda: -1)
 def test_timing():
     sc = _client()