Permalink
Browse files

Support gauge deltas. Fixes #21.

  • Loading branch information...
1 parent 4d3a196 commit 7ed4f77ff9915a9c1957a2a45e6d02c2dc644a85 @jsocol committed Mar 6, 2013
Showing with 48 additions and 3 deletions.
  1. +4 −0 CHANGES
  2. +5 −1 docs/reference.rst
  3. +18 −0 docs/types.rst
  4. +6 −2 statsd/client.py
  5. +15 −0 statsd/tests.py
View
@@ -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
-------------
View
@@ -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
View
@@ -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
View
@@ -68,9 +68,13 @@ def decr(self, stat, count=1, rate=1):
"""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)
View
@@ -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()

0 comments on commit 7ed4f77

Please sign in to comment.