Update documentation with the client method

Author: OlegZv

docs/conf.py

@@ -122,6 +122,7 @@
         "https://opentelemetry-python.readthedocs.io/en/latest/",
         None,
     ),
+    "redis": ("https://redis-py.readthedocs.io/en/latest/", None),
 }
 
 # http://www.sphinx-doc.org/en/master/config.html#confval-nitpicky

docs/instrumentation/redis/redis.rst

@@ -1,7 +1,10 @@
-OpenTelemetry Redis Instrumentation
-===================================
+.. include:: ../../../instrumentation/opentelemetry-instrumentation-redis/README.rst
+    :end-before: References
+
+Usage
+-----
 
 .. automodule:: opentelemetry.instrumentation.redis
     :members:
     :undoc-members:
-    :show-inheritance:
+    :show-inheritance:

instrumentation/opentelemetry-instrumentation-httpx/README.rst

@@ -43,9 +43,11 @@ Instrumenting single clients
 ****************************
 
 If you only want to instrument requests for specific client instances, you can
-use the `instrument_client` method.
+use the `instrument_client`_ method.
 
 
+.. _instrument_client: #opentelemetry.instrumentation.httpx.HTTPXClientInstrumentor.instrument_client
+
 .. code-block:: python
 
     import httpx

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

@@ -15,15 +15,14 @@
 """
 Instrument `redis`_ to report Redis queries.
 
-There are two options for instrumenting code. The first option is to use the
-``opentelemetry-instrument`` executable which will automatically
-instrument your Redis client. The second is to programmatically enable
-instrumentation via the following code:
-
 .. _redis: https://pypi.org/project/redis/
 
-Usage
------
+
+Instrument All Clients
+----------------------
+
+The easiest way to instrument all redis client instances is by
+``RedisInstrumentor().instrument()``:
 
 .. code:: python
 
@@ -38,7 +37,7 @@
     client = redis.StrictRedis(host="localhost", port=6379)
     client.get("my-key")
 
-Async Redis clients (i.e. redis.asyncio.Redis) are also instrumented in the same way:
+Async Redis clients (i.e. ``redis.asyncio.Redis``) are also instrumented in the same way:
 
 .. code:: python
 
@@ -54,19 +53,44 @@ async def redis_get():
         client = redis.asyncio.Redis(host="localhost", port=6379)
         await client.get("my-key")
 
-The `instrument` method accepts the following keyword args:
+.. note::
+    Calling the ``instrument`` method will instrument the client classes, so any client
+    created after the ``instrument`` call will be instrumented. To instrument only a
+    single client, use :func:`RedisInstrumentor.instrument_client` method.
 
-tracer_provider (TracerProvider) - an optional tracer provider
+Instrument Single Client
+------------------------
 
-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, instance: redis.connection.Connection, args, kwargs) -> None
+The :func:`RedisInstrumentor.instrument_client` can instrument a connection instance. This is useful when there are multiple clients with a different redis database index.
+Or, you might have a different connection pool used for an application function you
+don't want instrumented.
 
-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, instance: redis.connection.Connection, response) -> None
+.. code:: python
 
-for example:
+    from opentelemetry.instrumentation.redis import RedisInstrumentor
+    import redis
+
+    instrumented_client = redis.Redis()
+    not_instrumented_client = redis.Redis()
+
+    # Instrument redis
+    RedisInstrumentor.instrument_client(client=instrumented_client)
+
+    # This will report a span with the default settings
+    instrumented_client.get("my-key")
 
-.. code: python
+    # This will not have a span
+    not_instrumented_client.get("my-key")
+
+.. warning::
+    All client instances created after calling ``RedisInstrumentor().instrument`` will
+    be instrumented. To avoid instrumenting all clients, use
+    :func:`RedisInstrumentor.instrument_client` .
+
+Request/Response Hooks
+----------------------
+
+.. code:: python
 
     from opentelemetry.instrumentation.redis import RedisInstrumentor
     import redis
@@ -86,7 +110,6 @@ def response_hook(span, instance, response):
     client = redis.StrictRedis(host="localhost", port=6379)
     client.get("my-key")
 
-
 API
 ---
 """
@@ -110,16 +133,16 @@ def response_hook(span, instance, response):
 from opentelemetry.instrumentation.redis.version import __version__
 from opentelemetry.instrumentation.utils import unwrap
 from opentelemetry.semconv.trace import SpanAttributes
-from opentelemetry.trace import Span, StatusCode
+from opentelemetry.trace import Span, StatusCode, TracerProvider, get_tracer
 
 _DEFAULT_SERVICE = "redis"
 
-_RequestHookT = typing.Optional[
+RequestHook = typing.Optional[
     typing.Callable[
-        [Span, redis.connection.Connection, typing.List, typing.Dict], None
+        [Span, redis.connection.Connection, typing.Tuple, typing.Dict], None
     ]
 ]
-_ResponseHookT = typing.Optional[
+ResponseHook = typing.Optional[
     typing.Callable[[Span, redis.connection.Connection, Any], None]
 ]
 _logger = logging.getLogger(__name__)
@@ -252,8 +275,8 @@ def _build_span_meta_data_for_pipeline(instance):
 
 def _traced_execute_factory(
     tracer,
-    request_hook: _RequestHookT = None,
-    response_hook: _ResponseHookT = None,
+    request_hook: RequestHook = None,
+    response_hook: ResponseHook = None,
 ):
     def _traced_execute_command(func, instance, args, kwargs):
         query = _format_command_args(args)
@@ -282,8 +305,8 @@ def _traced_execute_command(func, instance, args, kwargs):
 
 def _traced_execute_pipeline_factory(
     tracer,
-    request_hook: _RequestHookT = None,
-    response_hook: _ResponseHookT = None,
+    request_hook: RequestHook = None,
+    response_hook: ResponseHook = None,
 ):
     def _traced_execute_pipeline(func, instance, args, kwargs):
         (
@@ -322,8 +345,8 @@ def _traced_execute_pipeline(func, instance, args, kwargs):
 
 def _async_traced_execute_factory(
     tracer,
-    request_hook: _RequestHookT = None,
-    response_hook: _ResponseHookT = None,
+    request_hook: RequestHook = None,
+    response_hook: ResponseHook = None,
 ):
     async def _async_traced_execute_command(func, instance, args, kwargs):
         query = _format_command_args(args)
@@ -348,8 +371,8 @@ async def _async_traced_execute_command(func, instance, args, kwargs):
 
 def _async_traced_execute_pipeline_factory(
     tracer,
-    request_hook: _RequestHookT = None,
-    response_hook: _ResponseHookT = None,
+    request_hook: RequestHook = None,
+    response_hook: ResponseHook = None,
 ):
     async def _async_traced_execute_pipeline(func, instance, args, kwargs):
         (
@@ -391,8 +414,8 @@ async def _async_traced_execute_pipeline(func, instance, args, kwargs):
 # pylint: disable=R0915
 def _instrument(
     tracer,
-    request_hook: _RequestHookT = None,
-    response_hook: _ResponseHookT = None,
+    request_hook: RequestHook = None,
+    response_hook: ResponseHook = None,
 ):
     _traced_execute_command = _traced_execute_factory(
         tracer, request_hook, response_hook
@@ -463,11 +486,11 @@ def _instrument(
         )
 
 
-def _instrument_connection(
+def _instrument_client(
     client,
     tracer,
-    request_hook: _RequestHookT = None,
-    response_hook: _ResponseHookT = None,
+    request_hook: RequestHook = None,
+    response_hook: ResponseHook = None,
 ):
     # first, handle async clients and cluster clients
     _async_traced_execute = _async_traced_execute_factory(
@@ -539,22 +562,48 @@ def _pipeline_wrapper(func, instance, args, kwargs):
 
 
 class RedisInstrumentor(BaseInstrumentor):
-    """An instrumentor for Redis
-    See `BaseInstrumentor`
-    """
-
     @staticmethod
     def _get_tracer(**kwargs):
         tracer_provider = kwargs.get("tracer_provider")
-        return trace.get_tracer(
+        return get_tracer(
             __name__,
             __version__,
             tracer_provider=tracer_provider,
             schema_url="https://opentelemetry.io/schemas/1.11.0",
         )
 
-    def instrumentation_dependencies(self) -> Collection[str]:
-        return _instruments
+    def instrument(
+        self,
+        tracer_provider: typing.Optional[TracerProvider] = None,
+        request_hook: RequestHook = None,
+        response_hook: ResponseHook = None,
+        **kwargs,
+    ):
+        """Instruments all Redis/StrictRedis/RedisCluster and async client instances.
+
+        Args:
+            tracer_provider: A TracerProvider, defaults to global.
+            request_hook:
+                a function with extra user-defined logic to run before performing the request.
+
+                The ``args`` is a tuple, where items are
+                command arguments. For example ``client.set("mykey", "value", ex=5)`` would
+                have ``args`` as ``('SET', 'mykey', 'value', 'EX', 5)``.
+
+                The ``kwargs`` represents occasional ``options`` passed by redis. For example,
+                if you use ``client.set("mykey", "value", get=True)``, the ``kwargs`` would be
+                ``{'get': True}``.
+            response_hook:
+                a function with extra user-defined logic to run after the request is complete.
+
+                The ``args`` represents the response.
+        """
+        super().instrument(
+            tracer_provider=tracer_provider,
+            request_hook=request_hook,
+            response_hook=response_hook,
+            **kwargs,
+        )
 
     def _instrument(self, **kwargs):
         """Instruments the redis module
@@ -601,13 +650,44 @@ def _uninstrument(self, **kwargs):
             unwrap(redis.asyncio.cluster.ClusterPipeline, "execute")
 
     @staticmethod
-    def instrument_connection(
-        client, tracer_provider: None, request_hook=None, response_hook=None
+    def instrument_client(
+        client: typing.Union[
+            redis.StrictRedis,
+            redis.Redis,
+            redis.asyncio.Redis,
+            redis.cluster.RedisCluster,
+            redis.asyncio.cluster.RedisCluster,
+        ],
+        tracer_provider: typing.Optional[TracerProvider] = None,
+        request_hook: RequestHook = None,
+        response_hook: ResponseHook = None,
     ):
+        """Instrument the provided Redis Client. The client can be sync or async.
+        Cluster client is also supported.
+
+        Args:
+            client: The redis client.
+            tracer_provider: A TracerProvider, defaults to global.
+            request_hook: a function with extra user-defined logic to run before
+                performing the request.
+
+                The ``args`` is a tuple, where items are
+                command arguments. For example ``client.set("mykey", "value", ex=5)`` would
+                have ``args`` as ``('SET', 'mykey', 'value', 'EX', 5)``.
+
+                The ``kwargs`` represents occasional ``options`` passed by redis. For example,
+                if you use ``client.set("mykey", "value", get=True)``, the ``kwargs`` would be
+                ``{'get': True}``.
+
+            response_hook: a function with extra user-defined logic to run after
+                the request is complete.
+
+                The ``args`` represents the response.
+        """
         if not hasattr(client, INSTRUMENTATION_ATTR):
             setattr(client, INSTRUMENTATION_ATTR, False)
         if not getattr(client, INSTRUMENTATION_ATTR):
-            _instrument_connection(
+            _instrument_client(
                 client,
                 RedisInstrumentor._get_tracer(tracer_provider=tracer_provider),
                 request_hook=request_hook,
@@ -620,7 +700,20 @@ def instrument_connection(
             )
 
     @staticmethod
-    def uninstrument_connection(client):
+    def uninstrument_client(
+        client: typing.Union[
+            redis.StrictRedis,
+            redis.Redis,
+            redis.asyncio.Redis,
+            redis.cluster.RedisCluster,
+            redis.asyncio.cluster.RedisCluster,
+        ],
+    ):
+        """Disables instrumentation for the given client instance
+
+        Args:
+            client: The redis client
+        """
         if getattr(client, INSTRUMENTATION_ATTR):
             # for all clients we need to unwrap execute_command and pipeline functions
             unwrap(client, "execute_command")
@@ -634,3 +727,7 @@ def uninstrument_connection(client):
                 "Attempting to un-instrument Redis connection that wasn't instrumented"
             )
             return
+
+    def instrumentation_dependencies(self) -> Collection[str]:
+        """Return a list of python packages with versions that the will be instrumented."""
+        return _instruments