gRPC Python Observability

1.80.0 verified Fri May 01 auth: no python

Observability package for gRPC Python, providing OpenTelemetry integration for client and server interceptors. Current version 1.80.0, released alongside grpcio. Release cadence matches grpcio releases (monthly).

pip install grpcio-observability

Common errors

error ImportError: cannot import name 'OpenTelemetryClientInterceptor' from 'grpc_opentelemetry' ↓

cause Using an incorrect import path from older documentation or outdated examples

fix

Use from grpc_opentelemetry import OpenTelemetryClientInterceptor

error AttributeError: module 'grpc_opentelemetry' has no attribute 'OpenTelemetryClientInterceptor' ↓

cause Installed older version (<1.0) where interceptors were in submodule

fix

Upgrade to grpcio-observability>=1.0: pip install -U grpcio-observability

error TypeError: __init__() missing 1 required positional argument: 'tracer' ↓

cause OpenTelemetryServerInterceptor requires a tracer argument; missing it

fix

Pass a tracer instance: OpenTelemetryServerInterceptor(trace.get_tracer(__name__))

Warnings

breaking grpcio-observability 1.60+ drops support for Python 3.7 and earlier pre-1.60 import paths ↓

fix Upgrade to Python 3.8+ and use `from grpc_opentelemetry import ...` (not `grpc_opentelemetry.interceptors`)

gotcha Interceptors must be created with the same tracer provider; mixing providers may result in missing spans ↓

fix Ensure both client and server interceptors use the same global tracer provider (set via `trace.set_tracer_provider`)

gotcha OpenTelemetryClientInterceptor does not automatically propagate context; you must install a propagation injector or use the interceptor correctly with metadata ↓

fix Use `create_metric_interceptors()` or manually inject context into gRPC metadata

Imports

OpenTelemetryClientInterceptor

wrong

from grpc_opentelemetry.interceptors import OpenTelemetryClientInterceptor

correct

from grpc_opentelemetry import OpenTelemetryClientInterceptor

older docs may show submodule path; top-level import is correct since v1.0

OpenTelemetryServerInterceptor

from grpc_opentelemetry import OpenTelemetryServerInterceptor

create_metric_interceptors

from grpc_opentelemetry import create_metric_interceptors

Quickstart

Minimal setup for tracing gRPC calls with console export.

import grpc
from grpc_opentelemetry import OpenTelemetryServerInterceptor, OpenTelemetryClientInterceptor
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor

# Set up tracer provider and exporter
trace.set_tracer_provider(TracerProvider())
trace.get_tracer_provider().add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))

# Create interceptors
server_interceptor = OpenTelemetryServerInterceptor(trace.get_tracer(__name__))
client_interceptor = OpenTelemetryClientInterceptor(trace.get_tracer(__name__))

# Use with gRPC server/server
# server = grpc.server(futures.ThreadPoolExecutor(), interceptors=[server_interceptor])
# stub = ... with interceptor