OpenTelemetry Redis Instrumentation

This library allows tracing requests made by the Redis library.

Installation

pip install opentelemetry-instrumentation-redis

Usage

Instrument redis to report Redis queries.

Instrument All Clients

The easiest way to instrument all redis client instances is by RedisInstrumentor().instrument():

from opentelemetry.instrumentation.redis import RedisInstrumentor
import redis


# Instrument redis
RedisInstrumentor().instrument()

# This will report a span with the default settings
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:

from opentelemetry.instrumentation.redis import RedisInstrumentor
import redis.asyncio


# Instrument redis
RedisInstrumentor().instrument()

# This will report a span with the default settings
async def redis_get():
    client = redis.asyncio.Redis(host="localhost", port=6379)
    await client.get("my-key")

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 RedisInstrumentor.instrument_client() method.

Instrument Single Client

The 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.

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")

# 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 RedisInstrumentor.instrument_client() .

Request/Response Hooks

from opentelemetry.instrumentation.redis import RedisInstrumentor
import redis

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")

# Instrument redis with hooks
RedisInstrumentor().instrument(request_hook=request_hook, response_hook=response_hook)

# This will report a span with the default settings and the custom attributes added from the hooks
client = redis.StrictRedis(host="localhost", port=6379)
client.get("my-key")

Suppress Instrumentation

You can use the suppress_instrumentation context manager to prevent instrumentation from being applied to specific Redis operations. This is useful when you want to avoid creating spans for internal operations, health checks, or during specific code paths.

from opentelemetry.instrumentation.redis import RedisInstrumentor
from opentelemetry.instrumentation.utils import suppress_instrumentation
import redis

# Instrument redis
RedisInstrumentor().instrument()

client = redis.StrictRedis(host="localhost", port=6379)

# This will report a span
client.get("my-key")

# This will NOT report a span
with suppress_instrumentation():
    client.get("internal-key")
    client.set("cache-key", "value")

# This will report a span again
client.get("another-key")

API

class opentelemetry.instrumentation.redis.RedisInstrumentor(*args, **kwargs)[source]

Bases: BaseInstrumentor

instrument(tracer_provider=None, request_hook=None, response_hook=None, **kwargs)[source]

Instruments all Redis/StrictRedis/RedisCluster and async client instances.

Parameters:

tracer_provider (Optional[TracerProvider]) – A TracerProvider, defaults to global.
request_hook (Optional[Callable[[Span, Connection, list[Any], dict[str, Any]], None]]) –
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 (Optional[Callable[[Span, Connection, Any], None]]) –
a function with extra user-defined logic to run after the request is complete.

The args represents the response.

static instrument_client(client, tracer_provider=None, request_hook=None, response_hook=None)[source]

Instrument the provided Redis Client. The client can be sync or async. Cluster client is also supported.

Parameters:

client (Redis | Redis | RedisCluster | RedisCluster) – The redis client.
tracer_provider (Optional[TracerProvider]) – A TracerProvider, defaults to global.
request_hook (Optional[Callable[[Span, Connection, list[Any], dict[str, Any]], None]]) –
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 (Optional[Callable[[Span, Connection, Any], None]]) –
a function with extra user-defined logic to run after the request is complete.

The args represents the response.

static uninstrument_client(client)[source]

Disables instrumentation for the given client instance

Parameters:: client (Redis | Redis | RedisCluster | RedisCluster) – The redis client

instrumentation_dependencies()[source]

Return a list of python packages with versions that the will be instrumented.

Return type:: Collection[str]