Skip to content

Commit ca14026

Browse files
authored
chore(errortracking): improve error_tracking documentation (#13412)
## Description Improves and corrects documentation in the Error Tracking section of `basic_usage.rst` ## Motivation While writing the Ruby documentation, I found that the python one was missing some precision on the `_INCLUDE` env variable. ## Checklist - [X] PR author has checked that all the criteria below are met - The PR description includes an overview of the change - The PR description articulates the motivation for the change - The change includes tests OR the PR description describes a testing strategy - The PR description notes risks associated with the change, if any - Newly-added code is easy to change - The change follows the [library release note guidelines](https://ddtrace.readthedocs.io/en/stable/releasenotes.html) - The change includes or references documentation updates if necessary - Backport labels are set (if [applicable](https://ddtrace.readthedocs.io/en/latest/contributing.html#backporting)) ## Reviewer Checklist - [x] Reviewer has checked that all the criteria below are met - Title is accurate - All changes are related to the pull request's stated goal - Avoids breaking [API](https://ddtrace.readthedocs.io/en/stable/versioning.html#interfaces) changes - Testing strategy adequately addresses listed risks - Newly-added code is easy to change - Release note makes sense to a user of the library - If necessary, author has acknowledged and discussed the performance implications of this PR as reported in the benchmarks PR comment - Backport labels are set in a manner that is consistent with the [release branch maintenance policy](https://ddtrace.readthedocs.io/en/latest/contributing.html#backporting)
1 parent 355694d commit ca14026

File tree

1 file changed

+14
-8
lines changed

1 file changed

+14
-8
lines changed

docs/basic_usage.rst

Lines changed: 14 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -143,24 +143,28 @@ the ``set_asyncio_event_loop_policy`` method::
143143
Error Tracking
144144
~~~~~~~~~~~~~~
145145

146+
``dd-trace`` can report handled errors. Reported errors will be directly available
147+
in Error Tracking as well as attached as a span event to the span in which they were handled.
148+
146149
Automatic Instrumentation
147150
-------------------------
148151

149152
.. important::
150153

151-
This feature is available on Python3.10+ and ddtrace 3.8.0+
154+
This feature is available on Python3.10+ and ddtrace 3.8.0+.
152155

153156
To enable automatic reporting of handled errors, you can set one of the two environment variables:
154157

155158
- ``DD_ERROR_TRACKING_HANDLED_ERRORS`` = ``user|third_party|all``. Report handled errors of: user code, third party packages or both.
156-
- ``DD_ERROR_TRACKING_HANDLED_ERRORS_INCLUDE`` = ``module1, module2...``. List of modules for which you want to report handled errors.
159+
- ``DD_ERROR_TRACKING_HANDLED_ERRORS_INCLUDE`` = ``module1, module2...``. List of modules for which handled errors will be reported.
157160

158-
You need to specify the full name of the module. For instance, to instrument the module `security` in your `mysite` app, you need to specify
159-
`mysite.security`
161+
To include a module, you need to specify its full name. For instance, to instrument the module ``security`` in your ``mysite`` app,
162+
you need to specify ``mysite.security``. Note that when instrumenting a module, all the submodules are also instrumented.
160163

161-
Handled errors will be report in Error Tracking and attached to spans through span events.
164+
You can also use this variable to choose the third-party packages you want to instrument. For instance, providing ``numpy`` will report
165+
all the errors from the package.
162166

163-
If you are on Python3.10 or Python3.11 and you want to instrument ``__main__`` module, you need to add::
167+
If you are on Python3.10 or Python3.11, and you want to instrument the ``__main__`` module, you need to add::
164168

165169
from ddtrace.errortracking._handled_exceptions.bytecode_reporting import instrument_main
166170

@@ -172,6 +176,10 @@ This code should be added after the functions definitions with handled errors.
172176
Manual Instrumentation
173177
----------------------
174178

179+
.. important::
180+
181+
This feature is available in ddtrace 3.1.1+.
182+
175183
You can report handled errors manually using ``span.record_exception(e)``::
176184

177185
from ddtrace import tracer
@@ -183,8 +191,6 @@ You can report handled errors manually using ``span.record_exception(e)``::
183191
if span:
184192
span.record_exception(e)
185193

186-
This call will create a span event on the span with the error information and will report
187-
the error to Error Tracking.
188194
You can also provide additional attributes using::
189195

190196
span.record_exception(e, {"foo": "bar"})

0 commit comments

Comments
 (0)