diff options
| -rw-r--r-- | docs/api.rst | 28 | ||||
| -rw-r--r-- | docs/breadcrumbs.rst | 17 |
2 files changed, 35 insertions, 10 deletions
diff --git a/docs/api.rst b/docs/api.rst index 9592b7e..e3c7df5 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -147,12 +147,26 @@ Context This means that you can modify this object over time to feed it with more appropriate information. - .. py:method:: merge(data) + .. py:method:: activate() + + Binds the context to the current thread. This normally happens + automatically on first usage but if the context was deactivated + then this needs to be called again to bind it again. Only if a + context is bound to the thread breadcrumbs will be recorded. + + .. py:method:: deactivate() + + This deactivates the thread binding of the context. In particular + it means that breadcrumbs of the current thread are no longer + recorded to this context. + + .. py:method:: merge(data, activate=True) Performs a merge of the current data in the context and the new - data provided. + data provided. This also automatically activates the context + by default. - .. py:method:: clear() + .. py:method:: clear(deactivate=None) Clears the context. It's important that you make sure to call this when you reuse the thread for something else. For instance @@ -161,3 +175,11 @@ Context Otherwise you run at risk of seeing incorrect information after the first use of the thread. + + Optionally `deactivate` parameter controls if the context should + automatically be deactivated. The default behavior is to + deactivate if the context was not created for the main thread. + + The context can also be used as a context manager. In that case + :py:meth:`activate` is called on enter and :py:meth:`deactivate` is + called on exit. diff --git a/docs/breadcrumbs.rst b/docs/breadcrumbs.rst index 2ce9997..ec304dd 100644 --- a/docs/breadcrumbs.rst +++ b/docs/breadcrumbs.rst @@ -122,13 +122,16 @@ modifications: 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. +Typically breadcrumbs work automatically. Both the raven client itself as +well as the framework integrations configure it to work as good as +possible out of the box. In some advanced scenarios however you might not +see breadcrumbs show up. -To bind the context you can use the `activate()` method on it:: +This can be because the context needs to be bound to a thread. The +default behavior is to automatically bind the context and to unbind it +when the context is cleared. + +To manually bind the context you can use the `activate()` method on it:: client.context.activate() @@ -143,4 +146,4 @@ Alternatively you can use the context with the `with` statement:: The context is automatically deactivated if it's cleared unless it's managed from the main thread. Likewise raven will attempt to auto -activate the client. +activate the client the first time a thread needs it. |