Merge remote-tracking branch 'ustudio/master'

4 files changed, 64 insertions, 0 deletions

diff --git a/docs/reference.rst b/docs/reference.rst
index df74e75..72f0fa9 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -154,6 +154,32 @@ Set a :ref:`gauge <gauge-type>` value.
    not be recorded.
 
 
+.. _set:
+
+``set``
+=========
+
+::
+
+    StatsClient().set(stat, value, rate=1)
+
+Increment a :ref:`set <set-type>` value.
+
+* ``stat``: the name of the set to update.
+
+* ``value``: the unique value to count.
+
+* ``rate``: a sample rate, a float between 0 and 1. Will only send data
+  this percentage of the time. The statsd server does *not* take the
+  sample rate into account for sets. Use with care.
+
+.. note::
+
+   Sets were added to the statsd server in commit 1c10cfc0ac_. If you
+   try to use this method with an older version of the server, the
+   data will not be recorded.
+
+
 .. _pipeline:
 
 ``pipeline``
diff --git a/docs/types.rst b/docs/types.rst
index 66c742c..31a1f3d 100644
--- a/docs/types.rst
+++ b/docs/types.rst
@@ -143,6 +143,22 @@ keyword argument to ``True``. For example::
    to have any effect.
 
 
+.. _set-type:
+
+Sets
+======
+
+*Sets* count the number of unique values passed to a key.
+
+For example, you could count the number of users accessing your system
+using:
+
+    statsd.set('users', userid)
+
+If that method is called multiple times with the same userid in the
+same sample period, that userid will only be counted once.
+
+
 .. _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 677c8f5..c69405d 100644
--- a/statsd/client.py
+++ b/statsd/client.py
@@ -78,6 +78,12 @@ class StatsClient(object):
         if data is not None:
             self._after(data)
 
+    def set(self, stat, value, rate=1):
+        """Set a set value."""
+        data = self._prepare(stat, '%s|s' % value, rate)
+        if data is not None:
+            self._after(data)
+
     def _prepare(self, stat, value, rate=1):
         if rate < 1:
             if random.random() < rate:
diff --git a/statsd/tests.py b/statsd/tests.py
index 7d9f73d..1e6f6e0 100644
--- a/statsd/tests.py
+++ b/statsd/tests.py
@@ -147,6 +147,22 @@ def test_gauge_delta():
 
 
 @mock.patch.object(random, 'random', lambda: -1)
+def test_set():
+    sc = _client()
+    sc.set('foo', 10)
+    _sock_check(sc, 1, 'foo:10|s')
+
+    sc.set('foo', 2.3)
+    _sock_check(sc, 2, 'foo:2.3|s')
+
+    sc.set('foo', 'bar')
+    _sock_check(sc, 3, 'foo:bar|s')
+
+    sc.set('foo', 2.3, 0.5)
+    _sock_check(sc, 4, 'foo:2.3|s|@0.5')
+
+
+@mock.patch.object(random, 'random', lambda: -1)
 def test_timing():
     sc = _client()