|
| 1 | +The Design of dd-trace-py |
| 2 | +========================= |
| 3 | + |
| 4 | +Parts of the Library |
| 5 | +-------------------- |
| 6 | + |
| 7 | +When designing a change, one of the first decisions to make is where it should be made. This is an overview |
| 8 | +of the main functional areas of the library. |
| 9 | + |
| 10 | +A **product** is a unit of code within the library that implements functionality specific to a small set of |
| 11 | +customer-facing Datadog products. Examples include the `appsec module <https://github.com/DataDog/dd-trace-py/tree/1.x/ddtrace/appsec>`_ |
| 12 | +implementing functionality for `App and API Protection <https://www.datadoghq.com/product/application-security-management/>`_ |
| 13 | +and the `profiling <https://github.com/DataDog/dd-trace-py/tree/1.x/ddtrace/profiling>`_ module implementing |
| 14 | +functionality for `Continuous Profiling <https://docs.datadoghq.com/profiler/>`_. Ideally it only contains code |
| 15 | +that is specific to the Datadog product being supported, and no code related to Integrations. |
| 16 | + |
| 17 | +An **integration** is one of the modules in the `contrib <https://github.com/DataDog/dd-trace-py/tree/f26a526a6f79870e6e6a21d281f4796a434616bb/ddtrace/contrib>`_ |
| 18 | +directory, hooking our code into the internal logic of a given Python library. Ideally it only contains code |
| 19 | +that is specific to the library being integrated with, and no code related to Products. |
| 20 | + |
| 21 | +The **core** of the library is the abstraction layer that allows Products and Integrations to keep their concerns |
| 22 | +separate. It is implemented in the Python files in the `top level of ddtracepy <https://github.com/DataDog/dd-trace-py/tree/main/ddtrace>`_ |
| 23 | +and in the `internal` module. As an implementation detail, the core logic also happens to directly support |
| 24 | +`Application Performance Monitoring <https://docs.datadoghq.com/tracing/>`_. |
| 25 | + |
| 26 | +Be mindful and intentional about which of these categories your change fits into, and avoid mixing concerns between |
| 27 | +categories. If doing so requires more foundational refactoring or additional layers of abstraction, consider |
| 28 | +opening an issue describing the limitations of the current design. |
| 29 | + |
| 30 | + |
| 31 | +How Autoinstrumentation Works |
| 32 | +----------------------------- |
| 33 | + |
| 34 | +Autoinstrumentation is the feature of dd-trace-py that hooks into application code to facilitate application-level |
| 35 | +product functionality, for example the detailed traces visible in Datadog Application Monitoring. This is an |
| 36 | +overview of the technical implementation of this hooking functionality. |
| 37 | + |
| 38 | +This is the series of steps involved in autoinstrumentation: |
| 39 | + |
| 40 | +1. import bootstrap.sitecustomize, preload, clean up loaded modules, execute preexisting sitecustomizes |
| 41 | +2. start products |
| 42 | +3. set up an import hook for each integration |
| 43 | +4. when an integrated-with module is imported, the import hook calls the contrib's patch(). patch() replaces important functions in the module with transparent wrappers. |
| 44 | +5. These wrappers use the core API to create a tree of ExecutionContext objects. The context tree is traversed |
| 45 | + to generate the data to send to product intake. |
| 46 | + |
| 47 | +Step 1: Bootstrap |
| 48 | +----------------- |
| 49 | + |
| 50 | +The autoinstrumentation entrypoint is `import ddtrace.bootstrap.sitecustomize`. This can be done in user code, either directly or via |
| 51 | +`import ddtrace.auto`, or behind the scenes by `ddtrace-run`. |
| 52 | + |
| 53 | +ddtrace's sitecustomize script's basic goal is to start the Products that the library implements. |
| 54 | +These are subpackages like `_trace`, `profiling`, `debugging`, `appsec`, et cetera. Before starting these Products, |
| 55 | +some setup has to happen, especially the execution of preexisting PEP648 `sitecustomize` scripts to maintain |
| 56 | +user-facing guarantees about the runtime environment in which the application will execute. ddtrace's sitecustomize |
| 57 | +also attempts to "leave no trace" on the runtime environment, especially by unloading all of the modules it has |
| 58 | +used in the course of its setup phases. This helps reduce the possibility that ddtrace will use the same copy of |
| 59 | +an integrated-with module that the application uses, which can lead to undefined behavior. |
| 60 | + |
| 61 | +Step 2: Start Products |
| 62 | +---------------------- |
| 63 | + |
| 64 | +The Products implemented by the library conform to a Product Manager Protocol, which controls common functionality |
| 65 | +like setup, start, and stop. Each enabled Product module is loaded into the Manager instance on import, which happens in |
| 66 | +sitecustomize. In turn, sitecustomize runs the Protocol with `manager.run_protocol()` and later runs additional Product |
| 67 | +setup steps via `preload.post_preload`. Together, these calls comprise the setup of Products that will operate during the |
| 68 | +application's lifetime. |
| 69 | + |
| 70 | +Step 3: Set Up Import Hooks |
| 71 | +--------------------------- |
| 72 | + |
| 73 | +The core functionality set up during step 2 is autoinstrumentation, which is a prerequisite for many of the other Products. |
| 74 | + |
| 75 | +Autoinstrumentation setup involves registering hooks that will execute when a particular module is imported. The list of |
| 76 | +modules whose imports trigger this registration is defined in `_monkey.py`. During this step, each of these modules has an |
| 77 | +import hook registered for it. In the rest of this document, these modules are called "Instrumented Modules". |
| 78 | + |
| 79 | +Note that as of this writing, autoinstrumentation is implemented as a side effect of the `_trace` Product's setup phase. |
| 80 | +In a more abstract sense, autoinstrumentation can function as its own Product, and in the future may be refactored as such. |
| 81 | + |
| 82 | +Step 4: Import Occurs |
| 83 | +--------------------- |
| 84 | + |
| 85 | +The next step of autoinstrumentation happens when the application imports an Instrumented Module. The import triggers the |
| 86 | +import hook that was registered in step 3. The function that the hook executes has the primary goal of calling the `patch()` |
| 87 | +function of the integration module located at `ddtrace.contrib.<integration-name>.patch`. |
| 88 | + |
| 89 | +The goal of an integration's `patch()` function is to invisibly wrap the Instrumented Module with logic that generates the |
| 90 | +data about the module that's necessary for any relevant Products. The most commonly used wrapping approach is based on the |
| 91 | +`wrapt` library, which is included as a vendored dependency in `ddtrace`. Another approach, employed by certain components of the appsec product, involves decompiling the imported module into its abstract syntax tree, modifying it, and then recompiling the module. Inside of the wrappers, it's common for |
| 92 | +integrations to build trees of `core.ExecutionContext` objects that store information about the running application's |
| 93 | +call stack. |
| 94 | + |
| 95 | +Whatever approach is taken, this step only sets up logic that will run later. |
| 96 | + |
| 97 | +Step 5: Application Logic Runs |
| 98 | +------------------------------ |
| 99 | + |
| 100 | +When the application uses the Instrumented Module after importing it, the wrappers created in step 4 are executed. This causes |
| 101 | +data about the running application to be collected in memory, often as a tree of `ExecutionContext` objects. Any Product |
| 102 | +that was started in step 2 may access these data and use them to build a payload to send to the relevant intake endpoints. |
| 103 | +The classic example is the `_trace` Product, which periodically traverses the context tree for the purpose of creating a `Trace` |
| 104 | +object that is subsequently serialized and sent to Datadog to power a flamegraph in the Application Observability product. |
0 commit comments