From 8eb3bc558b7d0aa28b4a0aee91a5bdc0096f0a78 Mon Sep 17 00:00:00 2001 From: Emmett Butler Date: Tue, 18 Nov 2025 10:51:38 -0800 Subject: [PATCH 1/6] update upgrade notes for new major version --- .../dd_libraries/python.md | 137 +++++++++--------- 1 file changed, 70 insertions(+), 67 deletions(-) diff --git a/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md b/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md index d7cdc1bf7c158..7485ed9265220 100644 --- a/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md +++ b/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md @@ -64,15 +64,15 @@ The tracing library can be configured through environment variables. This is the For a comprehensive list of configuration options, including Unified Service Tagging, see the [Library Configuration][3] documentation. -## Upgrading to dd-trace-py v3 +## Upgrading to dd-trace-py v4 -Version 3.0.0 of `dd-trace-py` drops support for Python 3.7 and removes previously deprecated APIs. This guide provides steps to help you upgrade your application. +Version 4.0.0 of `dd-trace-py` drops support for Python 3.8 and 32-bit linux. It also removes previously deprecated APIs. This guide provides steps to help you upgrade your application. -With the release of `v3.0.0`, the `2.x` release line is in maintenance mode. Only critical bug fixes should be backported. For more details, see the [versioning support policy][14]. +With the release of `v4.0.0`, the `3.x` release line is in maintenance mode. Only critical bug fixes will be backported. For more details, see the [versioning support policy][14]. ### Step 1: Detect deprecations -To ensure a smooth transition, first upgrade to the latest v2 release (`2.21.0`) and use the following tools to find any deprecated code that will break in v3. +To ensure a smooth transition, first upgrade to the latest v3 release (`3.19.0`) and use the following tools to find any deprecated code that will break in v4. #### In tests @@ -92,7 +92,66 @@ PYTHONWARNINGS=all python app.py ### Step 2: Address breaking changes -After identifying potential issues, review the following breaking changes. Update your code to be compatible with v3 before proceeding with the upgrade. +After identifying potential issues, review the following breaking changes. Update your code to be compatible with v4 before proceeding with the upgrade. + +- Support for ddtrace with Python 3.8 is removed after being deprecated in the 3.0 release line. Use ddtrace 4.x with Python 3.9 or newer. +- 32-bit linux is no longer supported. Please contact us if this blocks upgrading dd-trace-py. +- mongoengine + - Drops support for the `ddtrace.Pin` object with mongoengine. With this change, the ddtrace library no longer directly supports mongoengine. Mongoengine will be supported through the `pymongo` integration. +- CI Visibility + - Removed deprecated entry points for the `pytest_benchmark` and `pytest_bdd` integrations. These plugins are now supported by the regular `pytest` integration. +- dynamic instrumentation + - removed the deprecated `DD_DYNAMIC_INSTRUMENTATION_UPLOAD_FLUSH_INTERVAL` variable. +- exception replay + - removed the deprecated `DD_EXCEPTION_DEBUGGING_ENABLED` variable. +- tracing + - Deprecated methods have been removed + - `Span.set_tag_str` has been removed, use `Span.set_tag` instead. + - `Span.set_struct_tag` has been removed. + - `Span.get_struct_tag` has been removed. + - `Span._pprint` has been removed + - `Span.finished` setter was removed, please use `Span.finish()` method instead. + - `Tracer.on_start_span` method has been removed. + - `Tracer.deregister_on_start_span` method has been removed. + - `ddtrace.trace.Pin` has been removed. + - `Span.finish_with_ancestors` was removed with no replacement. + - Some methods have had their type signatures changed + - `Span.set_tag` typing is now `set_tag(key: str, value: Optional[str] = None) -> None` + - `Span.get_tag` typing is now `get_tag(key: str) -> Optional[str]` + - `Span.set_tags` typing is now `set_tags(tags: dict[str, str]) -> None` + - `Span.get_tags` typing is now `get_tags() -> dict[str, str]` + - `Span.set_metric` typing is now `set_metric(key: str, value: int | float) -> None` + - `Span.get_metric` typing is now `get_metric(key: str) -> Optional[int | float]` + - `Span.set_metrics` typing is now `set_metrics(metrics: Dict[str, int | float]) -> None` + - `Span.get_metrics` typing is now `get_metrics() -> dict[str, int | float]` + - `Span.record_exception`'s `timestamp` and `escaped` parameters are removed +- LLM Observability + - manual instrumentation methods, including `LLMObs.annotate()`, `LLMObs.export_span()`, `LLMObs.submit_evaluation()`, `LLMObs.inject_distributed_headers()`, and `LLMObs.activate_distributed_headers()` now raise exceptions instead of logging. LLM Observability auto-instrumentation is not affected. + - `LLMObs.submit_evaluation_for()` has been removed. Please use `LLMObs.submit_evaluation()` instead for submitting evaluations. To migrate: + - `LLMObs.submit_evaluation_for(...)` users: rename to `LLMObs.submit_evaluation(...)` + - `LLMObs.submit_evaluation_for(...)` users: rename the `span_context` argument to `span`, i.e. `LLMObs.submit_evaluation(span_context={"span_id": ..., "trace_id": ...}, ...)` to `LLMObs.submit_evaluation(span={"span_id": ..., "trace_id": ...}, ...)` +- profiling + - this updates echion (the Python stack sampler) to the latest version, which introduces an experimental faster memory copy function. + - The V1 stack profiler is removed. V2 has been enabled by default since v2.20.0. `DD_PROFILING_STACK_V2_ENABLED` is now removed. +- freezegun + - The deprecated `freezegun` integration is now removed. +- opentracer + - This change removes the deprecated `opentracer` package +- aioredis + - The aioredis integration has been removed. +- google_generativeai + - The `google_generativeai` integration has been removed as the `google_generativeai` library has reached end-of-life. + As an alternative, you can use the recommended `google_genai` library and corresponding integration instead. +- openai + - Streamed chat/completions will no longer have token counts computed using the `tiktoken` library, and instead + will default to having their token counts estimated if not explicitly provided in the OpenAI response object. To guarantee accurate streamed token metrics, set `stream_options={"include_usage": True}` in the OpenAI request. +- django + - This upgrades the default tracing behavior to enable minimal tracing mode by default (``DD_DJANGO_TRACING_MINIMAL`` now defaults to ``true``). Django ORM, cache, and template instrumentation are disabled by default to eliminate duplicate span creation since library integrations for database drivers (psycopg, MySQLdb, sqlite3), cache clients (redis, memcached), template renderers (Jinja2), and other supported libraries continue to be traced. This reduces performance overhead by removing redundant Django-layer instrumentation. To restore all Django instrumentation, set ``DD_DJANGO_TRACING_MINIMAL=false``, or enable individual features using ``DD_DJANGO_INSTRUMENT_DATABASES=true``, ``DD_DJANGO_INSTRUMENT_CACHES=true``, and ``DD_DJANGO_INSTRUMENT_TEMPLATES=true``. + - When ``DD_DJANGO_INSTRUMENT_DATABASES=true`` (default ``false``), database instrumentation now merges Django-specific tags into database driver spans created by supported integrations (psycopg, sqlite3, MySQLdb, etc.) instead of creating duplicate Django database spans. If the database cursor is not already wrapped by a supported integration, Django wraps it and creates a span. This change reduces overhead and duplicate spans while preserving visibility into database operations. +- Other + - This change removes the `ddtrace.settings` package. Environment variables should be used to adjust settings. + - This change removes the deprecated non_active_span parameter to `HttpPropagator.inject` + - This change removes the deprecated environment variable `DEFAULT_RUNTIME_METRICS_INTERVAL`. #### Environment variable changes @@ -101,74 +160,18 @@ The following environment variables have been removed or replaced. Update your c You can use the following command to find all occurrences of these deprecated variables in your codebase: ```sh -git grep -P -e "DD_LLMOBS_APP_NAME" \ - -e "_DD_LLMOBS_EVALUATOR_SAMPLING_RULES" \ - -e "_DD_LLMOBS_EVALUATORS" \ - -e "DD_TRACE_PROPAGATION_STYLE=.*b3 single header" \ - -e "DD_TRACE_SAMPLE_RATE" \ - -e "DD_TRACE_API_VERSION=v0.3" \ - -e "DD_ANALYTICS_ENABLED" \ - -e "DD_TRACE_ANALYTICS_ENABLED" \ - -e "DD_HTTP_CLIENT_TAG_QUERY_STRING" \ - -e "DD_TRACE_SPAN_AGGREGATOR_RLOCK" \ - -e "DD_TRACE_METHODS=.*\[\]" +git grep -P -e "DD_DYNAMIC_INSTRUMENTATION_UPLOAD_FLUSH_INTERVAL" \ +-e "DD_EXCEPTION_DEBUGGING_ENABLED" \ +-e "DD_PROFILING_STACK_V2_ENABLED" \ +-e "DEFAULT_RUNTIME_METRICS_INTERVAL" ``` -| Deprecation | Action Required | -|-------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------| -| `DD_ANALYTICS_ENABLED` | Removed. This is a no-op. See [Ingestion Controls][15] for alternatives. | -| `DD_HTTP_CLIENT_TAG_QUERY_STRING` | Use `DD_TRACE_HTTP_CLIENT_TAG_QUERY_STRING` instead. | -| `DD_LLMOBS_APP_NAME` | Use `DD_LLMOBS_ML_APP` instead. | -| `_DD_LLMOBS_EVALUATOR_SAMPLING_RULES` | Use `DD_LLMOBS_EVALUATOR_SAMPLING_RULES` instead (without the leading underscore). | -| `_DD_LLMOBS_EVALUATORS` | Use `DD_LLMOBS_EVALUATORS` instead (without the leading underscore). | -| `DD_PYTEST_USE_NEW_PLUGIN_BETA` | Removed. The new pytest plugin is the default and is no longer in beta. | -| `DD_TRACE_ANALYTICS_ENABLED` | Removed. This is a no-op. See [Ingestion Controls][15] for alternatives. | -| `DD_TRACE_METHODS` (using `[]` notation) | You must use the `:` notation. For example: `mod.submod:method2;mod.submod:Class.method1`. See the [DD_TRACE_METHODS][16] for details. | -| `DD_TRACE_PROPAGATION_STYLE="b3 single header"` | Use `DD_TRACE_PROPAGATION_STYLE=b3` for identical behavior. | -| `DD_TRACE_SAMPLE_RATE` | Use `DD_TRACE_SAMPLING_RULES` instead. See [User-Defined Rules][17] for details. | -| `DD_TRACE_SPAN_AGGREGATOR_RLOCK` | Removed. This feature has been removed and the variable is a no-op. | -
These changes only apply to dd-trace-py configuration and not the Datadog Agent.
-#### API and interface changes - -The following methods, attributes, and behaviors have been removed or changed. - -##### General - -- **Python 3.7 Support**: Support for Python 3.7 is removed. - -##### Tracing - -- **Multiple Tracer Instances**: Support for multiple `Tracer` instances is removed. You must use the global `ddtrace.tracer` instance. -- `Tracer.configure()`: Deprecated parameters have been removed. Use environment variables to configure Agent connection details (`hostname`, `port`), sampling, and other settings. -- `Span.sampled`: This attribute is removed. Use `span.context.sampling_priority > 0` to check if a span is sampled. -- `ddtrace.opentracer`: The `_dd_tracer` attribute is removed. Use the global `ddtrace.tracer` instead. -- `LLMObs.annotate()`: The `parameters` argument is removed. Use `metadata` instead. -- `choose_matcher()`: Callables and regex patterns are no longer allowed as arguments to `ddtrace.tracer.sampler.rules[].choose_matcher`. You must pass a string. - -##### LLM Observability - -- **OpenAI and Langchain**: Support for OpenAI v0.x and Langchain v0.0.x is dropped. - -##### CI Visibility - -- The new pytest plugin is the default. -- Module, suite, and test names are parsed from `item.nodeid`. -- Test names for class-based tests include the class name (for example, `TestClass::test_method`). -- Test skipping is performed at the suite level. - -### Step 3: Upgrade the library - -After you have updated your code to address the breaking changes, you can upgrade to the latest v3 release. - -```sh -pip install --upgrade ddtrace -``` -#### Python 3.13 compatibility +#### Python 3.14 compatibility -Full support for Python 3.13 is in active development. While the core tracing library is compatible, some integrations may not be fully tested or supported in the latest version. +Full support for Python 3.14 is in active development. While the core tracing library is compatible, some integrations may not be fully tested or supported in the latest version. For the most current compatibility details for a specific integration, see the library's [latest release notes][19]. From 8cf81577a508cb8e10977d1e107396fb175ba573 Mon Sep 17 00:00:00 2001 From: Emmett Butler <723615+emmettbutler@users.noreply.github.com> Date: Tue, 18 Nov 2025 12:09:02 -0800 Subject: [PATCH 2/6] Update content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md Co-authored-by: Brett Langdon --- .../automatic_instrumentation/dd_libraries/python.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md b/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md index 7485ed9265220..7d8a82e9f6451 100644 --- a/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md +++ b/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md @@ -94,6 +94,7 @@ PYTHONWARNINGS=all python app.py After identifying potential issues, review the following breaking changes. Update your code to be compatible with v4 before proceeding with the upgrade. +- Starting with ddtrace v4.0.0, Datadog Agent v7.63.0 or newer is required. - Support for ddtrace with Python 3.8 is removed after being deprecated in the 3.0 release line. Use ddtrace 4.x with Python 3.9 or newer. - 32-bit linux is no longer supported. Please contact us if this blocks upgrading dd-trace-py. - mongoengine From 13268aa9c18071457cdd1310661c7613572f5390 Mon Sep 17 00:00:00 2001 From: Emmett Butler Date: Tue, 18 Nov 2025 13:32:03 -0800 Subject: [PATCH 3/6] vale warnings --- .../dd_libraries/python.md | 44 +++++++++---------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md b/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md index 7d8a82e9f6451..7017c5fca1915 100644 --- a/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md +++ b/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md @@ -68,11 +68,11 @@ For a comprehensive list of configuration options, including Unified Service Tag Version 4.0.0 of `dd-trace-py` drops support for Python 3.8 and 32-bit linux. It also removes previously deprecated APIs. This guide provides steps to help you upgrade your application. -With the release of `v4.0.0`, the `3.x` release line is in maintenance mode. Only critical bug fixes will be backported. For more details, see the [versioning support policy][14]. +With the release of `v4.0.0`, the `3.x` release line is in maintenance mode. Only critical bug fixes are backported. For more details, see the [versioning support policy][14]. ### Step 1: Detect deprecations -To ensure a smooth transition, first upgrade to the latest v3 release (`3.19.0`) and use the following tools to find any deprecated code that will break in v4. +To ensure a smooth transition, first upgrade to the latest v3 release (`3.19.0`) and use the following tools to find any deprecated code that breaks in v4. #### In tests @@ -96,11 +96,11 @@ After identifying potential issues, review the following breaking changes. Updat - Starting with ddtrace v4.0.0, Datadog Agent v7.63.0 or newer is required. - Support for ddtrace with Python 3.8 is removed after being deprecated in the 3.0 release line. Use ddtrace 4.x with Python 3.9 or newer. -- 32-bit linux is no longer supported. Please contact us if this blocks upgrading dd-trace-py. +- 32-bit linux is no longer supported. Contact support@datadoghq.com if this blocks upgrading dd-trace-py. - mongoengine - - Drops support for the `ddtrace.Pin` object with mongoengine. With this change, the ddtrace library no longer directly supports mongoengine. Mongoengine will be supported through the `pymongo` integration. + - Drops support for the `ddtrace.Pin` object with mongoengine. With this change, the ddtrace library no longer directly supports mongoengine. Mongoengine is supported through the `pymongo` integration. - CI Visibility - - Removed deprecated entry points for the `pytest_benchmark` and `pytest_bdd` integrations. These plugins are now supported by the regular `pytest` integration. + - Removed deprecated entry points for the `pytest_benchmark` and `pytest_bdd` integrations. These plugins are supported by the regular `pytest` integration. - dynamic instrumentation - removed the deprecated `DD_DYNAMIC_INSTRUMENTATION_UPLOAD_FLUSH_INTERVAL` variable. - exception replay @@ -111,31 +111,31 @@ After identifying potential issues, review the following breaking changes. Updat - `Span.set_struct_tag` has been removed. - `Span.get_struct_tag` has been removed. - `Span._pprint` has been removed - - `Span.finished` setter was removed, please use `Span.finish()` method instead. + - `Span.finished` setter was removed, use `Span.finish()` method instead. - `Tracer.on_start_span` method has been removed. - `Tracer.deregister_on_start_span` method has been removed. - `ddtrace.trace.Pin` has been removed. - `Span.finish_with_ancestors` was removed with no replacement. - Some methods have had their type signatures changed - - `Span.set_tag` typing is now `set_tag(key: str, value: Optional[str] = None) -> None` - - `Span.get_tag` typing is now `get_tag(key: str) -> Optional[str]` - - `Span.set_tags` typing is now `set_tags(tags: dict[str, str]) -> None` - - `Span.get_tags` typing is now `get_tags() -> dict[str, str]` - - `Span.set_metric` typing is now `set_metric(key: str, value: int | float) -> None` - - `Span.get_metric` typing is now `get_metric(key: str) -> Optional[int | float]` - - `Span.set_metrics` typing is now `set_metrics(metrics: Dict[str, int | float]) -> None` - - `Span.get_metrics` typing is now `get_metrics() -> dict[str, int | float]` + - `Span.set_tag` typing is `set_tag(key: str, value: Optional[str] = None) -> None` + - `Span.get_tag` typing is `get_tag(key: str) -> Optional[str]` + - `Span.set_tags` typing is `set_tags(tags: dict[str, str]) -> None` + - `Span.get_tags` typing is `get_tags() -> dict[str, str]` + - `Span.set_metric` typing is `set_metric(key: str, value: int | float) -> None` + - `Span.get_metric` typing is `get_metric(key: str) -> Optional[int | float]` + - `Span.set_metrics` typing is `set_metrics(metrics: Dict[str, int | float]) -> None` + - `Span.get_metrics` typing is `get_metrics() -> dict[str, int | float]` - `Span.record_exception`'s `timestamp` and `escaped` parameters are removed - LLM Observability - - manual instrumentation methods, including `LLMObs.annotate()`, `LLMObs.export_span()`, `LLMObs.submit_evaluation()`, `LLMObs.inject_distributed_headers()`, and `LLMObs.activate_distributed_headers()` now raise exceptions instead of logging. LLM Observability auto-instrumentation is not affected. - - `LLMObs.submit_evaluation_for()` has been removed. Please use `LLMObs.submit_evaluation()` instead for submitting evaluations. To migrate: + - manual instrumentation methods, including `LLMObs.annotate()`, `LLMObs.export_span()`, `LLMObs.submit_evaluation()`, `LLMObs.inject_distributed_headers()`, and `LLMObs.activate_distributed_headers()` raise exceptions instead of logging. LLM Observability auto-instrumentation is not affected. + - `LLMObs.submit_evaluation_for()` has been removed. Use `LLMObs.submit_evaluation()` instead for submitting evaluations. To migrate: - `LLMObs.submit_evaluation_for(...)` users: rename to `LLMObs.submit_evaluation(...)` - `LLMObs.submit_evaluation_for(...)` users: rename the `span_context` argument to `span`, i.e. `LLMObs.submit_evaluation(span_context={"span_id": ..., "trace_id": ...}, ...)` to `LLMObs.submit_evaluation(span={"span_id": ..., "trace_id": ...}, ...)` - profiling - this updates echion (the Python stack sampler) to the latest version, which introduces an experimental faster memory copy function. - - The V1 stack profiler is removed. V2 has been enabled by default since v2.20.0. `DD_PROFILING_STACK_V2_ENABLED` is now removed. + - The V1 stack profiler is removed. V2 has been enabled by default since v2.20.0. `DD_PROFILING_STACK_V2_ENABLED` is removed. - freezegun - - The deprecated `freezegun` integration is now removed. + - The deprecated `freezegun` integration is removed. - opentracer - This change removes the deprecated `opentracer` package - aioredis @@ -144,11 +144,11 @@ After identifying potential issues, review the following breaking changes. Updat - The `google_generativeai` integration has been removed as the `google_generativeai` library has reached end-of-life. As an alternative, you can use the recommended `google_genai` library and corresponding integration instead. - openai - - Streamed chat/completions will no longer have token counts computed using the `tiktoken` library, and instead - will default to having their token counts estimated if not explicitly provided in the OpenAI response object. To guarantee accurate streamed token metrics, set `stream_options={"include_usage": True}` in the OpenAI request. + - Streamed chat/completions no longer have token counts computed using the `tiktoken` library, and instead + default to having their token counts estimated if not explicitly provided in the OpenAI response object. To guarantee accurate streamed token metrics, set `stream_options={"include_usage": True}` in the OpenAI request. - django - - This upgrades the default tracing behavior to enable minimal tracing mode by default (``DD_DJANGO_TRACING_MINIMAL`` now defaults to ``true``). Django ORM, cache, and template instrumentation are disabled by default to eliminate duplicate span creation since library integrations for database drivers (psycopg, MySQLdb, sqlite3), cache clients (redis, memcached), template renderers (Jinja2), and other supported libraries continue to be traced. This reduces performance overhead by removing redundant Django-layer instrumentation. To restore all Django instrumentation, set ``DD_DJANGO_TRACING_MINIMAL=false``, or enable individual features using ``DD_DJANGO_INSTRUMENT_DATABASES=true``, ``DD_DJANGO_INSTRUMENT_CACHES=true``, and ``DD_DJANGO_INSTRUMENT_TEMPLATES=true``. - - When ``DD_DJANGO_INSTRUMENT_DATABASES=true`` (default ``false``), database instrumentation now merges Django-specific tags into database driver spans created by supported integrations (psycopg, sqlite3, MySQLdb, etc.) instead of creating duplicate Django database spans. If the database cursor is not already wrapped by a supported integration, Django wraps it and creates a span. This change reduces overhead and duplicate spans while preserving visibility into database operations. + - This upgrades the default tracing behavior to enable minimal tracing mode by default (``DD_DJANGO_TRACING_MINIMAL`` defaults to ``true``). Django ORM, cache, and template instrumentation are disabled by default to eliminate duplicate span creation since library integrations for database drivers (psycopg, MySQLdb, sqlite3), cache clients (redis, memcached), template renderers (Jinja2), and other supported libraries continue to be traced. This reduces performance overhead by removing redundant Django-layer instrumentation. To restore all Django instrumentation, set ``DD_DJANGO_TRACING_MINIMAL=false``, or enable individual features using ``DD_DJANGO_INSTRUMENT_DATABASES=true``, ``DD_DJANGO_INSTRUMENT_CACHES=true``, and ``DD_DJANGO_INSTRUMENT_TEMPLATES=true``. + - When ``DD_DJANGO_INSTRUMENT_DATABASES=true`` (default ``false``), database instrumentation merges Django-specific tags into database driver spans created by supported integrations (psycopg, sqlite3, MySQLdb, etc.) instead of creating duplicate Django database spans. If the database cursor is not already wrapped by a supported integration, Django wraps it and creates a span. This change reduces overhead and duplicate spans while preserving visibility into database operations. - Other - This change removes the `ddtrace.settings` package. Environment variables should be used to adjust settings. - This change removes the deprecated non_active_span parameter to `HttpPropagator.inject` From d91055c6b9991d3b1edfa463eb15c43c095c08b9 Mon Sep 17 00:00:00 2001 From: Emmett Butler Date: Tue, 18 Nov 2025 13:44:57 -0800 Subject: [PATCH 4/6] nicer formatting; dont erase v3 notes --- .../dd_libraries/python.md | 168 ++++++++++++++++-- 1 file changed, 150 insertions(+), 18 deletions(-) diff --git a/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md b/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md index 7017c5fca1915..63050c3e4b279 100644 --- a/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md +++ b/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md @@ -94,18 +94,30 @@ PYTHONWARNINGS=all python app.py After identifying potential issues, review the following breaking changes. Update your code to be compatible with v4 before proceeding with the upgrade. +##### General + - Starting with ddtrace v4.0.0, Datadog Agent v7.63.0 or newer is required. - Support for ddtrace with Python 3.8 is removed after being deprecated in the 3.0 release line. Use ddtrace 4.x with Python 3.9 or newer. - 32-bit linux is no longer supported. Contact support@datadoghq.com if this blocks upgrading dd-trace-py. -- mongoengine + +##### mongoengine + - Drops support for the `ddtrace.Pin` object with mongoengine. With this change, the ddtrace library no longer directly supports mongoengine. Mongoengine is supported through the `pymongo` integration. -- CI Visibility + +##### CI Visibility + - Removed deprecated entry points for the `pytest_benchmark` and `pytest_bdd` integrations. These plugins are supported by the regular `pytest` integration. -- dynamic instrumentation + +##### Dynamic Instrumentation + - removed the deprecated `DD_DYNAMIC_INSTRUMENTATION_UPLOAD_FLUSH_INTERVAL` variable. -- exception replay + +##### Exception Replay + - removed the deprecated `DD_EXCEPTION_DEBUGGING_ENABLED` variable. -- tracing + +##### Tracing + - Deprecated methods have been removed - `Span.set_tag_str` has been removed, use `Span.set_tag` instead. - `Span.set_struct_tag` has been removed. @@ -126,33 +138,45 @@ After identifying potential issues, review the following breaking changes. Updat - `Span.set_metrics` typing is `set_metrics(metrics: Dict[str, int | float]) -> None` - `Span.get_metrics` typing is `get_metrics() -> dict[str, int | float]` - `Span.record_exception`'s `timestamp` and `escaped` parameters are removed -- LLM Observability + - This change removes the deprecated environment variable `DEFAULT_RUNTIME_METRICS_INTERVAL`. + +##### LLM Observability + - manual instrumentation methods, including `LLMObs.annotate()`, `LLMObs.export_span()`, `LLMObs.submit_evaluation()`, `LLMObs.inject_distributed_headers()`, and `LLMObs.activate_distributed_headers()` raise exceptions instead of logging. LLM Observability auto-instrumentation is not affected. - `LLMObs.submit_evaluation_for()` has been removed. Use `LLMObs.submit_evaluation()` instead for submitting evaluations. To migrate: - `LLMObs.submit_evaluation_for(...)` users: rename to `LLMObs.submit_evaluation(...)` - `LLMObs.submit_evaluation_for(...)` users: rename the `span_context` argument to `span`, i.e. `LLMObs.submit_evaluation(span_context={"span_id": ..., "trace_id": ...}, ...)` to `LLMObs.submit_evaluation(span={"span_id": ..., "trace_id": ...}, ...)` -- profiling + +##### Profiling + - this updates echion (the Python stack sampler) to the latest version, which introduces an experimental faster memory copy function. - The V1 stack profiler is removed. V2 has been enabled by default since v2.20.0. `DD_PROFILING_STACK_V2_ENABLED` is removed. -- freezegun + +##### Removed Packages + - The deprecated `freezegun` integration is removed. -- opentracer - - This change removes the deprecated `opentracer` package -- aioredis - The aioredis integration has been removed. -- google_generativeai + - This change removes the deprecated `opentracer` package + - This change removes the `ddtrace.settings` package. Environment variables should be used to adjust settings. + +##### Google Generative AI + - The `google_generativeai` integration has been removed as the `google_generativeai` library has reached end-of-life. As an alternative, you can use the recommended `google_genai` library and corresponding integration instead. -- openai + +##### OpenAI + - Streamed chat/completions no longer have token counts computed using the `tiktoken` library, and instead default to having their token counts estimated if not explicitly provided in the OpenAI response object. To guarantee accurate streamed token metrics, set `stream_options={"include_usage": True}` in the OpenAI request. -- django + +##### Django + - This upgrades the default tracing behavior to enable minimal tracing mode by default (``DD_DJANGO_TRACING_MINIMAL`` defaults to ``true``). Django ORM, cache, and template instrumentation are disabled by default to eliminate duplicate span creation since library integrations for database drivers (psycopg, MySQLdb, sqlite3), cache clients (redis, memcached), template renderers (Jinja2), and other supported libraries continue to be traced. This reduces performance overhead by removing redundant Django-layer instrumentation. To restore all Django instrumentation, set ``DD_DJANGO_TRACING_MINIMAL=false``, or enable individual features using ``DD_DJANGO_INSTRUMENT_DATABASES=true``, ``DD_DJANGO_INSTRUMENT_CACHES=true``, and ``DD_DJANGO_INSTRUMENT_TEMPLATES=true``. - When ``DD_DJANGO_INSTRUMENT_DATABASES=true`` (default ``false``), database instrumentation merges Django-specific tags into database driver spans created by supported integrations (psycopg, sqlite3, MySQLdb, etc.) instead of creating duplicate Django database spans. If the database cursor is not already wrapped by a supported integration, Django wraps it and creates a span. This change reduces overhead and duplicate spans while preserving visibility into database operations. -- Other - - This change removes the `ddtrace.settings` package. Environment variables should be used to adjust settings. - - This change removes the deprecated non_active_span parameter to `HttpPropagator.inject` - - This change removes the deprecated environment variable `DEFAULT_RUNTIME_METRICS_INTERVAL`. + +##### Propagation + + - This change removes the deprecated `non_active_span` parameter to `HttpPropagator.inject` #### Environment variable changes @@ -176,6 +200,114 @@ Full support for Python 3.14 is in active development. While the core tracing li For the most current compatibility details for a specific integration, see the library's [latest release notes][19]. +## Upgrading to dd-trace-py v3 + +Version 3.0.0 of `dd-trace-py` drops support for Python 3.7 and removes previously deprecated APIs. This guide provides steps to help you upgrade your application. + +With the release of `v3.0.0`, the `2.x` release line is in maintenance mode. Only critical bug fixes should be backported. For more details, see the [versioning support policy][14]. + +### Step 1: Detect deprecations + +To ensure a smooth transition, first upgrade to the latest v2 release (`2.21.0`) and use the following tools to find any deprecated code that will break in v3. + +#### In tests + +Run `pytest` with warnings enabled as errors to identify areas in your test suite that need updates: + +```sh +pytest -W "error::ddtrace.DDTraceDeprecationWarning" tests.py +``` + +#### In applications + +Set the`PYTHONWARNINGS` environment variable to surface deprecation warnings when you run your application. + +```sh +PYTHONWARNINGS=all python app.py +``` + +### Step 2: Address breaking changes + +After identifying potential issues, review the following breaking changes. Update your code to be compatible with v3 before proceeding with the upgrade. + +#### Environment variable changes + +The following environment variables have been removed or replaced. Update your configuration with the new variables where applicable. + +You can use the following command to find all occurrences of these deprecated variables in your codebase: + +```sh +git grep -P -e "DD_LLMOBS_APP_NAME" \ + -e "_DD_LLMOBS_EVALUATOR_SAMPLING_RULES" \ + -e "_DD_LLMOBS_EVALUATORS" \ + -e "DD_TRACE_PROPAGATION_STYLE=.*b3 single header" \ + -e "DD_TRACE_SAMPLE_RATE" \ + -e "DD_TRACE_API_VERSION=v0.3" \ + -e "DD_ANALYTICS_ENABLED" \ + -e "DD_TRACE_ANALYTICS_ENABLED" \ + -e "DD_HTTP_CLIENT_TAG_QUERY_STRING" \ + -e "DD_TRACE_SPAN_AGGREGATOR_RLOCK" \ + -e "DD_TRACE_METHODS=.*\[\]" +``` + +| Deprecation | Action Required | +|-------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------| +| `DD_ANALYTICS_ENABLED` | Removed. This is a no-op. See [Ingestion Controls][15] for alternatives. | +| `DD_HTTP_CLIENT_TAG_QUERY_STRING` | Use `DD_TRACE_HTTP_CLIENT_TAG_QUERY_STRING` instead. | +| `DD_LLMOBS_APP_NAME` | Use `DD_LLMOBS_ML_APP` instead. | +| `_DD_LLMOBS_EVALUATOR_SAMPLING_RULES` | Use `DD_LLMOBS_EVALUATOR_SAMPLING_RULES` instead (without the leading underscore). | +| `_DD_LLMOBS_EVALUATORS` | Use `DD_LLMOBS_EVALUATORS` instead (without the leading underscore). | +| `DD_PYTEST_USE_NEW_PLUGIN_BETA` | Removed. The new pytest plugin is the default and is no longer in beta. | +| `DD_TRACE_ANALYTICS_ENABLED` | Removed. This is a no-op. See [Ingestion Controls][15] for alternatives. | +| `DD_TRACE_METHODS` (using `[]` notation) | You must use the `:` notation. For example: `mod.submod:method2;mod.submod:Class.method1`. See the [DD_TRACE_METHODS][16] for details. | +| `DD_TRACE_PROPAGATION_STYLE="b3 single header"` | Use `DD_TRACE_PROPAGATION_STYLE=b3` for identical behavior. | +| `DD_TRACE_SAMPLE_RATE` | Use `DD_TRACE_SAMPLING_RULES` instead. See [User-Defined Rules][17] for details. | +| `DD_TRACE_SPAN_AGGREGATOR_RLOCK` | Removed. This feature has been removed and the variable is a no-op. | + +
These changes only apply to dd-trace-py configuration and not the Datadog Agent.
+ +#### API and interface changes + +The following methods, attributes, and behaviors have been removed or changed. + +##### General + +- **Python 3.7 Support**: Support for Python 3.7 is removed. + +##### Tracing + +- **Multiple Tracer Instances**: Support for multiple `Tracer` instances is removed. You must use the global `ddtrace.tracer` instance. +- `Tracer.configure()`: Deprecated parameters have been removed. Use environment variables to configure Agent connection details (`hostname`, `port`), sampling, and other settings. +- `Span.sampled`: This attribute is removed. Use `span.context.sampling_priority > 0` to check if a span is sampled. +- `ddtrace.opentracer`: The `_dd_tracer` attribute is removed. Use the global `ddtrace.tracer` instead. +- `LLMObs.annotate()`: The `parameters` argument is removed. Use `metadata` instead. +- `choose_matcher()`: Callables and regex patterns are no longer allowed as arguments to `ddtrace.tracer.sampler.rules[].choose_matcher`. You must pass a string. + +##### LLM Observability + +- **OpenAI and Langchain**: Support for OpenAI v0.x and Langchain v0.0.x is dropped. + +##### CI Visibility + +- The new pytest plugin is the default. +- Module, suite, and test names are parsed from `item.nodeid`. +- Test names for class-based tests include the class name (for example, `TestClass::test_method`). +- Test skipping is performed at the suite level. + +### Step 3: Upgrade the library + +After you have updated your code to address the breaking changes, you can upgrade to the latest v3 release. + +```sh +pip install --upgrade ddtrace +``` + +#### Python 3.13 compatibility + +Full support for Python 3.13 is in active development. While the core tracing library is compatible, some integrations may not be fully tested or supported in the latest version. + +For the most current compatibility details for a specific integration, see the library's [latest release notes][19]. + ## Further reading {{< partial name="whats-next/whats-next.html" >}} From 91d7f56095db2345a29503edaf6d130be4205170 Mon Sep 17 00:00:00 2001 From: Emmett Butler Date: Tue, 18 Nov 2025 13:46:03 -0800 Subject: [PATCH 5/6] better pythonwarnings setting --- .../automatic_instrumentation/dd_libraries/python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md b/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md index 63050c3e4b279..12245d551e511 100644 --- a/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md +++ b/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md @@ -87,7 +87,7 @@ pytest -W "error::ddtrace.DDTraceDeprecationWarning" tests.py Set the`PYTHONWARNINGS` environment variable to surface deprecation warnings when you run your application. ```sh -PYTHONWARNINGS=all python app.py +PYTHONWARNINGS=error::ddtrace.DDTraceDeprecationWarning python app.py ``` ### Step 2: Address breaking changes From 005f987796c052cf5730fa0bda6b0876f7b837e4 Mon Sep 17 00:00:00 2001 From: Brett Blue Date: Tue, 18 Nov 2025 21:32:37 -0700 Subject: [PATCH 6/6] Move migration content to new file; edit v4 migration content. --- .../dd_libraries/migrate/python/v3.md | 124 +++++++++ .../dd_libraries/migrate/python/v4.md | 150 +++++++++++ .../dd_libraries/python.md | 243 +----------------- 3 files changed, 281 insertions(+), 236 deletions(-) create mode 100644 content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/migrate/python/v3.md create mode 100644 content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/migrate/python/v4.md diff --git a/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/migrate/python/v3.md b/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/migrate/python/v3.md new file mode 100644 index 0000000000000..2bbbce16524af --- /dev/null +++ b/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/migrate/python/v3.md @@ -0,0 +1,124 @@ +--- +title: Migrate to dd-trace-py v3 +description: 'Upgrade your Python tracer from v2 to v3.' +further_reading: + - link: 'https://github.com/DataDog/dd-trace-py/releases' + tag: "GitHub" + text: 'Release Notes' + - link: 'tracing/trace_collection/dd_libraries/python' + tag: 'Documentation' + text: 'Python Tracing Setup' +--- + +Version 3.0.0 of `dd-trace-py` drops support for Python 3.7 and removes previously deprecated APIs. This guide provides steps to help you upgrade your application. + +With the release of `v3.0.0`, the `2.x` release line is in maintenance mode. Only critical bug fixes should be backported. For more details, see the [versioning support policy][14]. + +### Step 1: Detect deprecations + +To ensure a smooth transition, first upgrade to the latest v2 release (`2.21.0`) and use the following tools to find any deprecated code that will break in v3. + +#### In tests + +Run `pytest` with warnings enabled as errors to identify areas in your test suite that need updates: + +```sh +pytest -W "error::ddtrace.DDTraceDeprecationWarning" tests.py +``` + +#### In applications + +Set the`PYTHONWARNINGS` environment variable to surface deprecation warnings when you run your application. + +```sh +PYTHONWARNINGS=all python app.py +``` + +### Step 2: Address breaking changes + +After identifying potential issues, review the following breaking changes. Update your code to be compatible with v3 before proceeding with the upgrade. + +#### Environment variable changes + +The following environment variables have been removed or replaced. Update your configuration with the new variables where applicable. + +You can use the following command to find all occurrences of these deprecated variables in your codebase: + +```sh +git grep -P -e "DD_LLMOBS_APP_NAME" \ + -e "_DD_LLMOBS_EVALUATOR_SAMPLING_RULES" \ + -e "_DD_LLMOBS_EVALUATORS" \ + -e "DD_TRACE_PROPAGATION_STYLE=.*b3 single header" \ + -e "DD_TRACE_SAMPLE_RATE" \ + -e "DD_TRACE_API_VERSION=v0.3" \ + -e "DD_ANALYTICS_ENABLED" \ + -e "DD_TRACE_ANALYTICS_ENABLED" \ + -e "DD_HTTP_CLIENT_TAG_QUERY_STRING" \ + -e "DD_TRACE_SPAN_AGGREGATOR_RLOCK" \ + -e "DD_TRACE_METHODS=.*\[\]" +``` + +| Deprecation | Action Required | +|-------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------| +| `DD_ANALYTICS_ENABLED` | Removed. This is a no-op. See [Ingestion Controls][15] for alternatives. | +| `DD_HTTP_CLIENT_TAG_QUERY_STRING` | Use `DD_TRACE_HTTP_CLIENT_TAG_QUERY_STRING` instead. | +| `DD_LLMOBS_APP_NAME` | Use `DD_LLMOBS_ML_APP` instead. | +| `_DD_LLMOBS_EVALUATOR_SAMPLING_RULES` | Use `DD_LLMOBS_EVALUATOR_SAMPLING_RULES` instead (without the leading underscore). | +| `_DD_LLMOBS_EVALUATORS` | Use `DD_LLMOBS_EVALUATORS` instead (without the leading underscore). | +| `DD_PYTEST_USE_NEW_PLUGIN_BETA` | Removed. The new pytest plugin is the default and is no longer in beta. | +| `DD_TRACE_ANALYTICS_ENABLED` | Removed. This is a no-op. See [Ingestion Controls][15] for alternatives. | +| `DD_TRACE_METHODS` (using `[]` notation) | You must use the `:` notation. For example: `mod.submod:method2;mod.submod:Class.method1`. See the [DD_TRACE_METHODS][16] for details. | +| `DD_TRACE_PROPAGATION_STYLE="b3 single header"` | Use `DD_TRACE_PROPAGATION_STYLE=b3` for identical behavior. | +| `DD_TRACE_SAMPLE_RATE` | Use `DD_TRACE_SAMPLING_RULES` instead. See [User-Defined Rules][17] for details. | +| `DD_TRACE_SPAN_AGGREGATOR_RLOCK` | Removed. This feature has been removed and the variable is a no-op. | + +
These changes only apply to dd-trace-py configuration and not the Datadog Agent.
+ +#### API and interface changes + +The following methods, attributes, and behaviors have been removed or changed. + +##### General + +- **Python 3.7 Support**: Support for Python 3.7 is removed. + +##### Tracing + +- **Multiple Tracer Instances**: Support for multiple `Tracer` instances is removed. You must use the global `ddtrace.tracer` instance. +- `Tracer.configure()`: Deprecated parameters have been removed. Use environment variables to configure Agent connection details (`hostname`, `port`), sampling, and other settings. +- `Span.sampled`: This attribute is removed. Use `span.context.sampling_priority > 0` to check if a span is sampled. +- `ddtrace.opentracer`: The `_dd_tracer` attribute is removed. Use the global `ddtrace.tracer` instead. +- `LLMObs.annotate()`: The `parameters` argument is removed. Use `metadata` instead. +- `choose_matcher()`: Callables and regex patterns are no longer allowed as arguments to `ddtrace.tracer.sampler.rules[].choose_matcher`. You must pass a string. + +##### LLM Observability + +- **OpenAI and Langchain**: Support for OpenAI v0.x and Langchain v0.0.x is dropped. + +##### CI Visibility + +- The new pytest plugin is the default. +- Module, suite, and test names are parsed from `item.nodeid`. +- Test names for class-based tests include the class name (for example, `TestClass::test_method`). +- Test skipping is performed at the suite level. + +### Step 3: Upgrade the library + +After you have updated your code to address the breaking changes, you can upgrade to the latest v3 release. + +```sh +pip install --upgrade ddtrace +``` + +#### Python 3.13 compatibility + +Full support for Python 3.13 is in active development. While the core tracing library is compatible, some integrations may not be fully tested or supported in the latest version. + +For the most current compatibility details for a specific integration, see the library's [latest release notes][19]. + + +[14]: /tracing/trace_collection/compatibility/python/#releases +[15]: /tracing/trace_pipeline/ingestion_mechanisms/?tab=python +[16]: https://ddtrace.readthedocs.io/en/stable/configuration.html?highlight=dd_trace_methods#DD_TRACE_METHODS +[17]: /tracing/trace_pipeline/ingestion_mechanisms/?tab=python#in-tracing-libraries-user-defined-rules +[19]: https://github.com/DataDog/dd-trace-py/releases \ No newline at end of file diff --git a/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/migrate/python/v4.md b/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/migrate/python/v4.md new file mode 100644 index 0000000000000..8e00d8b566d3b --- /dev/null +++ b/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/migrate/python/v4.md @@ -0,0 +1,150 @@ +--- +title: Migrate to dd-trace-py v4 +description: 'Upgrade your Python tracer from v3 to v4.' +further_reading: + - link: 'https://github.com/DataDog/dd-trace-py/releases' + tag: "GitHub" + text: 'Release Notes' + - link: 'tracing/trace_collection/dd_libraries/python' + tag: 'Documentation' + text: 'Python Tracing Setup' +--- + +## Overview + +Version 4.0.0 of `dd-trace-py` drops support for older Python versions, removes deprecated APIs, and creates new default behaviors for frameworks such as Django. + +The `3.x` release line is now in maintenance mode; only critical bug fixes are backported. + +## Prerequisites + +Ensure your environment meets the following requirements: + +- **Python Version:** Python 3.9 or newer (Python 3.8 support is removed). +- **Datadog Agent:** v7.63.0 or newer. +- **OS:** 64-bit Linux (32-bit Linux support is removed). + +## Step 1: Detect deprecations + +To ensure a smooth transition, upgrade to the latest v3 release (`3.19.0`) and use the following tools to detect deprecated code. + +### In tests + +Run `pytest` with warnings enabled as errors to identify necessary updates in your test suite: + +```bash +pytest -W "error::ddtrace.DDTraceDeprecationWarning" tests.py +``` + +### In applications + +Set the `PYTHONWARNINGS` environment variable to surface deprecation warnings when running your application: + +```bash +PYTHONWARNINGS=error::ddtrace.DDTraceDeprecationWarning python app.py +``` + +## Step 2: Address breaking changes + +Review the following changes and update your code before installing v4. + +### Configuration and environment variables + +The `ddtrace.settings` package is removed. Use environment variables to configure settings. + +The following environment variables are removed: + +* `DD_DYNAMIC_INSTRUMENTATION_UPLOAD_FLUSH_INTERVAL` +* `DD_EXCEPTION_DEBUGGING_ENABLED` +* `DD_PROFILING_STACK_V2_ENABLED` +* `DEFAULT_RUNTIME_METRICS_INTERVAL` + +Use `git grep` to find occurrences in your codebase: + +```bash +git grep -P -e "DD_DYNAMIC_INSTRUMENTATION_UPLOAD_FLUSH_INTERVAL" \ +-e "DD_EXCEPTION_DEBUGGING_ENABLED" \ +-e "DD_PROFILING_STACK_V2_ENABLED" \ +-e "DEFAULT_RUNTIME_METRICS_INTERVAL" +``` + +### Tracing API changes + +The following methods on `Span` and `Tracer` objects are removed or have updated type signatures. + +#### Removed methods + +| Class | Method | Replacement | +| :--- | :--- | :--- | +| `Span` | `set_tag_str` | Use `Span.set_tag`. | +| `Span` | `finished` (setter) | Use `Span.finish()`. | +| `Span` | `finish_with_ancestors` | None. | +| `Span` | `set_struct_tag` | None. | +| `Span` | `get_struct_tag` | None. | +| `Span` | `_pprint` | None. | +| `Tracer` | `on_start_span` | None. | +| `Tracer` | `deregister_on_start_span` | None. | +| `ddtrace.trace` | `Pin` | None. | + +#### Updated type signatures + +The following methods enforce stricter typing: + +- `Span.set_tag`: `(key: str, value: Optional[str] = None) -> None` +- `Span.get_tag`: `(key: str) -> Optional[str]` +- `Span.set_tags`: `(tags: dict[str, str]) -> None` +- `Span.get_tags`: `() -> dict[str, str]` +- `Span.set_metric`: `(key: str, value: int | float) -> None` +- `Span.get_metric`: `(key: str) -> Optional[int | float]` +- `Span.set_metrics`: `(metrics: Dict[str, int | float]) -> None` +- `Span.get_metrics`: `() -> dict[str, int | float]` + +#### Parameter changes +- `Span.record_exception`: The `timestamp` and `escaped` parameters are removed. + +### Framework and Integration changes + +#### Django +`DD_DJANGO_TRACING_MINIMAL` defaults to `true`. + +- **Impact:** Django ORM, cache, and template instrumentation are disabled by default. This reduces performance overhead and eliminates duplicate spans, as underlying libraries (such as `psycopg`, `redis`, `jinja2`) are instrumented by their own integrations. +- **Database Spans:** When `DD_DJANGO_INSTRUMENT_DATABASES=true` (default `false`), the tracer merges Django-specific tags into the driver spans rather than creating separate spans. +- **Restoration:** To restore full Django instrumentation, set `DD_DJANGO_TRACING_MINIMAL=false`. + +#### OpenAI +Streamed chat/completions do not use `tiktoken` to compute token counts. +- **Action:** To guarantee accurate streamed token metrics, set `stream_options={"include_usage": True}` in your OpenAI request. + +#### LLM Observability +- **Manual Instrumentation:** The following methods raise exceptions instead of logging errors: `LLMObs.annotate()`, `LLMObs.export_span()`, `LLMObs.submit_evaluation()`, `LLMObs.inject_distributed_headers()`, and `LLMObs.activate_distributed_headers()`. +- **Renaming:** `LLMObs.submit_evaluation_for()` is removed. Use `LLMObs.submit_evaluation()` and rename the `span_context` argument to `span`. + +#### Removed integrations +The following libraries are no longer supported: +- `google_generativeai`: Use the `google_genai` library and integration. +- `Mongoengine:** Support for `ddtrace.Pin` is removed. Use the `pymongo` integration. +- `Aioredis` +- `Freezegun` +- `Opentracer` + +### Profiling + +- The V1 stack profiler is removed. V2 is the default. +- `echion` (Python stack sampler) includes an experimental faster memory copy function. + +### CI Visibility + +- **Pytest:** Deprecated entry points for `pytest_benchmark` and `pytest_bdd` are removed. The standard `pytest` integration supports these plugins. +- **Propagation:** The deprecated `non_active_span` parameter is removed from `HttpPropagator.inject`. + +## Step 3: Upgrade the library + +After addressing breaking changes, install the new version: + +```bash +pip install --upgrade ddtrace +``` + +## Further reading + +{{< partial name="whats-next/whats-next.html" >}} \ No newline at end of file diff --git a/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md b/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md index 12245d551e511..54bd5087041c9 100644 --- a/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md +++ b/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/python.md @@ -66,247 +66,15 @@ For a comprehensive list of configuration options, including Unified Service Tag ## Upgrading to dd-trace-py v4 -Version 4.0.0 of `dd-trace-py` drops support for Python 3.8 and 32-bit linux. It also removes previously deprecated APIs. This guide provides steps to help you upgrade your application. +Version 4.0.0 drops support for Python 3.8, removes deprecated APIs, and changes default behaviors for frameworks like Django. -With the release of `v4.0.0`, the `3.x` release line is in maintenance mode. Only critical bug fixes are backported. For more details, see the [versioning support policy][14]. - -### Step 1: Detect deprecations - -To ensure a smooth transition, first upgrade to the latest v3 release (`3.19.0`) and use the following tools to find any deprecated code that breaks in v4. - -#### In tests - -Run `pytest` with warnings enabled as errors to identify areas in your test suite that need updates: - -```sh -pytest -W "error::ddtrace.DDTraceDeprecationWarning" tests.py -``` - -#### In applications - -Set the`PYTHONWARNINGS` environment variable to surface deprecation warnings when you run your application. - -```sh -PYTHONWARNINGS=error::ddtrace.DDTraceDeprecationWarning python app.py -``` - -### Step 2: Address breaking changes - -After identifying potential issues, review the following breaking changes. Update your code to be compatible with v4 before proceeding with the upgrade. - -##### General - -- Starting with ddtrace v4.0.0, Datadog Agent v7.63.0 or newer is required. -- Support for ddtrace with Python 3.8 is removed after being deprecated in the 3.0 release line. Use ddtrace 4.x with Python 3.9 or newer. -- 32-bit linux is no longer supported. Contact support@datadoghq.com if this blocks upgrading dd-trace-py. - -##### mongoengine - - - Drops support for the `ddtrace.Pin` object with mongoengine. With this change, the ddtrace library no longer directly supports mongoengine. Mongoengine is supported through the `pymongo` integration. - -##### CI Visibility - - - Removed deprecated entry points for the `pytest_benchmark` and `pytest_bdd` integrations. These plugins are supported by the regular `pytest` integration. - -##### Dynamic Instrumentation - - - removed the deprecated `DD_DYNAMIC_INSTRUMENTATION_UPLOAD_FLUSH_INTERVAL` variable. - -##### Exception Replay - - - removed the deprecated `DD_EXCEPTION_DEBUGGING_ENABLED` variable. - -##### Tracing - - - Deprecated methods have been removed - - `Span.set_tag_str` has been removed, use `Span.set_tag` instead. - - `Span.set_struct_tag` has been removed. - - `Span.get_struct_tag` has been removed. - - `Span._pprint` has been removed - - `Span.finished` setter was removed, use `Span.finish()` method instead. - - `Tracer.on_start_span` method has been removed. - - `Tracer.deregister_on_start_span` method has been removed. - - `ddtrace.trace.Pin` has been removed. - - `Span.finish_with_ancestors` was removed with no replacement. - - Some methods have had their type signatures changed - - `Span.set_tag` typing is `set_tag(key: str, value: Optional[str] = None) -> None` - - `Span.get_tag` typing is `get_tag(key: str) -> Optional[str]` - - `Span.set_tags` typing is `set_tags(tags: dict[str, str]) -> None` - - `Span.get_tags` typing is `get_tags() -> dict[str, str]` - - `Span.set_metric` typing is `set_metric(key: str, value: int | float) -> None` - - `Span.get_metric` typing is `get_metric(key: str) -> Optional[int | float]` - - `Span.set_metrics` typing is `set_metrics(metrics: Dict[str, int | float]) -> None` - - `Span.get_metrics` typing is `get_metrics() -> dict[str, int | float]` - - `Span.record_exception`'s `timestamp` and `escaped` parameters are removed - - This change removes the deprecated environment variable `DEFAULT_RUNTIME_METRICS_INTERVAL`. - -##### LLM Observability - - - manual instrumentation methods, including `LLMObs.annotate()`, `LLMObs.export_span()`, `LLMObs.submit_evaluation()`, `LLMObs.inject_distributed_headers()`, and `LLMObs.activate_distributed_headers()` raise exceptions instead of logging. LLM Observability auto-instrumentation is not affected. - - `LLMObs.submit_evaluation_for()` has been removed. Use `LLMObs.submit_evaluation()` instead for submitting evaluations. To migrate: - - `LLMObs.submit_evaluation_for(...)` users: rename to `LLMObs.submit_evaluation(...)` - - `LLMObs.submit_evaluation_for(...)` users: rename the `span_context` argument to `span`, i.e. `LLMObs.submit_evaluation(span_context={"span_id": ..., "trace_id": ...}, ...)` to `LLMObs.submit_evaluation(span={"span_id": ..., "trace_id": ...}, ...)` - -##### Profiling - - - this updates echion (the Python stack sampler) to the latest version, which introduces an experimental faster memory copy function. - - The V1 stack profiler is removed. V2 has been enabled by default since v2.20.0. `DD_PROFILING_STACK_V2_ENABLED` is removed. - -##### Removed Packages - - - The deprecated `freezegun` integration is removed. - - The aioredis integration has been removed. - - This change removes the deprecated `opentracer` package - - This change removes the `ddtrace.settings` package. Environment variables should be used to adjust settings. - -##### Google Generative AI - - - The `google_generativeai` integration has been removed as the `google_generativeai` library has reached end-of-life. - As an alternative, you can use the recommended `google_genai` library and corresponding integration instead. - -##### OpenAI - - - Streamed chat/completions no longer have token counts computed using the `tiktoken` library, and instead - default to having their token counts estimated if not explicitly provided in the OpenAI response object. To guarantee accurate streamed token metrics, set `stream_options={"include_usage": True}` in the OpenAI request. - -##### Django - - - This upgrades the default tracing behavior to enable minimal tracing mode by default (``DD_DJANGO_TRACING_MINIMAL`` defaults to ``true``). Django ORM, cache, and template instrumentation are disabled by default to eliminate duplicate span creation since library integrations for database drivers (psycopg, MySQLdb, sqlite3), cache clients (redis, memcached), template renderers (Jinja2), and other supported libraries continue to be traced. This reduces performance overhead by removing redundant Django-layer instrumentation. To restore all Django instrumentation, set ``DD_DJANGO_TRACING_MINIMAL=false``, or enable individual features using ``DD_DJANGO_INSTRUMENT_DATABASES=true``, ``DD_DJANGO_INSTRUMENT_CACHES=true``, and ``DD_DJANGO_INSTRUMENT_TEMPLATES=true``. - - When ``DD_DJANGO_INSTRUMENT_DATABASES=true`` (default ``false``), database instrumentation merges Django-specific tags into database driver spans created by supported integrations (psycopg, sqlite3, MySQLdb, etc.) instead of creating duplicate Django database spans. If the database cursor is not already wrapped by a supported integration, Django wraps it and creates a span. This change reduces overhead and duplicate spans while preserving visibility into database operations. - -##### Propagation - - - This change removes the deprecated `non_active_span` parameter to `HttpPropagator.inject` - -#### Environment variable changes - -The following environment variables have been removed or replaced. Update your configuration with the new variables where applicable. - -You can use the following command to find all occurrences of these deprecated variables in your codebase: - -```sh -git grep -P -e "DD_DYNAMIC_INSTRUMENTATION_UPLOAD_FLUSH_INTERVAL" \ --e "DD_EXCEPTION_DEBUGGING_ENABLED" \ --e "DD_PROFILING_STACK_V2_ENABLED" \ --e "DEFAULT_RUNTIME_METRICS_INTERVAL" -``` - -
These changes only apply to dd-trace-py configuration and not the Datadog Agent.
- - -#### Python 3.14 compatibility - -Full support for Python 3.14 is in active development. While the core tracing library is compatible, some integrations may not be fully tested or supported in the latest version. - -For the most current compatibility details for a specific integration, see the library's [latest release notes][19]. +For a complete migration guide, see [Migrate to dd-trace-py v4][20]. ## Upgrading to dd-trace-py v3 -Version 3.0.0 of `dd-trace-py` drops support for Python 3.7 and removes previously deprecated APIs. This guide provides steps to help you upgrade your application. - -With the release of `v3.0.0`, the `2.x` release line is in maintenance mode. Only critical bug fixes should be backported. For more details, see the [versioning support policy][14]. - -### Step 1: Detect deprecations - -To ensure a smooth transition, first upgrade to the latest v2 release (`2.21.0`) and use the following tools to find any deprecated code that will break in v3. - -#### In tests - -Run `pytest` with warnings enabled as errors to identify areas in your test suite that need updates: - -```sh -pytest -W "error::ddtrace.DDTraceDeprecationWarning" tests.py -``` - -#### In applications - -Set the`PYTHONWARNINGS` environment variable to surface deprecation warnings when you run your application. - -```sh -PYTHONWARNINGS=all python app.py -``` - -### Step 2: Address breaking changes - -After identifying potential issues, review the following breaking changes. Update your code to be compatible with v3 before proceeding with the upgrade. - -#### Environment variable changes - -The following environment variables have been removed or replaced. Update your configuration with the new variables where applicable. - -You can use the following command to find all occurrences of these deprecated variables in your codebase: +Version 3.0.0 drops support for Python 3.7, removes deprecated APIs, and cleans up configuration names. -```sh -git grep -P -e "DD_LLMOBS_APP_NAME" \ - -e "_DD_LLMOBS_EVALUATOR_SAMPLING_RULES" \ - -e "_DD_LLMOBS_EVALUATORS" \ - -e "DD_TRACE_PROPAGATION_STYLE=.*b3 single header" \ - -e "DD_TRACE_SAMPLE_RATE" \ - -e "DD_TRACE_API_VERSION=v0.3" \ - -e "DD_ANALYTICS_ENABLED" \ - -e "DD_TRACE_ANALYTICS_ENABLED" \ - -e "DD_HTTP_CLIENT_TAG_QUERY_STRING" \ - -e "DD_TRACE_SPAN_AGGREGATOR_RLOCK" \ - -e "DD_TRACE_METHODS=.*\[\]" -``` - -| Deprecation | Action Required | -|-------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------| -| `DD_ANALYTICS_ENABLED` | Removed. This is a no-op. See [Ingestion Controls][15] for alternatives. | -| `DD_HTTP_CLIENT_TAG_QUERY_STRING` | Use `DD_TRACE_HTTP_CLIENT_TAG_QUERY_STRING` instead. | -| `DD_LLMOBS_APP_NAME` | Use `DD_LLMOBS_ML_APP` instead. | -| `_DD_LLMOBS_EVALUATOR_SAMPLING_RULES` | Use `DD_LLMOBS_EVALUATOR_SAMPLING_RULES` instead (without the leading underscore). | -| `_DD_LLMOBS_EVALUATORS` | Use `DD_LLMOBS_EVALUATORS` instead (without the leading underscore). | -| `DD_PYTEST_USE_NEW_PLUGIN_BETA` | Removed. The new pytest plugin is the default and is no longer in beta. | -| `DD_TRACE_ANALYTICS_ENABLED` | Removed. This is a no-op. See [Ingestion Controls][15] for alternatives. | -| `DD_TRACE_METHODS` (using `[]` notation) | You must use the `:` notation. For example: `mod.submod:method2;mod.submod:Class.method1`. See the [DD_TRACE_METHODS][16] for details. | -| `DD_TRACE_PROPAGATION_STYLE="b3 single header"` | Use `DD_TRACE_PROPAGATION_STYLE=b3` for identical behavior. | -| `DD_TRACE_SAMPLE_RATE` | Use `DD_TRACE_SAMPLING_RULES` instead. See [User-Defined Rules][17] for details. | -| `DD_TRACE_SPAN_AGGREGATOR_RLOCK` | Removed. This feature has been removed and the variable is a no-op. | - -
These changes only apply to dd-trace-py configuration and not the Datadog Agent.
- -#### API and interface changes - -The following methods, attributes, and behaviors have been removed or changed. - -##### General - -- **Python 3.7 Support**: Support for Python 3.7 is removed. - -##### Tracing - -- **Multiple Tracer Instances**: Support for multiple `Tracer` instances is removed. You must use the global `ddtrace.tracer` instance. -- `Tracer.configure()`: Deprecated parameters have been removed. Use environment variables to configure Agent connection details (`hostname`, `port`), sampling, and other settings. -- `Span.sampled`: This attribute is removed. Use `span.context.sampling_priority > 0` to check if a span is sampled. -- `ddtrace.opentracer`: The `_dd_tracer` attribute is removed. Use the global `ddtrace.tracer` instead. -- `LLMObs.annotate()`: The `parameters` argument is removed. Use `metadata` instead. -- `choose_matcher()`: Callables and regex patterns are no longer allowed as arguments to `ddtrace.tracer.sampler.rules[].choose_matcher`. You must pass a string. - -##### LLM Observability - -- **OpenAI and Langchain**: Support for OpenAI v0.x and Langchain v0.0.x is dropped. - -##### CI Visibility - -- The new pytest plugin is the default. -- Module, suite, and test names are parsed from `item.nodeid`. -- Test names for class-based tests include the class name (for example, `TestClass::test_method`). -- Test skipping is performed at the suite level. - -### Step 3: Upgrade the library - -After you have updated your code to address the breaking changes, you can upgrade to the latest v3 release. - -```sh -pip install --upgrade ddtrace -``` - -#### Python 3.13 compatibility - -Full support for Python 3.13 is in active development. While the core tracing library is compatible, some integrations may not be fully tested or supported in the latest version. - -For the most current compatibility details for a specific integration, see the library's [latest release notes][19]. +For a complete migration guide, see [Migrate to dd-trace-py v3][21]. ## Further reading @@ -325,3 +93,6 @@ For the most current compatibility details for a specific integration, see the l [17]: /tracing/trace_pipeline/ingestion_mechanisms/?tab=python#in-tracing-libraries-user-defined-rules [18]: https://github.com/DataDog/dd-trace-py [19]: https://github.com/DataDog/dd-trace-py/releases +[20]: /tracing/trace_collection/automatic_instrumentation/dd_libraries/migrate/python/v4 +[21]: /tracing/trace_collection/automatic_instrumentation/dd_libraries/migrate/python/v3 +