From 5dfc056382d5368c04133ad4869a4289c7a8ac21 Mon Sep 17 00:00:00 2001 From: Munir Abdinur Date: Mon, 6 Jan 2025 18:17:05 -0500 Subject: [PATCH 1/4] update docs --- docs/basic_usage.rst | 32 ++++++-------------------------- 1 file changed, 6 insertions(+), 26 deletions(-) diff --git a/docs/basic_usage.rst b/docs/basic_usage.rst index 4e438e154bb..c910108a73c 100644 --- a/docs/basic_usage.rst +++ b/docs/basic_usage.rst @@ -3,39 +3,19 @@ Basic Usage =========== -Tracing -~~~~~~~ +Automatic Instrumentation +~~~~~~~~~~~~~~~~~~~~~~~~~ ``ddtrace.auto`` ---------------- -To set up instrumentation within your application, call :ref:`import ddtrace.auto` as early as possible +To enable full ddtrace support (library instrumentations, profiling, application security monitoring, dynamic instrumentation, etc.) call :ref:`import ddtrace.auto` as early as possible in your application. This will only work if your application is not running under ``ddtrace-run``. -``patch_all`` -------------- - -For fine-grained control over instrumentation setup, use ``patch_all`` as early as possible -in the application:: - - from ddtrace import patch_all - patch_all() - -To toggle instrumentation for a particular module:: - - from ddtrace import patch_all - patch_all(redis=False, cassandra=False) - -By default all supported libraries will be instrumented when ``patch_all`` is -used. - -**Note:** To ensure that the supported libraries are instrumented properly in -the application, they must be patched *prior* to being imported. So make sure -to call ``patch_all`` *before* importing libraries that are to be instrumented. - -More information about ``patch_all`` is available in the :py:func:`patch_all` API -documentation. +Note: Some Datadog products and instrumentations are disabled by default. Products and instrumentations can be enabled/disable via environment variables, see :ref:`configurations ` page for more details. +Tracing +~~~~~~~ Manual Instrumentation ---------------------- From 754a612e85cb8f2b1f51c8605bf6b574480e8399 Mon Sep 17 00:00:00 2001 From: Munir Abdinur Date: Tue, 7 Jan 2025 10:57:20 -0500 Subject: [PATCH 2/4] Update docs/basic_usage.rst Co-authored-by: Gabriele N. Tornetta --- docs/basic_usage.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/basic_usage.rst b/docs/basic_usage.rst index c910108a73c..d544d1db64c 100644 --- a/docs/basic_usage.rst +++ b/docs/basic_usage.rst @@ -9,7 +9,7 @@ Automatic Instrumentation ``ddtrace.auto`` ---------------- -To enable full ddtrace support (library instrumentations, profiling, application security monitoring, dynamic instrumentation, etc.) call :ref:`import ddtrace.auto` as early as possible +To enable full ddtrace support (library instrumentations, profiling, application security monitoring, dynamic instrumentation, etc.) call :ref:`import ddtrace.auto` as the very first thing in your application. This will only work if your application is not running under ``ddtrace-run``. Note: Some Datadog products and instrumentations are disabled by default. Products and instrumentations can be enabled/disable via environment variables, see :ref:`configurations ` page for more details. From 74eaa5fb31fb6a3302472c226b14695174648097 Mon Sep 17 00:00:00 2001 From: Munir Abdinur Date: Wed, 8 Jan 2025 11:59:03 -0500 Subject: [PATCH 3/4] do not encourage the use of patch_all --- ddtrace/_monkey.py | 2 +- docs/index.rst | 2 +- docs/installation_quickstart.rst | 18 ------------------ 3 files changed, 2 insertions(+), 20 deletions(-) diff --git a/ddtrace/_monkey.py b/ddtrace/_monkey.py index 488211e46b1..954312dcb85 100644 --- a/ddtrace/_monkey.py +++ b/ddtrace/_monkey.py @@ -206,7 +206,7 @@ def on_import(hook): def patch_all(**patch_modules): # type: (bool) -> None - """Automatically patches all available modules. + """Automatically enables ddtrace support for all available modules. In addition to ``patch_modules``, an override can be specified via an environment variable, ``DD_TRACE__ENABLED`` for each module. diff --git a/docs/index.rst b/docs/index.rst index 3d19a4fbf14..23c0cd48a06 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -186,7 +186,7 @@ contacting support. .. [1] Libraries that are automatically instrumented when the :ref:`ddtrace-run` command is used or the ``import ddtrace.auto`` import - is used. Always use ``patch()``, ``patch_all()``, and ``import ddtrace.auto`` as soon + is used. Always use ``import ddtrace.auto`` as soon as possible in your Python entrypoint. .. [2] only the synchronous client diff --git a/docs/installation_quickstart.rst b/docs/installation_quickstart.rst index 4cfc4d670d1..2d879a072b3 100644 --- a/docs/installation_quickstart.rst +++ b/docs/installation_quickstart.rst @@ -59,24 +59,6 @@ When ``ddtrace-run`` cannot be used, a similar start-up behavior can be achieved with the import of ``ddtrace.auto``. This should normally be imported as the first thing during the application start-up. -If neither ``ddtrace-run`` nor ``import ddtrace.auto`` are suitable for your application, then -:py:func:`ddtrace.patch_all` can be used to configure the tracer:: - - from ddtrace import config, patch_all - - config.env = "dev" # the environment the application is in - config.service = "app" # name of your application - config.version = "0.1" # version of your application - patch_all() - - -.. note:: - We recommend the use of ``ddtrace-run`` when possible. If you are importing - ``ddtrace.auto`` as a programmatic replacement for ``ddtrace``, then note - that integrations will take their configuration from the environment - variables. A call to :py:func:`ddtrace.patch_all` cannot be used to disable - an integration at this point. - Service names also need to be configured for libraries that query other services (``requests``, ``grpc``, database libraries, etc). Check out the From 088be845168e67146f894eee16273030b304cb55 Mon Sep 17 00:00:00 2001 From: Munir Abdinur Date: Thu, 9 Jan 2025 14:52:18 -0500 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Emmett Butler <723615+emmettbutler@users.noreply.github.com> --- ddtrace/_monkey.py | 2 +- docs/basic_usage.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/ddtrace/_monkey.py b/ddtrace/_monkey.py index 954312dcb85..eafc747f5ad 100644 --- a/ddtrace/_monkey.py +++ b/ddtrace/_monkey.py @@ -206,7 +206,7 @@ def on_import(hook): def patch_all(**patch_modules): # type: (bool) -> None - """Automatically enables ddtrace support for all available modules. + """enables ddtrace instrumentation of all available supported modules In addition to ``patch_modules``, an override can be specified via an environment variable, ``DD_TRACE__ENABLED`` for each module. diff --git a/docs/basic_usage.rst b/docs/basic_usage.rst index d544d1db64c..2a89150ab31 100644 --- a/docs/basic_usage.rst +++ b/docs/basic_usage.rst @@ -9,7 +9,7 @@ Automatic Instrumentation ``ddtrace.auto`` ---------------- -To enable full ddtrace support (library instrumentations, profiling, application security monitoring, dynamic instrumentation, etc.) call :ref:`import ddtrace.auto` as the very first thing +To enable full ddtrace functionality, including library instrumentations, profiling, application security monitoring, dynamic instrumentation, and more, call :ref:`import ddtrace.auto` as the very first thing in your application. This will only work if your application is not running under ``ddtrace-run``. Note: Some Datadog products and instrumentations are disabled by default. Products and instrumentations can be enabled/disable via environment variables, see :ref:`configurations ` page for more details.