update upgrade notes for new major version

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.                                                                    |
+
+<div class="alert alert-info">These changes only apply to <code>dd-trace-py</code> configuration and not the Datadog Agent.</div>
+
+#### 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

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" >}}