You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: fix formatting errors in design document (#13648)
## 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)
Copy file name to clipboardExpand all lines: docs/contributing-design.rst
+16-16Lines changed: 16 additions & 16 deletions
Original file line number
Diff line number
Diff line change
@@ -20,7 +20,7 @@ that is specific to the library being integrated with, and no code related to Pr
20
20
21
21
The **core** of the library is the abstraction layer that allows Products and Integrations to keep their concerns
22
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
23
+
and in the ``internal`` module. As an implementation detail, the core logic also happens to directly support
Be mindful and intentional about which of these categories your change fits into, and avoid mixing concerns between
@@ -47,12 +47,12 @@ This is the series of steps involved in autoinstrumentation:
47
47
Step 1: Bootstrap
48
48
-----------------
49
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`.
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
52
53
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
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
56
user-facing guarantees about the runtime environment in which the application will execute. ddtrace's sitecustomize
57
57
also attempts to "leave no trace" on the runtime environment, especially by unloading all of the modules it has
58
58
used in the course of its setup phases. This helps reduce the possibility that ddtrace will use the same copy of
@@ -63,8 +63,8 @@ Step 2: Start Products
63
63
64
64
The Products implemented by the library conform to a Product Manager Protocol, which controls common functionality
65
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
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
68
application's lifetime.
69
69
70
70
Step 3: Set Up Import Hooks
@@ -73,23 +73,23 @@ Step 3: Set Up Import Hooks
73
73
The core functionality set up during step 2 is autoinstrumentation, which is a prerequisite for many of the other Products.
74
74
75
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
76
+
modules whose imports trigger this registration is defined in ``_monkey.py``. During this step, each of these modules has an
77
77
import hook registered for it. In the rest of this document, these modules are called "Instrumented Modules".
78
78
79
-
Note that as of this writing, autoinstrumentation is implemented as a side effect of the `_trace` Product's setup phase.
79
+
Note that as of this writing, autoinstrumentation is implemented as a side effect of the ``_trace`` Product's setup phase.
80
80
In a more abstract sense, autoinstrumentation can function as its own Product, and in the future may be refactored as such.
81
81
82
82
Step 4: Import Occurs
83
83
---------------------
84
84
85
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`.
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
88
89
-
The goal of an integration's `patch()` function is to invisibly wrap the Instrumented Module with logic that generates the
89
+
The goal of an integration's ``patch()`` function is to invisibly wrap the Instrumented Module with logic that generates the
90
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
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
93
call stack.
94
94
95
95
Whatever approach is taken, this step only sets up logic that will run later.
@@ -98,7 +98,7 @@ Step 5: Application Logic Runs
98
98
------------------------------
99
99
100
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
101
+
data about the running application to be collected in memory, often as a tree of ``ExecutionContext`` objects. Any Product
102
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`
103
+
The classic example is the ``_trace`` Product, which periodically traverses the context tree for the purpose of creating a ``Trace``
104
104
object that is subsequently serialized and sent to Datadog to power a flamegraph in the Application Observability product.
0 commit comments