Registry /
observability / opentelemetry-instrumentation-grpc
This library provides automatic instrumentation for gRPC clients and servers within the OpenTelemetry Python ecosystem. It's part of the `opentelemetry-python-contrib` repository, currently at version `0.61b0`. As a `contrib` package, its release cadence often aligns with the main OpenTelemetry Python project, receiving frequent updates to add features, fix bugs, and align with new OpenTelemetry specifications.
Install & Compatibility
Where this runs
tested against v0.63b1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
GrpcInstrumentor
✓ from opentelemetry.instrumentation.grpc import GrpcInstrumentor
This is the primary class used to enable gRPC instrumentation.
set_tracer_provider
✓ from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry import trace
✗ from opentelemetry import trace
trace.set_tracer_provider(SomeProvider())
Always set a `TracerProvider` with a `Resource` and `SpanProcessor` early in your application lifecycle. The `set_tracer_provider` function is part of `opentelemetry.trace` (the API), but you use `opentelemetry.sdk.trace.TracerProvider` for implementation.
This quickstart demonstrates how to set up and enable OpenTelemetry gRPC instrumentation. It configures a basic `TracerProvider` with a `ConsoleSpanExporter` (for printing spans to the console) and then initializes the `GrpcInstrumentor`. Once `instrument()` is called, all subsequent `grpc.insecure_channel`, `grpc.secure_channel`, and `grpc.server` creations will be automatically instrumented. No actual gRPC server is run here, but the channel creation demonstrates the patched behavior.
import grpc
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.instrumentation.grpc import GrpcInstrumentor
# 1. Configure OpenTelemetry Tracer Provider
resource = Resource.create({"service.name": "my-grpc-app"})
tracer_provider = TracerProvider(resource=resource)
tracer_provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(tracer_provider)
# 2. Initialize gRPC Instrumentation
GrpcInstrumentor().instrument()
# Now any gRPC client or server interactions will be automatically instrumented.
# Example (no actual gRPC server running, just showing the channel creation):
print("OpenTelemetry gRPC instrumentation initialized.")
print("Any grpc.insecure_channel or grpc.secure_channel calls from now on will be instrumented.")
try:
# This part would typically be your actual gRPC client/server code
channel = grpc.insecure_channel('localhost:50051')
# Example: call a method (this would require a real gRPC setup)
# stub = YourServiceStub(channel)
# response = stub.YourMethod(YourRequest())
print("Created a gRPC channel (if a server was running, it would be instrumented).")
channel.close()
except Exception as e:
print(f"An error occurred (expected if no gRPC server is running): {e}")
print("Check console for exported spans.")
Debug
Known issues
gotchaThis instrumentation, like many in `opentelemetry-python-contrib`, is currently in beta (`0.61b0`). While generally stable, its API might undergo minor breaking changes or modifications in future releases before reaching a stable `1.0.0` version.fixRefer to release notes for each update and test thoroughly when upgrading. Consider pinning to specific beta versions (`==0.X.Y`) for production environments.
affects: All versions before 1.0.0
gotchaThe gRPC instrumentation must be enabled *before* gRPC channels or servers are initialized. If `GrpcInstrumentor().instrument()` is called after `grpc.insecure_channel()` or `grpc.server()` has already been used to create instances, those existing instances will not be instrumented.fixEnsure `GrpcInstrumentor().instrument()` is called early in your application's startup phase, ideally immediately after configuring your OpenTelemetry `TracerProvider`.
affects: All versions
gotchaThis instrumentation automatically patches standard gRPC methods. Custom gRPC interceptors or highly specialized gRPC setups might not be fully covered. In such cases, you may need to implement manual instrumentation using the OpenTelemetry API.fixIf automatic instrumentation doesn't provide the desired detail, manually create spans using `trace.get_current_tracer().start_as_current_span('my-custom-grpc-operation')` around your specific gRPC logic or within your custom interceptors. affects: All versions
gotchaThe instrumentation relies on the presence of the `grpcio` package. While `opentelemetry-instrumentation-grpc` specifies it as a dependency, ensure your application's environment has a compatible version of `grpcio` installed.fixEnsure `pip install grpcio` (and optionally `grpcio-tools` if compiling protos) is executed in your environment. Check the `grpcio` documentation for compatibility with your Python version.
affects: All versions
Audit
Dependencies
grpciorequiredRequired for gRPC communication, which this library instruments.
opentelemetry-apirequiredCore OpenTelemetry API for defining tracing and metrics.
opentelemetry-sdkrequiredOpenTelemetry SDK for processing and exporting telemetry data.