redis/redis-py · error · ImportError

OpenTelemetry API is not installed. Install it with: pip…

Error message

OpenTelemetry API is not installed. Install it with: pip install opentelemetry-api

What it means

Raised as ImportError by RedisMetricsCollector.__init__ (redis/observability/metrics.py:84) when the module-level import `from opentelemetry.metrics import Meter` failed at load time, leaving OTEL_AVAILABLE=False. The collector cannot create any instruments (Counter/Histogram/UpDownCounter) without the opentelemetry-api package, so construction aborts immediately with an actionable install hint.

Solutions

Install the dependency: `pip install opentelemetry-api` (or reinstall redis with the extra: `pip install redis[otel]`).
Verify the import resolves in the running interpreter: `python -c "from opentelemetry.metrics import Meter"`.
If metrics are optional for your app, guard initialization so a missing dependency disables observability rather than crashing startup.
Pin compatible opentelemetry versions in requirements to avoid a resolver silently removing opentelemetry-api.

Example fix

# before
from redis.observability import get_observability_instance, OTelConfig
otel = get_observability_instance()
otel.init(OTelConfig(enable_metrics=True))  # ImportError if opentelemetry-api missing

# after - install dependency, then optionally guard
pip install opentelemetry-api

# or make observability optional in code
try:
    from redis.observability import get_observability_instance, OTelConfig
    get_observability_instance().init(OTelConfig(enable_metrics=True))
except ImportError:
    logging.warning("OpenTelemetry not installed; metrics disabled")

Defensive patterns

Strategy: validation

Validate before calling

def metrics_available():
    try:
        from opentelemetry.metrics import Meter  # noqa: F401
        return True
    except ImportError:
        return False

if metrics_available():
    from redis.observability import get_observability_instance, OTelConfig
    get_observability_instance().init(OTelConfig(enable_metrics=True))

Try / catch

try:
    from redis.observability import get_observability_instance, OTelConfig
    get_observability_instance().init(OTelConfig(enable_metrics=True))
except ImportError as e:
    if 'opentelemetry-api' in str(e):
        logging.warning('OpenTelemetry API missing; metrics disabled')
    else:
        raise

Prevention

Install redis with the otel extra (`pip install redis[otel]`) in any environment that enables metrics.
Add a smoke check at startup that imports opentelemetry.metrics before initializing observability.
Make observability opt-in / guarded by try-except so a missing dependency degrades gracefully instead of crashing.
Pin opentelemetry-api in your lockfile to prevent a resolver from removing it.

When it happens

Trigger: Instantiating RedisMetricsCollector(meter, config) directly, or calling get_observability_instance().init(OTelConfig(enable_metrics=True)) which builds the provider manager and collector, in an environment where `pip install opentelemetry-api` was never run. Also triggered when the `otel` extra (redis[otel]) was not requested at install time.

Common situations: Enabling the observability feature in code but forgetting to add the otel extra to requirements.txt; CI image that lacks the wheel; a downgraded opentelemetry-api that uninstalled itself due to a dependency conflict; production env built from a slim base image that never included opentelemetry-api.

Related errors

AI-assisted analysis of redis/redis-py@6a6b581b48 (2026-08-10). Data as JSON: /api/errors/312d7b06c6fc274c. Report an issue: GitHub.

Appendix: source

Thrown at redis/observability/metrics.py:84

class RedisMetricsCollector:
    """
    Collects and records OpenTelemetry metrics for Redis operations.

    This class manages all metric instruments and provides methods to record
    various Redis operations including connection pool events, command execution,
    and cluster-specific operations.

    Args:
        meter: OpenTelemetry Meter instance
        config: OTel configuration object
    """

    METER_NAME = "redis-py"
    METER_VERSION = "1.0.0"

    def __init__(self, meter: Meter, config: OTelConfig):
        if not OTEL_AVAILABLE:
            raise ImportError(
                "OpenTelemetry API is not installed. "
                "Install it with: pip install opentelemetry-api"
            )

        self.meter = meter
        self.config = config
        self.attr_builder = AttributeBuilder()

        # Initialize enabled metric instruments

        if MetricGroup.RESILIENCY in self.config.metric_groups:
            self._init_resiliency_metrics()

        if MetricGroup.COMMAND in self.config.metric_groups:
            self._init_command_metrics()

        if MetricGroup.CONNECTION_BASIC in self.config.metric_groups:
            self._init_connection_basic_metrics()

View on GitHub (pinned to 6a6b581b48)