Add docs to demonstrate sampling messages

- Update Client.capture documentation to describe `sample_rate`
- Add section on sampling in the Advanced Usage docs

3 files changed, 26 insertions, 0 deletions

diff --git a/docs/advanced.rst b/docs/advanced.rst
index e60c7a5..3f07c17 100644
--- a/docs/advanced.rst
+++ b/docs/advanced.rst
@@ -267,6 +267,29 @@ deduplicate by taking into account the URL:
 
     For more information, see :ref:`custom-grouping`.
 
+Sampling Messages
+-----------------
+
+There are two ways to sample messages:
+
+- Add sample_rate to the Client object - This sends a percentage of messages the reaching the Client to Sentry
+
+    client = Client('___DSN___', sample_rate=0.5) # send 50% of events
+
+- Sample individual messages
+
+    client = Client('___DSN___') # No sample_rate provided
+
+    try:
+        1 / 0
+    except ZeroDivisionError:
+        client.captureException(sample_rate=0.5) # Send 50% of this event
+
+Alternatively, if you have SentryHandler configured in your logging stack,
+you can send ``sample_rate`` in the ``extra`` kwarg in each log like this
+
+    some_logger.warning('foo', extra={'sample_rate': 0.5}) # Send 50% of this event
+
 A Note on uWSGI
 ---------------
 
diff --git a/docs/api.rst b/docs/api.rst
index a84a2de..73b48b9 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -51,6 +51,8 @@ Client
         :param stack: If set to `True` a stack frame is recorded together
                       with the event.
         :param tags: dict of extra tags
+        :param sample_rate: a float in the range [0, 1] to sample this message.
+                            This overrides the Client object's sample_rate
         :param kwargs: extra keyword arguments are handled specific to the
                        reported event type.
         :return: a tuple with a 32-length string identifying this event
diff --git a/raven/base.py b/raven/base.py
index a41508b..b559fe9 100644
--- a/raven/base.py
+++ b/raven/base.py
@@ -615,6 +615,7 @@ class Client(object):
         :param extra: a dictionary of additional standard metadata
         :param stack: a stacktrace for the event
         :param tags: dict of extra tags
+        :param sample_rate: a float in the range [0, 1] to sample this message
         :return: a tuple with a 32-length string identifying this event
         """