botocore: document threading instrumentation for S3 multipart operations (#3999)

* botocore: document threading instrumentation for S3 multipart operations

Document that users need to enable ThreadingInstrumentor alongside
BotocoreInstrumentor for proper trace context propagation with S3
upload_file and download_file methods.

* botocore: move thread context docs to module docstring only

README.rst is not built into the documentation, so keep the
threading context propagation docs only in __init__.py where
autodoc will pick them up.

* Update __init__.py

* Update __init__.py

---------

Co-authored-by: Riccardo Magliocchetti <riccardo.magliocchetti@gmail.com>

Author: bendrucker

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

@@ -42,20 +42,36 @@
     ec2 = session.create_client("ec2", region_name="us-west-2")
     ec2.describe_instances()
 
+Thread Context Propagation
+--------------------------
+
+boto3's S3 ``upload_file`` and ``download_file`` methods use background threads
+for multipart transfers. To ensure trace context is propagated to these threads,
+also enable the threading instrumentation:
+
+.. code:: python
+
+    from opentelemetry.instrumentation.threading import ThreadingInstrumentor
+    from opentelemetry.instrumentation.botocore import BotocoreInstrumentor
+
+    ThreadingInstrumentor().instrument()
+    BotocoreInstrumentor().instrument()
+
+When using auto-instrumentation (``opentelemetry-instrument``), both instrumentors
+are enabled automatically if their packages are installed.
+
 API
 ---
 
 The `instrument` method accepts the following keyword args:
 
-tracer_provider (TracerProvider) - an optional tracer provider
-request_hook (Callable) - a function with extra user-defined logic to be performed before performing the request
-this function signature is:  def request_hook(span: Span, service_name: str, operation_name: str, api_params: dict) -> None
-response_hook (Callable) - a function with extra user-defined logic to be performed after performing the request
-this function signature is:  def response_hook(span: Span, service_name: str, operation_name: str, result: dict) -> None
+* tracer_provider (``TracerProvider``) - an optional tracer provider
+* request_hook (``Callable[[Span, str, str, dict], None]``) - a function with extra user-defined logic to be performed before performing the request
+* response_hook (``Callable[[Span, str, str, dict], None]``) - a function with extra user-defined logic to be performed after performing the request
 
 for example:
 
-.. code: python
+.. code:: python
 
     from opentelemetry.instrumentation.botocore import BotocoreInstrumentor
     import botocore.session