From 7c7a2a4312060e4ff55a718a8efb289b16b10803 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Artur=20Sm=C4=99t?=
 <1754812+artursmet@users.noreply.github.com>
Date: Mon, 15 Jul 2024 19:24:16 +0200
Subject: [PATCH] Add documentation for request/response hooks for requests
 instrumentor (#2704)

---
 .../instrumentation/requests/__init__.py      | 24 +++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/instrumentation/opentelemetry-instrumentation-requests/src/opentelemetry/instrumentation/requests/__init__.py b/instrumentation/opentelemetry-instrumentation-requests/src/opentelemetry/instrumentation/requests/__init__.py
index 18cc3e767..0a5556438 100644
--- a/instrumentation/opentelemetry-instrumentation-requests/src/opentelemetry/instrumentation/requests/__init__.py
+++ b/instrumentation/opentelemetry-instrumentation-requests/src/opentelemetry/instrumentation/requests/__init__.py
@@ -31,6 +31,30 @@ Usage
 Configuration
 -------------
 
+Request/Response hooks
+**********************
+
+The requests instrumentation supports extending tracing behavior with the help of
+request and response hooks. These are functions that are called back by the instrumentation
+right after a Span is created for a request and right before the span is finished processing a response respectively.
+The hooks can be configured as follows:
+
+.. code:: python
+
+    # `request_obj` is an instance of requests.PreparedRequest
+    def request_hook(span, request_obj):
+        pass
+
+    # `request_obj` is an instance of requests.PreparedRequest
+    # `response` is an instance of requests.Response
+    def response_hook(span, request_obj, response)
+        pass
+
+    RequestsInstrumentor().instrument(
+        request_hook=request_hook, response_hook=response_hook)
+    )
+
+
 Exclude lists
 *************
 To exclude certain URLs from being tracked, set the environment variable ``OTEL_PYTHON_REQUESTS_EXCLUDED_URLS``