Consolidate instrumentation documentation in docstrings (open-telemetry#754)

Author: lzchen

CHANGELOG.md

@@ -6,6 +6,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased](https://github.com/open-telemetry/opentelemetry-python/compare/v1.6.2-0.25b2...HEAD)
+
 ### Fixed
 
 - `opentelemetry-instrumentation-asgi` now explicitly depends on asgiref as it uses the package instead of instrumenting it.
@@ -19,6 +20,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#753](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/753))
 - `opentelemetry-instrumentation-pika` Add `_decorate_basic_consume` to ensure post instrumentation `basic_consume` calls are also instrumented.
   ([#759](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/759))
+- Consolidate instrumentation documentation in docstrings
+  ([#754](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/754))
 
 ### Fixed
 

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

@@ -16,45 +16,6 @@ Installation
 
      pip install opentelemetry-instrumentation-aiohttp-client
 
-
-Example
--------
-
-.. code:: python
-
-   import asyncio
-   
-   import aiohttp
-
-   from opentelemetry.instrumentation.aiohttp_client import AioHttpClientInstrumentor
-   from opentelemetry import trace
-   from opentelemetry.exporter.jaeger.thrift import JaegerExporter
-   from opentelemetry.sdk.trace import TracerProvider
-   from opentelemetry.sdk.trace.export import BatchSpanProcessor
-
-
-   _JAEGER_EXPORTER = JaegerExporter(
-      service_name="example-xxx",
-      agent_host_name="localhost",
-      agent_port=6831,
-   )
-
-   _TRACE_PROVIDER = TracerProvider()
-   _TRACE_PROVIDER.add_span_processor(BatchSpanProcessor(_JAEGER_EXPORTER))
-   trace.set_tracer_provider(_TRACE_PROVIDER)
-
-   AioHttpClientInstrumentor().instrument()
-
-
-   async def span_emitter():
-      async with aiohttp.ClientSession() as session:
-         async with session.get("https://example.com") as resp:
-               print(resp.status)
-
-
-   asyncio.run(span_emitter())
-
-
 References
 ----------
 

instrumentation/opentelemetry-instrumentation-aiohttp-client/src/opentelemetry/instrumentation/aiohttp_client/__init__.py

@@ -58,6 +58,29 @@ def strip_query_params(url: yarl.URL) -> str:
         async with session.get(url) as response:
             await response.text()
 
+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)
+
 API
 ---
 """

instrumentation/opentelemetry-instrumentation-asgi/README.rst

@@ -17,54 +17,6 @@ Installation
 
     pip install opentelemetry-instrumentation-asgi
 
-
-Usage (Quart)
--------------
-
-.. code-block:: python
-
-    from quart import Quart
-    from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware
-
-    app = Quart(__name__)
-    app.asgi_app = OpenTelemetryMiddleware(app.asgi_app)
-
-    @app.route("/")
-    async def hello():
-        return "Hello!"
-
-    if __name__ == "__main__":
-        app.run(debug=True)
-
-
-Usage (Django 3.0)
-------------------
-
-Modify the application's ``asgi.py`` file as shown below.
-
-.. code-block:: python
-
-    import os
-    from django.core.asgi import get_asgi_application
-    from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware
-
-    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'asgi_example.settings')
-
-    application = get_asgi_application()
-    application = OpenTelemetryMiddleware(application)
-
-
-Usage (Raw ASGI)
-----------------
-
-.. code-block:: python
-
-    from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware
-
-    app = ...  # An ASGI application.
-    app = OpenTelemetryMiddleware(app)
-
-
 References
 ----------
 

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

@@ -16,6 +16,82 @@
 The opentelemetry-instrumentation-asgi package provides an ASGI middleware that can be used
 on any ASGI framework (such as Django-channels / Quart) to track requests
 timing through OpenTelemetry.
+
+Usage (Quart)
+-------------
+
+.. code-block:: python
+
+    from quart import Quart
+    from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware
+
+    app = Quart(__name__)
+    app.asgi_app = OpenTelemetryMiddleware(app.asgi_app)
+
+    @app.route("/")
+    async def hello():
+        return "Hello!"
+
+    if __name__ == "__main__":
+        app.run(debug=True)
+
+
+Usage (Django 3.0)
+------------------
+
+Modify the application's ``asgi.py`` file as shown below.
+
+.. code-block:: python
+
+    import os
+    from django.core.asgi import get_asgi_application
+    from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware
+
+    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'asgi_example.settings')
+
+    application = get_asgi_application()
+    application = OpenTelemetryMiddleware(application)
+
+
+Usage (Raw ASGI)
+----------------
+
+.. code-block:: python
+
+    from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware
+
+    app = ...  # An ASGI application.
+    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)
+
+API
+---
 """
 
 import typing

instrumentation/opentelemetry-instrumentation-celery/README.rst

@@ -16,51 +16,6 @@ Installation
 
     pip install opentelemetry-instrumentation-celery
 
-Usage
------
-
-* Start broker backend
-
-::
-    docker run -p 5672:5672 rabbitmq
-
-
-* Run instrumented task
-
-.. code-block:: python
-
-    from opentelemetry import trace
-    from opentelemetry.sdk.trace import TracerProvider
-    from opentelemetry.sdk.trace.export import BatchSpanProcessor
-    from opentelemetry.instrumentation.celery import CeleryInstrumentor
-
-    from celery import Celery
-    from celery.signals import worker_process_init
-
-    @worker_process_init.connect(weak=False)
-    def init_celery_tracing(*args, **kwargs):
-        trace.set_tracer_provider(TracerProvider())
-        span_processor = BatchSpanProcessor(ConsoleSpanExporter())
-        trace.get_tracer_provider().add_span_processor(span_processor)
-        CeleryInstrumentor().instrument()
-
-    app = Celery("tasks", broker="amqp://localhost")
-
-    @app.task
-    def add(x, y):
-        return x + y
-
-    add.delay(42, 50)
-
-
-Setting up tracing 
---------------------
-
-When tracing a celery worker process, tracing and instrumention both must be initialized after the celery worker
-process is initialized. This is required for any tracing components that might use threading to work correctly
-such as the BatchSpanProcessor. Celery provides a signal called ``worker_process_init`` that can be used to
-accomplish this as shown in the example above.
-
 References
 ----------
 * `OpenTelemetry Celery Instrumentation <https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/celery/celery.html>`_

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

@@ -47,6 +47,14 @@ def add(x, y):
 
     add.delay(42, 50)
 
+Setting up tracing
+------------------
+
+When tracing a celery worker process, tracing and instrumention both must be initialized after the celery worker
+process is initialized. This is required for any tracing components that might use threading to work correctly
+such as the BatchSpanProcessor. Celery provides a signal called ``worker_process_init`` that can be used to
+accomplish this as shown in the example above.
+
 API
 ---
 """

instrumentation/opentelemetry-instrumentation-django/README.rst

@@ -15,52 +15,6 @@ Installation
 
     pip install opentelemetry-instrumentation-django
 
-Configuration
--------------
-
-Exclude lists
-*************
-To exclude certain URLs from being tracked, set the environment variable ``OTEL_PYTHON_DJANGO_EXCLUDED_URLS`` with comma delimited regexes representing which URLs to exclude.
-
-For example,
-
-::
-
-    export OTEL_PYTHON_DJANGO_EXCLUDED_URLS="client/.*/info,healthcheck"
-
-will exclude requests such as ``https://site/client/123/info`` and ``https://site/xyz/healthcheck``.
-
-Request attributes
-********************
-To extract certain 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. 
-
-For example,
-
-::
-
-    export OTEL_PYTHON_DJANGO_TRACED_REQUEST_ATTRS='path_info,content_type'
-
-will extract path_info and content_type attributes from every traced request and add them as span attritbues.
-
-Django Request object reference: https://docs.djangoproject.com/en/3.1/ref/request-response/#attributes
-
-Request and 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, request):
-        pass
-
-    def response_hook(span, request, response):
-        pass
-
-    DjangoInstrumentation().instrument(request_hook=request_hook, response_hook=response_hook)
-
-
 References
 ----------
 

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

@@ -71,6 +71,12 @@ def response_hook(span, request, response):
         pass
 
     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
+
+API
+---
 """
 
 from logging import getLogger

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

@@ -33,9 +33,6 @@
     es.index(index='my-index', doc_type='my-type', id=1, body={'my': 'data', 'timestamp': datetime.now()})
     es.get(index='my-index', doc_type='my-type', id=1)
 
-API
----
-
 Elasticsearch instrumentation prefixes operation names with the string "Elasticsearch". This
 can be changed to a different string by either setting the `OTEL_PYTHON_ELASTICSEARCH_NAME_PREFIX`
 environment variable or by passing the prefix as an argument to the instrumentor. For example,
@@ -79,6 +76,9 @@ def response_hook(span, response):
     es = elasticsearch.Elasticsearch()
     es.index(index='my-index', doc_type='my-type', id=1, body={'my': 'data', 'timestamp': datetime.now()})
     es.get(index='my-index', doc_type='my-type', id=1)
+
+API
+---
 """
 
 import re