OpenTelemetry gRPC Instrumentation

Warnings

• gotcha 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.
  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.
• gotcha 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.
  Fix: Ensure `GrpcInstrumentor().instrument()` is called early in your application's startup phase, ideally immediately after configuring your OpenTelemetry `TracerProvider`.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• pip install opentelemetry-instrumentation-grpc opentelemetry-sdk Install instrumentation and SDK

Imports

• 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

  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.

Quickstart

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