Skip to content

Commit 9fbf472

Browse files
authored
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)
1 parent fae0efb commit 9fbf472

File tree

1 file changed

+16
-16
lines changed

1 file changed

+16
-16
lines changed

docs/contributing-design.rst

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ that is specific to the library being integrated with, and no code related to Pr
2020

2121
The **core** of the library is the abstraction layer that allows Products and Integrations to keep their concerns
2222
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
2424
`Application Performance Monitoring <https://docs.datadoghq.com/tracing/>`_.
2525

2626
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:
4747
Step 1: Bootstrap
4848
-----------------
4949

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``.
5252

5353
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
5656
user-facing guarantees about the runtime environment in which the application will execute. ddtrace's sitecustomize
5757
also attempts to "leave no trace" on the runtime environment, especially by unloading all of the modules it has
5858
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
6363

6464
The Products implemented by the library conform to a Product Manager Protocol, which controls common functionality
6565
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
6868
application's lifetime.
6969

7070
Step 3: Set Up Import Hooks
@@ -73,23 +73,23 @@ Step 3: Set Up Import Hooks
7373
The core functionality set up during step 2 is autoinstrumentation, which is a prerequisite for many of the other Products.
7474

7575
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
7777
import hook registered for it. In the rest of this document, these modules are called "Instrumented Modules".
7878

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.
8080
In a more abstract sense, autoinstrumentation can function as its own Product, and in the future may be refactored as such.
8181

8282
Step 4: Import Occurs
8383
---------------------
8484

8585
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``.
8888

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
9090
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
9393
call stack.
9494

9595
Whatever approach is taken, this step only sets up logic that will run later.
@@ -98,7 +98,7 @@ Step 5: Application Logic Runs
9898
------------------------------
9999

100100
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
102102
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``
104104
object that is subsequently serialized and sent to Datadog to power a flamegraph in the Application Observability product.

0 commit comments

Comments
 (0)