Consolidate instrumentation documentation in docstrings

instrumentation/opentelemetry-instrumentation-aiohttp-client/README.rst

@@ -54,6 +54,28 @@ Example
 
    asyncio.run(span_emitter())
 
+Configuration
+-------------
+
+Request/Response hooks
+**********************
+
+Utilize request/reponse hooks to execute custom logic to be performed before/after performing a request.
+
+.. code-block:: python
+
+   def request_hook(span: Span, params: aiohttp.TraceRequestStartParams):
+      if span and span.is_recording():
+            span.set_attribute("custom_user_attribute_from_request_hook", "some-value")
+
+   def response_hook(span: Span, params: typing.Union[
+                aiohttp.TraceRequestEndParams,
+                aiohttp.TraceRequestExceptionParams,
+            ]):
+        if span and span.is_recording():
+            span.set_attribute("custom_user_attribute_from_response_hook", "some-value")
+
+   AioHttpClientInstrumentor().instrument(request_hook=request_hook, response_hook=response_hook) 
 
 References
 ----------

instrumentation/opentelemetry-instrumentation-asgi/README.rst

@@ -65,6 +65,32 @@ Usage (Raw ASGI)
     app = OpenTelemetryMiddleware(app)
 
 
+Configuration
+-------------
+
+Request/Response hooks
+**********************
+
+Utilize request/reponse hooks to execute custom logic to be performed before/after performing a request. The server request hook takes in a server span and ASGI
+scope object for every incoming request. The client request hook is called with the internal span and an ASGI scope which is sent as a dictionary for when the method recieve is called.
+The client response hook is called with the internal span and an ASGI event which is sent as a dictionary for when the method send is called.
+
+.. code-block:: python
+
+    def server_request_hook(span: Span, scope: dict):
+        if span and span.is_recording():
+            span.set_attribute("custom_user_attribute_from_request_hook", "some-value")
+
+    def client_request_hook(span: Span, scope: dict):
+        if span and span.is_recording():
+            span.set_attribute("custom_user_attribute_from_client_request_hook", "some-value")
+
+    def client_response_hook(span: Span, message: dict):
+        if span and span.is_recording():
+            span.set_attribute("custom_user_attribute_from_response_hook", "some-value")
+
+   OpenTelemetryMiddleware().(application, server_request_hook=server_request_hook, client_request_hook=client_request_hook, client_response_hook=client_response_hook)
+
 References
 ----------
 

instrumentation/opentelemetry-instrumentation-django/README.rst

@@ -45,8 +45,8 @@ will extract path_info and content_type attributes from every traced request and
 
 Django Request object reference: https://docs.djangoproject.com/en/3.1/ref/request-response/#attributes
 
-Request and Response hooks
-***************************
+Request/Response hooks
+**********************
 The instrumentation supports specifying request and response hooks. These are functions that get called back by the instrumentation right after a Span is created for a request
 and right before the span is finished while processing a response. The hooks can be configured as follows:
 
@@ -60,6 +60,9 @@ and right before the span is finished while processing a response. The hooks can
 
     DjangoInstrumentation().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
+
 
 References
 ----------

instrumentation/opentelemetry-instrumentation-elasticsearch/README.rst

@@ -16,6 +16,26 @@ Installation
 
      pip install opentelemetry-instrumentation-elasticsearch
 
+Configuration
+-------------
+
+Request/Response hooks
+**********************
+
+Utilize request/reponse hooks to execute custom logic to be performed before/after performing a request.
+
+.. code-block:: python
+
+   def request_hook(span: Span, method: str, url: str, kwargs):
+      if span and span.is_recording():
+            span.set_attribute("custom_user_attribute_from_request_hook", "some-value")
+
+   def response_hook(span: Span, response: dict):
+        if span and span.is_recording():
+            span.set_attribute("custom_user_attribute_from_response_hook", "some-value")
+
+   ElasticsearchInstrumentor().instrument(request_hook=request_hook, response_hook=response_hook) 
+
 References
 ----------
 

instrumentation/opentelemetry-instrumentation-falcon/README.rst

@@ -46,6 +46,22 @@ will extract path_info and content_type attributes from every traced request and
 
 Falcon Request object reference: https://falcon.readthedocs.io/en/stable/api/request_and_response.html#id1
 
+
+Request/Response hooks
+**********************
+The instrumentation supports specifying request and response hooks. These are functions that get called back by the instrumentation right after a Span is created for a request
+and right before the span is finished while processing a response. The hooks can be configured as follows:
+
+::
+
+    def request_hook(span, req):
+        pass
+
+    def response_hook(span, req, resp):
+        pass
+
+    FalconInstrumentation().instrument(request_hook=request_hook, response_hook=response_hook)
+
 References
 ----------
 

instrumentation/opentelemetry-instrumentation-fastapi/README.rst

@@ -34,6 +34,34 @@ For example,
 
 will exclude requests such as ``https://site/client/123/info`` and ``https://site/xyz/healthcheck``.
 
+You can also pass the comma delimited regexes to the ``instrument_app`` method directly:
+
+.. code-block:: python
+
+    FastAPIInstrumentor.instrument_app(app, excluded_urls="client/.*/info,healthcheck")
+
+Request/Response hooks
+**********************
+
+Utilize request/reponse hooks to execute custom logic to be performed before/after performing a request. The server request hook takes in a server span and ASGI
+scope object for every incoming request. The client request hook is called with the internal span and an ASGI scope which is sent as a dictionary for when the method recieve is called.
+The client response hook is called with the internal span and an ASGI event which is sent as a dictionary for when the method send is called.
+
+.. code-block:: python
+
+    def server_request_hook(span: Span, scope: dict):
+        if span and span.is_recording():
+            span.set_attribute("custom_user_attribute_from_request_hook", "some-value")
+
+    def client_request_hook(span: Span, scope: dict):
+        if span and span.is_recording():
+            span.set_attribute("custom_user_attribute_from_client_request_hook", "some-value")
+
+    def client_response_hook(span: Span, message: dict):
+        if span and span.is_recording():
+            span.set_attribute("custom_user_attribute_from_response_hook", "some-value")
+
+   FastAPIInstrumentor().instrument(server_request_hook=server_request_hook, client_request_hook=client_request_hook, client_response_hook=client_response_hook)
 
 Usage
 -----
@@ -51,12 +79,6 @@ Usage
 
     FastAPIInstrumentor.instrument_app(app)
 
-You can also pass the list of urls to exclude explicitly to the instrumentation call:
-
-.. code-block:: python
-
-    FastAPIInstrumentor.instrument_app(app, excluded_urls="client/.*/info,healthcheck")
-
 References
 ----------
 

instrumentation/opentelemetry-instrumentation-flask/README.rst

@@ -37,6 +37,26 @@ You can also pass the comma delimited regexes to the ``instrument_app`` method d
 
     FlaskInstrumentor().instrument_app(app, excluded_urls="client/.*/info,healthcheck")
 
+Request/Response hooks
+**********************
+
+Utilize request/reponse hooks to execute custom logic to be performed before/after performing a request. Environ is an instance of WSGIEnvironment (flask.request.environ).
+Response_headers is a list of key-value (tuples) representing the response headers returned from the response.
+
+.. code-block:: python
+
+    def request_hook(span: Span, environ: WSGIEnvironment):
+        if span and span.is_recording():
+            span.set_attribute("custom_user_attribute_from_request_hook", "some-value")
+
+    def response_hook(span: Span, status: str, response_headers: List):
+        if span and span.is_recording():
+            span.set_attribute("custom_user_attribute_from_response_hook", "some-value")
+
+    FlaskInstrumentation().instrument(request_hook=request_hook, response_hook=response_hook)
+
+Flask Request object reference: https://flask.palletsprojects.com/en/2.0.x/api/#flask.Request
+
 References
 ----------
 

instrumentation/opentelemetry-instrumentation-redis/README.rst

@@ -15,6 +15,25 @@ Installation
 
     pip install opentelemetry-instrumentation-redis
 
+Configuration
+-------------
+
+Request/Response hooks
+**********************
+
+Utilize request/reponse hooks to execute custom logic to be performed before/after performing a request. Instance is of type redis.connection.Connection.
+
+.. code-block:: python
+
+    def request_hook(span, instance, args, kwargs):
+        if span and span.is_recording():
+            span.set_attribute("custom_user_attribute_from_request_hook", "some-value")
+
+    def response_hook(span, instance, response):
+        if span and span.is_recording():
+            span.set_attribute("custom_user_attribute_from_response_hook", "some-value")
+
+    RedisInstrumentor().instrument(request_hook=request_hook, response_hook=response_hook)
 
 References
 ----------

instrumentation/opentelemetry-instrumentation-requests/README.rst

@@ -19,11 +19,17 @@ Installation
 Configuration
 -------------
 
-.. code-block:: python
+Exclude lists
+*************
+To exclude certain URLs from being tracked, set the environment variable ``OTEL_PYTHON_REQUESTS_EXCLUDED_URLS`` with comma delimited regexes representing which URLs to exclude.
 
-     from opentelemetry.instrumentation.requests import RequestsInstrumentor
-     RequestsInstrumentor().instrument()
+For example,
 
+::
+
+    export OTEL_PYTHON_REQUESTS_EXCLUDED_URLS="client/.*/info,healthcheck"
+
+will exclude requests such as ``https://site/client/123/info`` and ``https://site/xyz/healthcheck``.
 
 References
 ----------

instrumentation/opentelemetry-instrumentation-starlette/README.rst

@@ -34,6 +34,24 @@ For example,
 
 will exclude requests such as ``https://site/client/123/info`` and ``https://site/xyz/healthcheck``.
 
+Request/Response hooks
+**********************
+
+Utilize request/reponse hooks to execute custom logic to be performed before/after performing a request. The server request hook takes in a server span and ASGI
+scope object for every incoming request. The client request hook is called with the internal span and an ASGI scope which is sent as a dictionary for when the method recieve is called.
+The client response hook is called with the internal span and an ASGI event which is sent as a dictionary for when the method send is called.
+
+.. code-block:: python
+    def server_request_hook(span: Span, scope: dict):
+        if span and span.is_recording():
+            span.set_attribute("custom_user_attribute_from_request_hook", "some-value")
+    def client_request_hook(span: Span, scope: dict):
+        if span and span.is_recording():
+            span.set_attribute("custom_user_attribute_from_client_request_hook", "some-value")
+    def client_response_hook(span: Span, message: dict):
+        if span and span.is_recording():
+            span.set_attribute("custom_user_attribute_from_response_hook", "some-value")
+   StarletteInstrumentor().instrument(server_request_hook=server_request_hook, client_request_hook=client_request_hook, client_response_hook=client_response_hook)
 
 Usage
 -----

instrumentation/opentelemetry-instrumentation-tornado/README.rst

@@ -44,6 +44,40 @@ For example,
 
 will extract path_info and content_type attributes from every traced request and add them as span attributes.
 
+Request/Response hooks
+**********************
+
+Tornado instrumentation supports extending tracing behaviour with the help of hooks.
+Its ``instrument()`` method accepts three optional functions that get called back with the
+created span and some other contextual information. Example:
+
+.. code-block:: python
+
+    # will be called for each incoming request to Tornado
+    # web server. `handler` is an instance of
+    # `tornado.web.RequestHandler`.
+    def server_request_hook(span, handler):
+        pass
+
+    # will be called just before sending out a request with
+    # `tornado.httpclient.AsyncHTTPClient.fetch`.
+    # `request` is an instance of ``tornado.httpclient.HTTPRequest`.
+    def client_request_hook(span, request):
+        pass
+
+    # will be called after a outgoing request made with
+    # `tornado.httpclient.AsyncHTTPClient.fetch` finishes.
+    # `response`` is an instance of ``Future[tornado.httpclient.HTTPResponse]`.
+    def client_resposne_hook(span, future):
+        pass
+
+    # apply tornado instrumentation with hooks
+    TornadoInstrumentor().instrument(
+        server_request_hook=server_request_hook,
+        client_request_hook=client_request_hook,
+        client_response_hook=client_resposne_hook
+    )
+
 References
 ----------
 

instrumentation/opentelemetry-instrumentation-urllib/README.rst

@@ -16,6 +16,32 @@ Installation
 
      pip install opentelemetry-instrumentation-urllib
 
+Configuration
+-------------
+
+Request/Response hooks
+**********************
+
+The urllib 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 urllib.request.Request
+    def request_hook(span, request_obj):
+        pass
+
+    # `request_obj` is an instance of urllib.request.Request
+    # `response` is an instance of http.client.HTTPResponse
+    def response_hook(span, request_obj, response)
+        pass
+
+    URLLibInstrumentor.instrument(
+        request_hook=request_hook, response_hook=response_hook)
+    )
+
 References
 ----------
 

instrumentation/opentelemetry-instrumentation-urllib3/README.rst

@@ -16,6 +16,32 @@ Installation
 
      pip install opentelemetry-instrumentation-urllib3
 
+Configuration
+-------------
+
+Request/Response hooks
+**********************
+
+The urllib3 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` is an instance of urllib3.connectionpool.HTTPConnectionPool
+    def request_hook(span, request):
+        pass
+
+    # `request` is an instance of urllib3.connectionpool.HTTPConnectionPool
+    # `response` is an instance of urllib3.response.HTTPResponse
+    def response_hook(span, request, response):
+        pass
+
+    URLLib3Instrumentor.instrument(
+        request_hook=request_hook, response_hook=response_hook)
+    )
+
 References
 ----------