{"library":"py-grpc-prometheus","title":"Python gRPC Prometheus Interceptors","description":"py-grpc-prometheus is an instrumentation library that provides Prometheus metrics for gRPC services in Python. It offers client and server interceptors to expose standard gRPC metrics, aiming for parity with similar libraries in Java and Go. The current version is 0.8.0, released in February 2024, with releases occurring on an 'as-needed' basis.","language":"python","status":"active","last_verified":"Fri May 15","install":{"commands":["pip install py-grpc-prometheus"],"cli":null},"imports":["from py_grpc_prometheus.prometheus_server_interceptor import PromServerInterceptor","from py_grpc_prometheus.prometheus_client_interceptor import PromClientInterceptor","from prometheus_client import start_http_server"],"auth":{"required":false,"env_vars":[]},"quickstart":{"code":"import grpc\nfrom concurrent import futures\nfrom prometheus_client import start_http_server\nfrom py_grpc_prometheus.prometheus_server_interceptor import PromServerInterceptor\nfrom py_grpc_prometheus.prometheus_client_interceptor import PromClientInterceptor\n\n# --- Example gRPC Service (replace with your actual service) ---\n# In a real application, you would generate this from a .proto file\nclass GreeterServicer(grpc.ServerInterceptor):\n    def SayHello(self, request, context):\n        print(f\"Server received: {request.name}\")\n        return greeter_pb2.HelloReply(message=f\"Hello, {request.name}!\")\n\n    def intercept_service(self, continuation, handler_call_details):\n        # Simple example of a custom interceptor that just passes through\n        print(f\"Custom server interceptor: {handler_call_details.method}\")\n        return continuation(handler_call_details)\n\n# To make this example runnable, we'll mock proto definitions\nclass greeter_pb2:\n    class HelloRequest:\n        def __init__(self, name=''):\n            self.name = name\n    class HelloReply:\n        def __init__(self, message=''):\n            self.message = message\n\n\n# --- Server Setup ---\ndef serve():\n    # Start Prometheus HTTP server to expose metrics\n    start_http_server(8000)\n    print(\"Prometheus metrics exposed on port 8000\")\n\n    # Initialize Prometheus server interceptor\n    prom_server_interceptor = PromServerInterceptor(enable_handling_time_histogram=True)\n\n    # Create gRPC server with interceptor(s)\n    server = grpc.server(futures.ThreadPoolExecutor(max_workers=10), \n                         interceptors=(prom_server_interceptor, GreeterServicer()))\n\n    # Add your actual service to the server\n    # In a real app, this would be `greeter_pb2_grpc.add_GreeterServicer_to_server`\n    # For this example, we'll just bind the port for a placeholder\n    server.add_insecure_port('[::]:50051')\n    print(\"gRPC server started on port 50051\")\n    server.start()\n    server.wait_for_termination()\n\n# --- Client Setup ---\ndef run_client():\n    # Initialize Prometheus client interceptor\n    prom_client_interceptor = PromClientInterceptor(enable_client_handling_time_histogram=True)\n\n    # Create gRPC channel with interceptor\n    channel = grpc.intercept_channel(\n        grpc.insecure_channel('localhost:50051'),\n        prom_client_interceptor\n    )\n    # In a real app, this would be `greeter_pb2_grpc.GreeterStub(channel)`\n    stub = GreeterServicer() # Using the mock servicer for simplicity\n\n    print(\"Client sending request...\")\n    try:\n        response = stub.SayHello(greeter_pb2.HelloRequest(name='World'), context=None)\n        print(f\"Client received: {response.message}\")\n    except grpc.RpcError as e:\n        print(f\"Client received RPC error: {e.code()} - {e.details()}\")\n    print(\"Client finished.\")\n\nif __name__ == '__main__':\n    # This part requires a proper gRPC setup (proto files, generated code)\n    # For a truly runnable quickstart without proto generation, this is illustrative.\n    # To run this, you would typically run the server in one terminal and client in another.\n    # For demonstration, we'll just show the components.\n    \n    # As this cannot be fully 'runnable' without proto generation, \n    # consider this an illustrative quickstart. \n    # In a real scenario, you'd run `serve()` in one process and `run_client()` in another.\n    print(\"Quickstart shows client and server setup. Requires gRPC proto generation for full functionality.\")\n    print(\"To test metrics, run `serve()` in a separate process, then `run_client()`.\")\n    # Example of how you'd typically start them:\n    # import multiprocessing\n    # server_process = multiprocessing.Process(target=serve)\n    # server_process.start()\n    # time.sleep(2) # Give server time to start\n    # run_client()\n    # server_process.terminate()\n    # server_process.join()\n\n","lang":"python","description":"This quickstart demonstrates how to set up both gRPC server and client interceptors with `py-grpc-prometheus` to expose metrics. It includes starting a Prometheus HTTP server and enabling histogram metrics for latency tracking. Note: for a fully functional gRPC application, you would replace the placeholder `greeter_pb2` and `GreeterServicer` with generated code from your `.proto` definitions.","tag":null,"tag_description":null,"last_tested":null,"results":[]},"compatibility":{"tag":null,"tag_description":null,"last_tested":"2026-05-15","installed_version":"0.8.0","pypi_latest":"0.8.0","is_stale":false,"summary":{"python_range":"3.10–3.9","success_rate":100,"avg_install_s":2.9,"avg_import_s":0.44,"wheel_type":"wheel"},"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"py-grpc-prometheus","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.31,"mem_mb":9.4,"disk_size":"38.9M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"py-grpc-prometheus","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":2.9,"import_time_s":0.26,"mem_mb":9.4,"disk_size":"36M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"py-grpc-prometheus","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.46,"mem_mb":10.7,"disk_size":"41.1M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"py-grpc-prometheus","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":2.6,"import_time_s":0.37,"mem_mb":10.7,"disk_size":"39M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"py-grpc-prometheus","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.62,"mem_mb":10.6,"disk_size":"41.8M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"py-grpc-prometheus","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":2.8,"import_time_s":0.65,"mem_mb":10.6,"disk_size":"39M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"py-grpc-prometheus","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.64,"mem_mb":10.7,"disk_size":"41.5M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"py-grpc-prometheus","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":2.9,"import_time_s":0.58,"mem_mb":10.7,"disk_size":"39M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"py-grpc-prometheus","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.25,"mem_mb":9.4,"disk_size":"38.4M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"py-grpc-prometheus","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":3.3,"import_time_s":0.22,"mem_mb":9.4,"disk_size":"36M"}]}}