add: Python otel plugin codelab (#6)

Add Python observability codelab.

Author: XuanWang-Amos

codelabs/gRPC_Python_OpenTelemetry_Plugin/README.md

@@ -0,0 +1,19 @@
+# gRPC Python OpenTelemetry Plugin
+
+Get hands-on with gRPC's OpenTelemetry plugin for Python in this interactive codelab! <!-- TODO(arvindbr8): Insert link once codelab is published. -->
+
+
+Designed for developers already familiar with gRPC and wanting to learn how to instrument their gRPC usage with OpenTelemetry.
+
+#### You'll learn how to:
+
+- setup gRPC's OpenTelemetry plugin in gRPC Python.
+- setup Prometheus exporter with OpenTelemetry.
+- explore collected metrics using Prometheus.
+
+## How to use this directory
+
+- [start_here](start_here/) directory serves as a starting point for the
+codelab. 
+- [completed](completed/) directory showcases the finished code, giving you a
+peek of how the final implementation should look like.

codelabs/gRPC_Python_OpenTelemetry_Plugin/completed/helloworld_pb2.py

@@ -0,0 +1,17 @@
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from typing import ClassVar as _ClassVar, Optional as _Optional
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class HelloReply(_message.Message):
+    __slots__ = ["message"]
+    MESSAGE_FIELD_NUMBER: _ClassVar[int]
+    message: str
+    def __init__(self, message: _Optional[str] = ...) -> None: ...
+
+class HelloRequest(_message.Message):
+    __slots__ = ["name"]
+    NAME_FIELD_NUMBER: _ClassVar[int]
+    name: str
+    def __init__(self, name: _Optional[str] = ...) -> None: ...

codelabs/gRPC_Python_OpenTelemetry_Plugin/completed/helloworld_pb2.pyi

@@ -0,0 +1,70 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+
+import helloworld_pb2 as helloworld__pb2
+
+
+class GreeterStub(object):
+    """The greeting service definition.
+    """
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.SayHello = channel.unary_unary(
+                '/helloworld.Greeter/SayHello',
+                request_serializer=helloworld__pb2.HelloRequest.SerializeToString,
+                response_deserializer=helloworld__pb2.HelloReply.FromString,
+                )
+
+
+class GreeterServicer(object):
+    """The greeting service definition.
+    """
+
+    def SayHello(self, request, context):
+        """Sends a greeting
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_GreeterServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'SayHello': grpc.unary_unary_rpc_method_handler(
+                    servicer.SayHello,
+                    request_deserializer=helloworld__pb2.HelloRequest.FromString,
+                    response_serializer=helloworld__pb2.HelloReply.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'helloworld.Greeter', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+
+
+ # This class is part of an EXPERIMENTAL API.
+class Greeter(object):
+    """The greeting service definition.
+    """
+
+    @staticmethod
+    def SayHello(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(request, target, '/helloworld.Greeter/SayHello',
+            helloworld__pb2.HelloRequest.SerializeToString,
+            helloworld__pb2.HelloReply.FromString,
+            options, channel_credentials,
+            insecure, call_credentials, compression, wait_for_ready, timeout, metadata)

codelabs/gRPC_Python_OpenTelemetry_Plugin/completed/helloworld_pb2_grpc.py

@@ -0,0 +1,61 @@
+# Copyright 2024 gRPC authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""gRPC Python helloworld.Greeter client for observability codelab."""
+
+import logging
+
+import grpc
+import grpc_observability
+import helloworld_pb2
+import helloworld_pb2_grpc
+from opentelemetry.exporter.prometheus import PrometheusMetricReader
+from opentelemetry.sdk.metrics import MeterProvider
+from prometheus_client import start_http_server
+
+_SERVER_PORT = "50051"
+_PROMETHEUS_PORT = 9465
+
+
+def run():
+    # Start Prometheus client
+    start_http_server(port=_PROMETHEUS_PORT, addr="0.0.0.0")
+    # The default histogram boundaries are not granular enough for RPCs. Consider
+    # override the "grpc.client.attempt.duration" view similar to csm example.
+    # Link: https://github.com/grpc/grpc/blob/7407dbf21dbab125ab5eb778daab6182c009b069/examples/python/observability/csm/csm_greeter_client.py#L71C40-L71C53
+    meter_provider = MeterProvider(metric_readers=[PrometheusMetricReader()])
+
+    otel_plugin = grpc_observability.OpenTelemetryPlugin(
+        meter_provider=meter_provider
+    )
+    otel_plugin.register_global()
+
+    with grpc.insecure_channel(target=f"localhost:{_SERVER_PORT}") as channel:
+        stub = helloworld_pb2_grpc.GreeterStub(channel)
+        # Continuously send RPCs.
+        while True:
+            try:
+                response = stub.SayHello(
+                    helloworld_pb2.HelloRequest(name="You")
+                )
+                print(f"Greeter client received: {response.message}")
+            except grpc.RpcError as rpc_error:
+                print("Call failed with code: ", rpc_error.code())
+
+    # Deregister is not called in this example, but this is required to clean up.
+    otel_plugin.deregister_global()
+
+
+if __name__ == "__main__":
+    logging.basicConfig()
+    run()

codelabs/gRPC_Python_OpenTelemetry_Plugin/completed/observability_greeter_client.py

@@ -0,0 +1,66 @@
+# Copyright 2024 gRPC authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""The Python implementation of the GRPC helloworld.Greeter server for observability codelab."""
+
+from concurrent import futures
+import logging
+
+import grpc
+import grpc_observability
+import helloworld_pb2
+import helloworld_pb2_grpc
+from opentelemetry.exporter.prometheus import PrometheusMetricReader
+from opentelemetry.sdk.metrics import MeterProvider
+from prometheus_client import start_http_server
+
+_SERVER_PORT = "50051"
+_PROMETHEUS_PORT = 9464
+
+
+class Greeter(helloworld_pb2_grpc.GreeterServicer):
+    def SayHello(self, request, context):
+        message = request.name
+        return helloworld_pb2.HelloReply(message=f"Hello {message}")
+
+
+def serve():
+    # Start Prometheus client
+    start_http_server(port=_PROMETHEUS_PORT, addr="0.0.0.0")
+    # The default histogram boundaries are not granular enough for RPCs. Consider
+    # override the "grpc.client.attempt.duration" view similar to csm example.
+    # Link: https://github.com/grpc/grpc/blob/7407dbf21dbab125ab5eb778daab6182c009b069/examples/python/observability/csm/csm_greeter_client.py#L71C40-L71C53
+    meter_provider = MeterProvider(metric_readers=[PrometheusMetricReader()])
+
+    otel_plugin = grpc_observability.OpenTelemetryPlugin(
+        meter_provider=meter_provider
+    )
+    otel_plugin.register_global()
+
+    server = grpc.server(
+        thread_pool=futures.ThreadPoolExecutor(max_workers=10),
+    )
+    helloworld_pb2_grpc.add_GreeterServicer_to_server(Greeter(), server)
+    server.add_insecure_port("[::]:" + _SERVER_PORT)
+    server.start()
+    print("Server started, listening on " + _SERVER_PORT)
+
+    server.wait_for_termination()
+
+    # Deregister is not called in this example, but this is required to clean up.
+    otel_plugin.deregister_global()
+
+
+if __name__ == "__main__":
+    logging.basicConfig()
+    serve()

codelabs/gRPC_Python_OpenTelemetry_Plugin/completed/observability_greeter_server.py

@@ -0,0 +1,6 @@
+grpcio>=1.65.5
+protobuf>=5.26.1,<6.0dev
+grpcio-observability>=1.65.5
+opentelemetry-sdk==1.26.0
+opentelemetry-api==1.26.0
+opentelemetry-exporter-prometheus==0.47b0

codelabs/gRPC_Python_OpenTelemetry_Plugin/requirements.txt

@@ -0,0 +1,17 @@
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from typing import ClassVar as _ClassVar, Optional as _Optional
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class HelloReply(_message.Message):
+    __slots__ = ["message"]
+    MESSAGE_FIELD_NUMBER: _ClassVar[int]
+    message: str
+    def __init__(self, message: _Optional[str] = ...) -> None: ...
+
+class HelloRequest(_message.Message):
+    __slots__ = ["name"]
+    NAME_FIELD_NUMBER: _ClassVar[int]
+    name: str
+    def __init__(self, name: _Optional[str] = ...) -> None: ...

codelabs/gRPC_Python_OpenTelemetry_Plugin/start_here/helloworld_pb2.py

@@ -0,0 +1,70 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+
+import helloworld_pb2 as helloworld__pb2
+
+
+class GreeterStub(object):
+    """The greeting service definition.
+    """
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.SayHello = channel.unary_unary(
+                '/helloworld.Greeter/SayHello',
+                request_serializer=helloworld__pb2.HelloRequest.SerializeToString,
+                response_deserializer=helloworld__pb2.HelloReply.FromString,
+                )
+
+
+class GreeterServicer(object):
+    """The greeting service definition.
+    """
+
+    def SayHello(self, request, context):
+        """Sends a greeting
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_GreeterServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'SayHello': grpc.unary_unary_rpc_method_handler(
+                    servicer.SayHello,
+                    request_deserializer=helloworld__pb2.HelloRequest.FromString,
+                    response_serializer=helloworld__pb2.HelloReply.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'helloworld.Greeter', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+
+
+ # This class is part of an EXPERIMENTAL API.
+class Greeter(object):
+    """The greeting service definition.
+    """
+
+    @staticmethod
+    def SayHello(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(request, target, '/helloworld.Greeter/SayHello',
+            helloworld__pb2.HelloRequest.SerializeToString,
+            helloworld__pb2.HelloReply.FromString,
+            options, channel_credentials,
+            insecure, call_credentials, compression, wait_for_ready, timeout, metadata)