Added docs on context thread management

2 files changed, 55 insertions, 0 deletions

diff --git a/docs/breadcrumbs.rst b/docs/breadcrumbs.rst
index ffdbb0f..0178ddf 100644
--- a/docs/breadcrumbs.rst
+++ b/docs/breadcrumbs.rst
@@ -102,3 +102,27 @@ modifications:
     record_breadcrumb(message='This is an important message',
                       category='my_module', level='warning',
                       processor=process_crumb)
+
+Context Thread Binding
+----------------------
+
+Typically when you use breadcrumbs from a framework integration
+breadcrumbs work automatically.  However there are cases where you want to
+do this yourself.  If a context is not bound to the thread breadcrumbs
+will not be recorded.  The thread that created the client (typically the
+main thread) is bound by default.
+
+To bind the context you can use the `activate()` method on it::
+
+    client.context.activate()
+
+To unbind the context you can `deactivate()` it::
+
+    client.context.deactivate()
+
+Alternatively you can use the context with the `with` statement::
+
+    with client.context:
+        ...
+
+The context is automatically deactivated if it's cleared.
diff --git a/docs/usage.rst b/docs/usage.rst
index 1d8f083..28a1c54 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -51,6 +51,37 @@ and `clear()` function that can be used::
         finally:
             client.context.clear()
 
+Additionally starting with Raven 5.14 you can bind the context to the
+current thread to enable crumb support by calling `activate()`.  The
+deactivation happens upon calling `clear()`.  This can also be achieved by
+using the context object with the `with` statement.  This is needed to
+enable breadcrumb capturing.  Framework integrations typically do this
+automatically.
+
+These two examples are equivalent::
+
+    def handle_request(request):
+        client.context.activate()
+        client.context.merge({'user': {
+            'email': request.user.email
+        }})
+        try:
+            ...
+        finally:
+            client.context.clear()
+
+With a context manager::
+
+    def handle_request(request):
+        with client.context:
+            client.context.merge({'user': {
+                'email': request.user.email
+            }})
+            try:
+                ...
+            finally:
+                client.context.clear()
+
 Testing the Client
 ------------------