Compatibility requirements

This feature is available on Python3.10+ and ddtrace 3.8.0+.

Getting started

Before you begin, make sure you’ve already installed and configured the Agent. You also need to add the tracing library directly in the application to instrument it.

Automatic instrumentation

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

• DD_ERROR_TRACKING_HANDLED_ERRORS. Accepted values are: user, third_party or ,all. This environment variable enables reporting of handled errors respectively from user code, third party packages or both.
• DD_ERROR_TRACKING_HANDLED_ERRORS_INCLUDE = module1, module2.... List the modules from which handled errors should be reported. 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 mysite.security

Handled errors will be reported in Error Tracking and attached to spans through span events.

If you are running Python3.10 or Python3.11 and you want to instrument the __main__ module, you need to add:

from ddtrace.errortracking._handled_exceptions.bytecode_reporting import instrument_main

if __name__ == "__main__":
  instrument_main()

This code should be added after the functions definitions that contain handled errors.

Manual instrumentation

You can report handled errors manually using span.record_exception(e):

from ddtrace import tracer

try:
    raise ValueError("foo")
except ValueError as e:
    span = tracer.current_span()
    if span:
        span.record_exception(e)

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

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