Merge branch 'main' into fix-django-duration-exemplars

Author: tammy-baylis-swi

CHANGELOG.md

@@ -28,6 +28,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `opentelemetry-instrumentation-aiohttp-server`: add support for custom header captures via `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST` and `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE`
   ([#3916](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3916))
 - `opentelemetry-instrumentation-redis`: add support for `suppress_instrumentation` context manager for both sync and async Redis clients and pipelines
+- `opentelemetry-instrumentation-django`: improve docs for response_hook with examples of providing attributes from middlewares
+  ([#3923](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3923))
 - Update for Log SDK breaking changes. Rename InMemoryLogExporter to InMemoryLogRecordExporter in several tests
   ([#3850](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3589))
 

README.md

@@ -124,6 +124,7 @@ For more information about the maintainer role, see the [community repository](h
 - [Dylan Russell](https://github.com/dylanrussell), Google
 - [Emídio Neto](https://github.com/emdneto), PicPay
 - [Jeremy Voss](https://github.com/jeremydvoss), Microsoft
+- [Liudmila Molkova](https://github.com/lmolkova), Grafana Labs
 - [Owais Lone](https://github.com/owais), Splunk
 - [Pablo Collins](https://github.com/pmcollins), Splunk
 - [Sanket Mehta](https://github.com/sanketmehta28), Cisco

instrumentation-genai/opentelemetry-instrumentation-openai-v2/CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+- Fix service tier attribute names: use `GEN_AI_OPENAI_REQUEST_SERVICE_TIER` for request
+  attributes and `GEN_AI_OPENAI_RESPONSE_SERVICE_TIER` for response attributes.
+  ([#3920](https://github.com/open-telemetry/opentelemetry-python-contrib/issues/3920))
 - Added support for OpenAI embeddings instrumentation
   ([#3461](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3461))
 - Record prompt and completion events regardless of span sampling decision.

instrumentation-genai/opentelemetry-instrumentation-openai-v2/src/opentelemetry/instrumentation/openai_v2/patch.py

@@ -370,7 +370,7 @@ def _set_response_attributes(
     if getattr(result, "service_tier", None):
         set_span_attribute(
             span,
-            GenAIAttributes.GEN_AI_OPENAI_REQUEST_SERVICE_TIER,
+            GenAIAttributes.GEN_AI_OPENAI_RESPONSE_SERVICE_TIER,
             result.service_tier,
         )
 

instrumentation-genai/opentelemetry-instrumentation-openai-v2/src/opentelemetry/instrumentation/openai_v2/utils.py

@@ -230,8 +230,13 @@ def get_llm_request_attributes(
                     GenAIAttributes.GEN_AI_OPENAI_REQUEST_RESPONSE_FORMAT
                 ] = response_format
 
+        # service_tier can be passed directly or in extra_body (in SDK 1.26.0 it's via extra_body)
         service_tier = kwargs.get("service_tier")
-        attributes[GenAIAttributes.GEN_AI_OPENAI_RESPONSE_SERVICE_TIER] = (
+        if service_tier is None:
+            extra_body = kwargs.get("extra_body")
+            if isinstance(extra_body, Mapping):
+                service_tier = extra_body.get("service_tier")
+        attributes[GenAIAttributes.GEN_AI_OPENAI_REQUEST_SERVICE_TIER] = (
             service_tier if service_tier != "auto" else None
         )
 

instrumentation-genai/opentelemetry-instrumentation-openai-v2/tests/test_async_chat_completions.py

@@ -183,6 +183,8 @@ async def test_async_chat_completion_extra_params(
         response.model,
         response.usage.prompt_tokens,
         response.usage.completion_tokens,
+        request_service_tier="default",
+        response_service_tier=getattr(response, "service_tier", None),
     )
     assert (
         spans[0].attributes[GenAIAttributes.GEN_AI_OPENAI_REQUEST_SEED] == 42

instrumentation-genai/opentelemetry-instrumentation-openai-v2/tests/test_chat_completions.py

@@ -221,6 +221,8 @@ def test_chat_completion_extra_params(
         response.model,
         response.usage.prompt_tokens,
         response.usage.completion_tokens,
+        request_service_tier="default",
+        response_service_tier=getattr(response, "service_tier", None),
     )
     assert (
         spans[0].attributes[GenAIAttributes.GEN_AI_OPENAI_REQUEST_SEED] == 42

instrumentation-genai/opentelemetry-instrumentation-openai-v2/tests/test_utils.py

@@ -25,6 +25,14 @@
 )
 
 
+def _assert_optional_attribute(span, attribute_name, expected_value):
+    """Helper to assert optional span attributes."""
+    if expected_value is not None:
+        assert expected_value == span.attributes[attribute_name]
+    else:
+        assert attribute_name not in span.attributes
+
+
 def assert_all_attributes(
     span: ReadableSpan,
     request_model: str,
@@ -35,6 +43,8 @@ def assert_all_attributes(
     operation_name: str = "chat",
     server_address: str = "api.openai.com",
     server_port: int = 443,
+    request_service_tier: Optional[str] = None,
+    response_service_tier: Optional[str] = None,
 ):
     assert span.name == f"{operation_name} {request_model}"
     assert (
@@ -49,44 +59,35 @@ def assert_all_attributes(
         request_model == span.attributes[GenAIAttributes.GEN_AI_REQUEST_MODEL]
     )
 
-    if response_model:
-        assert (
-            response_model
-            == span.attributes[GenAIAttributes.GEN_AI_RESPONSE_MODEL]
-        )
-    else:
-        assert GenAIAttributes.GEN_AI_RESPONSE_MODEL not in span.attributes
-
-    if response_id:
-        assert (
-            response_id == span.attributes[GenAIAttributes.GEN_AI_RESPONSE_ID]
-        )
-    else:
-        assert GenAIAttributes.GEN_AI_RESPONSE_ID not in span.attributes
-
-    if input_tokens:
-        assert (
-            input_tokens
-            == span.attributes[GenAIAttributes.GEN_AI_USAGE_INPUT_TOKENS]
-        )
-    else:
-        assert GenAIAttributes.GEN_AI_USAGE_INPUT_TOKENS not in span.attributes
-
-    if output_tokens:
-        assert (
-            output_tokens
-            == span.attributes[GenAIAttributes.GEN_AI_USAGE_OUTPUT_TOKENS]
-        )
-    else:
-        assert (
-            GenAIAttributes.GEN_AI_USAGE_OUTPUT_TOKENS not in span.attributes
-        )
+    _assert_optional_attribute(
+        span, GenAIAttributes.GEN_AI_RESPONSE_MODEL, response_model
+    )
+    _assert_optional_attribute(
+        span, GenAIAttributes.GEN_AI_RESPONSE_ID, response_id
+    )
+    _assert_optional_attribute(
+        span, GenAIAttributes.GEN_AI_USAGE_INPUT_TOKENS, input_tokens
+    )
+    _assert_optional_attribute(
+        span, GenAIAttributes.GEN_AI_USAGE_OUTPUT_TOKENS, output_tokens
+    )
 
     assert server_address == span.attributes[ServerAttributes.SERVER_ADDRESS]
 
     if server_port != 443 and server_port > 0:
         assert server_port == span.attributes[ServerAttributes.SERVER_PORT]
 
+    _assert_optional_attribute(
+        span,
+        GenAIAttributes.GEN_AI_OPENAI_REQUEST_SERVICE_TIER,
+        request_service_tier,
+    )
+    _assert_optional_attribute(
+        span,
+        GenAIAttributes.GEN_AI_OPENAI_RESPONSE_SERVICE_TIER,
+        response_service_tier,
+    )
+
 
 def assert_log_parent(log, span):
     """Assert that the log record has the correct parent span context"""

instrumentation/opentelemetry-instrumentation-django/src/opentelemetry/instrumentation/django/__init__.py

@@ -45,7 +45,7 @@
 will exclude requests such as ``https://site/client/123/info`` and ``https://site/xyz/healthcheck``.
 
 Request attributes
-********************
+******************
 To extract attributes from Django's request object and use them as span attributes, set the environment variable
 ``OTEL_PYTHON_DJANGO_TRACED_REQUEST_ATTRS`` to a comma delimited list of request attribute names.
 
@@ -57,10 +57,10 @@
 
 will extract the ``path_info`` and ``content_type`` attributes from every traced request and add them as span attributes.
 
-Django Request object reference: https://docs.djangoproject.com/en/3.1/ref/request-response/#attributes
+* `Django Request object reference <https://docs.djangoproject.com/en/5.2/ref/request-response/#attributes>`_
 
 Request and Response hooks
-***************************
+**************************
 This instrumentation supports request and response hooks. These are functions that get called
 right after a span is created for a request and right before the span is finished for the response.
 The hooks can be configured as follows:
@@ -77,8 +77,76 @@ def response_hook(span, request, response):
 
     DjangoInstrumentor().instrument(request_hook=request_hook, response_hook=response_hook)
 
-Django Request object: https://docs.djangoproject.com/en/3.1/ref/request-response/#httprequest-objects
-Django Response object: https://docs.djangoproject.com/en/3.1/ref/request-response/#httpresponse-objects
+* `Django Request object <https://docs.djangoproject.com/en/5.2/ref/request-response/#httprequest-objects>`_
+* `Django Response object <https://docs.djangoproject.com/en/5.2/ref/request-response/#httpresponse-objects>`_
+
+Adding attributes from middleware context
+#########################################
+In many Django applications, certain request attributes become available only *after*
+specific middlewares have executed. For example:
+
+- ``django.contrib.auth.middleware.AuthenticationMiddleware`` populates ``request.user``
+- ``django.contrib.sites.middleware.CurrentSiteMiddleware`` populates ``request.site``
+
+Because the OpenTelemetry instrumentation creates the span **before** Django middlewares run,
+these attributes are **not yet available** in the ``request_hook`` stage.
+
+Therefore, such attributes should be safely attached in the **response_hook**, which executes
+after Django finishes processing the request (and after all middlewares have completed).
+
+Example: Attaching the authenticated user and current site to the span:
+
+.. code:: python
+
+    def response_hook(span, request, response):
+        # Attach user information if available
+        if request.user.is_authenticated:
+            span.set_attribute("enduser.id", request.user.pk)
+            span.set_attribute("enduser.username", request.user.get_username())
+
+        # Attach current site (if provided by CurrentSiteMiddleware)
+        if hasattr(request, "site"):
+            span.set_attribute("site.id", getattr(request.site, "pk", None))
+            span.set_attribute("site.domain", getattr(request.site, "domain", None))
+
+    DjangoInstrumentor().instrument(response_hook=response_hook)
+
+This ensures that middleware-dependent context (like user or site information) is properly
+recorded once Django’s middleware stack has finished execution.
+
+Custom Django middleware can also attach arbitrary data to the ``request`` object,
+which can later be included as span attributes in the ``response_hook``.
+
+* `Django middleware reference <https://docs.djangoproject.com/en/5.2/topics/http/middleware/>`_
+
+Best practices
+##############
+- Use **response_hook** (not request_hook) when accessing attributes added by Django middlewares.
+- Common middleware-provided attributes include:
+
+  - ``request.user`` (AuthenticationMiddleware)
+  - ``request.site`` (CurrentSiteMiddleware)
+
+- Avoid adding large or sensitive data (e.g., passwords, session tokens, PII) to spans.
+- Use **namespaced attribute keys**, e.g., ``enduser.*``, ``site.*``, or ``custom.*``, for clarity.
+- Hooks should execute quickly — avoid blocking or long-running operations.
+- Hooks can be safely combined with OpenTelemetry **Context propagation** or **Baggage**
+  for consistent tracing across services.
+
+* `OpenTelemetry semantic conventions <https://opentelemetry.io/docs/specs/semconv/http/http-spans/>`_
+
+Middleware execution order
+##########################
+In Django’s request lifecycle, the OpenTelemetry `request_hook` is executed before
+the first middleware runs. Therefore:
+
+- At `request_hook` time → only the bare `HttpRequest` object is available.
+- After middlewares → `request.user`, `request.site` etc. become available.
+- At `response_hook` time → all middlewares (including authentication and site middlewares)
+  have already run, making it the correct place to attach these attributes.
+
+Developers who need to trace attributes from middlewares should always use `response_hook`
+to ensure complete and accurate span data.
 
 Capture HTTP request and response headers
 *****************************************