{"id":1608,"library":"opentelemetry-instrumentation-grpc","title":"OpenTelemetry gRPC Instrumentation","description":"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.","status":"active","version":"0.61b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-grpc","tags":["opentelemetry","grpc","instrumentation","tracing","observability","distributed-tracing","python"],"install":[{"cmd":"pip install opentelemetry-instrumentation-grpc opentelemetry-sdk","lang":"bash","label":"Install instrumentation and SDK"}],"dependencies":[{"reason":"Required for gRPC communication, which this library instruments.","package":"grpcio","optional":false},{"reason":"Core OpenTelemetry API for defining tracing and metrics.","package":"opentelemetry-api","optional":false},{"reason":"OpenTelemetry SDK for processing and exporting telemetry data.","package":"opentelemetry-sdk","optional":false}],"imports":[{"note":"This is the primary class used to enable gRPC instrumentation.","symbol":"GrpcInstrumentor","correct":"from opentelemetry.instrumentation.grpc import GrpcInstrumentor"},{"note":"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.","wrong":"from opentelemetry import trace\ntrace.set_tracer_provider(SomeProvider())","symbol":"set_tracer_provider","correct":"from opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry import trace"}],"quickstart":{"code":"import grpc\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.instrumentation.grpc import GrpcInstrumentor\n\n# 1. Configure OpenTelemetry Tracer Provider\nresource = Resource.create({\"service.name\": \"my-grpc-app\"})\ntracer_provider = TracerProvider(resource=resource)\ntracer_provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))\ntrace.set_tracer_provider(tracer_provider)\n\n# 2. Initialize gRPC Instrumentation\nGrpcInstrumentor().instrument()\n\n# Now any gRPC client or server interactions will be automatically instrumented.\n# Example (no actual gRPC server running, just showing the channel creation):\nprint(\"OpenTelemetry gRPC instrumentation initialized.\")\nprint(\"Any grpc.insecure_channel or grpc.secure_channel calls from now on will be instrumented.\")\n\ntry:\n    # This part would typically be your actual gRPC client/server code\n    channel = grpc.insecure_channel('localhost:50051')\n    # Example: call a method (this would require a real gRPC setup)\n    # stub = YourServiceStub(channel)\n    # response = stub.YourMethod(YourRequest())\n    print(\"Created a gRPC channel (if a server was running, it would be instrumented).\")\n    channel.close()\nexcept Exception as e:\n    print(f\"An error occurred (expected if no gRPC server is running): {e}\")\n\nprint(\"Check console for exported spans.\")","lang":"python","description":"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."},"warnings":[{"fix":"Refer to release notes for each update and test thoroughly when upgrading. Consider pinning to specific beta versions (`==0.X.Y`) for production environments.","message":"This 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.","severity":"gotcha","affected_versions":"All versions before 1.0.0"},{"fix":"Ensure `GrpcInstrumentor().instrument()` is called early in your application's startup phase, ideally immediately after configuring your OpenTelemetry `TracerProvider`.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If 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.","message":"This 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `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.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}