{"id":9798,"library":"grpcio-opentracing","title":"gRPC OpenTracing Interceptors","description":"grpcio-opentracing provides Python OpenTracing Extensions for gRPC, enabling distributed tracing by offering gRPC server and client interceptors. Its current version is 1.1.4. The library is part of the `grpc-ecosystem` but has not seen active development since 2019, reflecting the OpenTracing standard's status as largely superseded by OpenTelemetry.","status":"maintenance","version":"1.1.4","language":"en","source_language":"en","source_url":"https://github.com/grpc-ecosystem/grpc-opentracing","tags":["grpc","opentracing","tracing","observability","deprecated"],"install":[{"cmd":"pip install grpcio-opentracing opentracing","lang":"bash","label":"Install library and core OpenTracing"},{"cmd":"pip install grpcio-opentracing opentracing jaeger-client","lang":"bash","label":"Install with Jaeger (example tracer)"}],"dependencies":[{"reason":"Core gRPC library for which interceptors are provided.","package":"grpcio"},{"reason":"The OpenTracing API, which this library implements extensions for.","package":"opentracing"}],"imports":[{"symbol":"OpenTracingServerInterceptor","correct":"from grpc_opentracing.server_interceptor import OpenTracingServerInterceptor"},{"symbol":"OpenTracingClientInterceptor","correct":"from grpc_opentracing.client_interceptor import OpenTracingClientInterceptor"},{"note":"While `set_global_tracer` exists in the module, the common pattern is to import `opentracing` and call it as `opentracing.set_global_tracer`.","wrong":"from opentracing import set_global_tracer","symbol":"set_global_tracer","correct":"import opentracing\nopentracing.set_global_tracer(...)"}],"quickstart":{"code":"import grpc\nfrom grpc_opentracing.server_interceptor import OpenTracingServerInterceptor\nfrom grpc_opentracing.client_interceptor import OpenTracingClientInterceptor\nimport opentracing\nfrom opentracing.mocktracer import MockTracer # For demonstration\n\n# 1. Initialize an OpenTracing-compliant tracer (e.g., Jaeger, MockTracer)\nmock_tracer = MockTracer()\n# 2. Set the global tracer (optional, but common for simplicity)\nopentracing.set_global_tracer(mock_tracer)\n\n# 3. Create a server interceptor\nserver_interceptor = OpenTracingServerInterceptor(tracer=mock_tracer)\n# To apply: server = grpc.server(futures.ThreadPoolExecutor(max_workers=10), interceptors=[server_interceptor])\n\n# 4. Create a client interceptor\nclient_interceptor = OpenTracingClientInterceptor(tracer=mock_tracer)\n# To apply: channel = grpc.intercept_channel(grpc.insecure_channel('localhost:50051'), client_interceptor)\n\nprint(\"OpenTracing interceptors created successfully.\")\nprint(\"Ensure a tracer is configured, either globally or passed explicitly to the interceptor.\")\n","lang":"python","description":"This quickstart demonstrates how to initialize `OpenTracingServerInterceptor` and `OpenTracingClientInterceptor`. It uses a `MockTracer` for simplicity; in a real application, you would configure a concrete tracer (e.g., Jaeger, Zipkin) and ensure it's made available to the interceptors, either globally or explicitly."},"warnings":[{"fix":"For new projects, strongly consider using `opentelemetry-instrumentation-grpc` from the OpenTelemetry Python Contrib project instead. For existing projects, be aware of the lack of ongoing support.","message":"The OpenTracing project is officially deprecated in favor of OpenTelemetry. This library, `grpcio-opentracing`, has not seen active development since 2019, making it a legacy solution for distributed tracing.","severity":"breaking","affected_versions":"All versions (1.x.x)"},{"fix":"Before using the interceptors, ensure you initialize and set an OpenTracing-compliant tracer, for example: `from jaeger_client import Config; config = Config(config={'sampler': {'type': 'const', 'param': 1}}, service_name='my-grpc-app'); opentracing.set_global_tracer(config.initialize_tracer())`","message":"The interceptors require an `opentracing.Tracer` instance to be configured, either globally via `opentracing.set_global_tracer()` or passed directly to the interceptor constructor (`tracer=my_tracer`). If no tracer is found, tracing will not occur and may lead to `NoneType` errors or silent failures.","severity":"gotcha","affected_versions":"All versions (1.x.x)"},{"fix":"Thoroughly test `grpcio-opentracing` with your specific `grpcio` and Python versions. Consider pinning exact versions of `grpcio` if stability issues arise. Migrating to OpenTelemetry is the recommended long-term solution.","message":"Due to the lack of recent maintenance, `grpcio-opentracing` might have untested or unstable compatibility with newer versions of `grpcio` or Python. This could lead to unexpected behavior or runtime errors.","severity":"gotcha","affected_versions":"All versions (1.x.x)"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install the `opentracing` package: `pip install opentracing`.","cause":"The core OpenTracing API library is not installed, which is a required peer dependency for `grpcio-opentracing` to function.","error":"ModuleNotFoundError: No module named 'opentracing'"},{"fix":"Initialize and set a global tracer (e.g., `opentracing.set_global_tracer(my_tracer)`) or pass a `tracer` object directly to the `OpenTracingServerInterceptor` or `OpenTracingClientInterceptor` constructor.","cause":"The `grpcio-opentracing` interceptor could not find an `opentracing.Tracer` instance, either because the global tracer was not set or no tracer was explicitly passed to the interceptor.","error":"grpc._channel._MultiThreadedRendezvous: <_Rendezvous of RPC that terminated with: status = StatusCode.UNKNOWN details = 'Tracer not set for OpenTracing interceptor'"},{"fix":"Ensure that a valid `opentracing.Tracer` instance is initialized and accessible (globally or explicitly passed) before any gRPC calls are made and before interceptors are configured.","cause":"This typically occurs when a tracer object is expected (e.g., `tracer.start_span()`), but the variable holding the tracer is `None`. This can happen if `opentracing.set_global_tracer()` was not called or a `None` value was passed to the interceptor.","error":"TypeError: 'NoneType' object is not callable"}]}