ni-grpc-extensions 0.1.0.dev0__tar.gz

ni_grpc_extensions-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.1
+Name: ni-grpc-extensions
+Version: 0.1.0.dev0
+Summary: gRPC Extensions
+Home-page: https://github.com/ni/ni-apis-python
+License: MIT
+Keywords: grpc,extensions,channel_pool
+Author: NI
+Author-email: opensource@ni.com
+Maintainer: Brad Keryan
+Maintainer-email: brad.keryan@emerson.com
+Requires-Python: >=3.9,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Dist: grpcio (>=1.49.0,<2.0)
+Requires-Dist: traceloggingdynamic (>=1.0) ; sys_platform == "win32"
+Project-URL: Repository, https://github.com/ni/ni-apis-python
+Description-Content-Type: text/markdown
+
+# Table of Contents
+
+- [Table of Contents](#table-of-contents)
+- [About](#about)
+  - [Operating System Support](#operating-system-support)
+  - [Python Version Support](#python-version-support)
+
+# About
+
+`ni-grpc-extensions` is a Python package that provides channel pool handling for gRPC communication.
+
+NI created and supports this package.
+
+## Operating System Support
+
+``ni-grpc-extensions` supports Windows and Linux operating systems.
+
+## Python Version Support
+
+``ni-grpc-extensions` supports CPython 3.9+.
+

ni_grpc_extensions-0.1.0.dev0/README.md

@@ -0,0 +1,20 @@
+# Table of Contents
+
+- [Table of Contents](#table-of-contents)
+- [About](#about)
+  - [Operating System Support](#operating-system-support)
+  - [Python Version Support](#python-version-support)
+
+# About
+
+`ni-grpc-extensions` is a Python package that provides channel pool handling for gRPC communication.
+
+NI created and supports this package.
+
+## Operating System Support
+
+``ni-grpc-extensions` supports Windows and Linux operating systems.
+
+## Python Version Support
+
+``ni-grpc-extensions` supports CPython 3.9+.

ni_grpc_extensions-0.1.0.dev0/pyproject.toml

@@ -0,0 +1,99 @@
+[tool.poetry]
+name = "ni-grpc-extensions"
+version = "0.1.0-dev0"
+license = "MIT"
+description = "gRPC Extensions"
+authors = ["NI <opensource@ni.com>"]
+maintainers = [
+  "Brad Keryan <brad.keryan@emerson.com>",
+  "Joe Friedrichsen <joe.friedrichsen@emerson.com>",
+]
+readme = "README.md"
+repository = "https://github.com/ni/ni-apis-python"
+keywords = ["grpc", "extensions", "channel_pool"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Manufacturing",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: Microsoft :: Windows",
+  "Operating System :: POSIX",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: Implementation :: CPython",
+]
+packages = [{include = "ni_grpc_extensions", from = "src"}]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+grpcio = {version=">=1.49.0,<2.0"}
+traceloggingdynamic = { version = ">=1.0", platform = "win32" }
+
+[tool.poetry.group.dev.dependencies]
+types-grpcio = ">=1.0"
+# Install traceloggingdynamic on Linux for type checking.
+traceloggingdynamic = { version = ">=1.0", platform = "linux" }
+
+[tool.poetry.group.lint.dependencies]
+bandit = { version = ">=1.7", extras = ["toml"] }
+ni-python-styleguide = ">=0.4.1"
+mypy = ">=1.0"
+pyright = { version = ">=1.1.400", extras = ["nodejs"] }
+
+[tool.poetry.group.test.dependencies]
+pytest = ">=7.2"
+pytest-cov = ">=4.0"
+pytest-doctestplus = ">=1.4"
+pytest-mock = ">=3.0"
+ni-measurementlink-discovery-v1-proto = { path = "../ni.measurementlink.discovery.v1.proto" }
+
+[tool.poetry.group.docs]
+optional = true
+
+[tool.poetry.group.docs.dependencies]
+# The latest Sphinx requires a recent Python version.
+Sphinx = { version = ">=8.2", python = "^3.11" }
+sphinx-rtd-theme = ">=1.0.0"
+sphinx-autoapi = ">=1.8.4"
+m2r2 = ">=0.3.2"
+toml = ">=0.10.2"
+
+[build-system]
+requires = ["poetry-core>=1.8"]
+build-backend = "poetry.core.masonry.api"
+
+
+[tool.bandit]
+skips = [
+  "B101", # assert_used
+]
+
+[tool.ni-python-styleguide]
+extend_exclude = "docs"
+
+[tool.black]
+extend-exclude = 'docs/'
+line-length = 100
+
+[tool.mypy]
+mypy_path = "src"
+files = "."
+namespace_packages = true
+strict = true
+explicit_package_bases = true
+exclude = ["docs"]
+
+[tool.pyright]
+include = ["src/", "tests/"]
+
+[tool.pytest.ini_options]
+addopts = "--doctest-modules --doctest-plus --strict-markers"
+testpaths = ["tests"]
+
+[tool.isort]
+known_first_party = ["ni_grpc_extensions"]

ni_grpc_extensions-0.1.0.dev0/src/ni_grpc_extensions/__init__.py

@@ -0,0 +1 @@
+"""gRPC extensions."""

ni_grpc_extensions-0.1.0.dev0/src/ni_grpc_extensions/_tracelogging.py

@@ -0,0 +1,210 @@
+from __future__ import annotations
+
+import ctypes
+import sys
+import uuid
+from typing import TYPE_CHECKING
+
+if sys.platform == "win32":
+    try:
+        import traceloggingdynamic
+
+        _event_provider: traceloggingdynamic.Provider | None = traceloggingdynamic.Provider(
+            b"NI-Grpc-Python"
+        )
+    except ImportError:
+        _event_provider = None
+else:
+    if TYPE_CHECKING:
+        import traceloggingdynamic
+
+    _event_provider = None
+
+_LEVEL_LOG_ALWAYS = 0
+_LEVEL_CRITICAL = 1
+_LEVEL_ERROR = 3
+_LEVEL_WARNING = 3
+_LEVEL_INFO = 4
+_LEVEL_VERBOSE = 5
+
+_OPCODE_INFO = 0
+_OPCODE_START = 1
+_OPCODE_STOP = 2
+
+_KEYWORD_NONE = 0
+_KEYWORD_GRPC = 1 << 0
+
+_TASK_GRPC_CLIENT_CALL = 1
+_TASK_GRPC_SERVER_CALL = 2
+
+
+if sys.platform == "win32":
+    # 0x00000800 = LOAD_LIBRARY_SEARCH_SYSTEM32 (Win8 or later)
+    _eventing_dll = ctypes.WinDLL("api-ms-win-eventing-provider-l1-1-0.dll", mode=0x00000800)
+
+    _EventActivityIdControl = _eventing_dll.EventActivityIdControl
+    _EventActivityIdControl.restype = ctypes.c_uint32
+    _EventActivityIdControl.argtypes = (ctypes.c_uint32, ctypes.c_void_p)
+
+    _EVENT_ACTIVITY_CTRL_GET_ID = 1
+    _EVENT_ACTIVITY_CTRL_SET_ID = 2
+    _EVENT_ACTIVITY_CTRL_CREATE_ID = 3
+    _EVENT_ACTIVITY_CTRL_GET_SET_ID = 4
+    _EVENT_ACTIVITY_CTRL_CREATE_SET_ID = 5
+
+    def _create_activity_id() -> uuid.UUID:
+        activity_bytes = (ctypes.c_byte * 16)()
+        status = _EventActivityIdControl(
+            _EVENT_ACTIVITY_CTRL_CREATE_ID, ctypes.pointer(activity_bytes)
+        )
+        if status != 0:
+            raise OSError("EventActivityIdControl error", status)
+        return uuid.UUID(bytes_le=bytes(activity_bytes))
+
+    def _get_current_thread_activity_id() -> uuid.UUID:
+        activity_bytes = (ctypes.c_byte * 16)()
+        status = _EventActivityIdControl(
+            _EVENT_ACTIVITY_CTRL_GET_ID, ctypes.pointer(activity_bytes)
+        )
+        if status != 0:
+            raise OSError("EventActivityIdControl error", status)
+        return uuid.UUID(bytes_le=bytes(activity_bytes))
+
+else:
+
+    def _create_activity_id() -> uuid.UUID:
+        return uuid.uuid4()
+
+    def _get_current_thread_activity_id() -> uuid.UUID:
+        return uuid.UUID()
+
+
+def is_enabled() -> bool:
+    """Queries whether the event provider is enabled."""
+    return _event_provider is not None and _event_provider.is_enabled()
+
+
+def log_grpc_client_call_start(method_name: str) -> uuid.UUID | None:
+    """Log when starting a gRPC client call."""
+    if _event_provider and _event_provider.is_enabled(level=_LEVEL_INFO, keyword=_KEYWORD_GRPC):
+        eb = traceloggingdynamic.EventBuilder()  # pyright: ignore[reportPossiblyUnboundVariable]
+        eb.reset(
+            b"GrpcClientCall",
+            level=_LEVEL_INFO,
+            keyword=_KEYWORD_GRPC,
+            opcode=_OPCODE_START,
+            task=_TASK_GRPC_CLIENT_CALL,
+        )
+        eb.add_str8(b"FormattedMessage", "gRPC client call starting: " + method_name)
+        activity_id = _create_activity_id()
+        related_activity_id = _get_current_thread_activity_id()
+        _event_provider.write(eb, activity_id, related_activity_id)
+        return activity_id
+    else:
+        return None
+
+
+def log_grpc_client_call_stop(method_name: str, activity_id: uuid.UUID | None = None) -> None:
+    """Log when a gRPC client call has completed."""
+    if _event_provider and _event_provider.is_enabled(level=_LEVEL_INFO, keyword=_KEYWORD_GRPC):
+        eb = traceloggingdynamic.EventBuilder()  # pyright: ignore[reportPossiblyUnboundVariable]
+        eb.reset(
+            b"GrpcClientCall",
+            level=_LEVEL_INFO,
+            keyword=_KEYWORD_GRPC,
+            opcode=_OPCODE_STOP,
+            task=_TASK_GRPC_CLIENT_CALL,
+        )
+        eb.add_str8(b"FormattedMessage", "gRPC client call complete: " + method_name)
+        _event_provider.write(eb, activity_id)
+
+
+def log_grpc_client_call_streaming_request(method_name: str) -> None:
+    """Log when a gRPC client call is sending a client-streaming request."""
+    if _event_provider and _event_provider.is_enabled(level=_LEVEL_INFO, keyword=_KEYWORD_GRPC):
+        eb = traceloggingdynamic.EventBuilder()  # pyright: ignore[reportPossiblyUnboundVariable]
+        eb.reset(
+            b"GrpcClientCallStreamingRequest",
+            level=_LEVEL_INFO,
+            keyword=_KEYWORD_GRPC,
+            opcode=_OPCODE_INFO,
+        )
+        eb.add_str8(b"FormattedMessage", "gRPC client call streaming request: " + method_name)
+        _event_provider.write(eb)
+
+
+def log_grpc_client_call_streaming_response(method_name: str) -> None:
+    """Log when a gRPC client call has received a server-streaming response."""
+    if _event_provider and _event_provider.is_enabled(level=_LEVEL_INFO, keyword=_KEYWORD_GRPC):
+        eb = traceloggingdynamic.EventBuilder()  # pyright: ignore[reportPossiblyUnboundVariable]
+        eb.reset(
+            b"GrpcClientCallStreamingResponse",
+            level=_LEVEL_INFO,
+            keyword=_KEYWORD_GRPC,
+            opcode=_OPCODE_INFO,
+        )
+        eb.add_str8(b"FormattedMessage", "gRPC client call streaming response: " + method_name)
+        _event_provider.write(eb)
+
+
+def log_grpc_server_call_start(method_name: str) -> uuid.UUID | None:
+    """Log when starting a gRPC server call."""
+    if _event_provider and _event_provider.is_enabled(level=_LEVEL_INFO, keyword=_KEYWORD_GRPC):
+        eb = traceloggingdynamic.EventBuilder()  # pyright: ignore[reportPossiblyUnboundVariable]
+        eb.reset(
+            b"GrpcServerCall",
+            level=_LEVEL_INFO,
+            keyword=_KEYWORD_GRPC,
+            opcode=_OPCODE_START,
+            task=_TASK_GRPC_SERVER_CALL,
+        )
+        eb.add_str8(b"FormattedMessage", "gRPC server call starting: " + method_name)
+        activity_id = _create_activity_id()
+        related_activity_id = _get_current_thread_activity_id()
+        _event_provider.write(eb, activity_id, related_activity_id)
+        return activity_id
+    else:
+        return None
+
+
+def log_grpc_server_call_stop(method_name: str, activity_id: uuid.UUID | None = None) -> None:
+    """Log when a gRPC server call has completed."""
+    if _event_provider and _event_provider.is_enabled(level=_LEVEL_INFO, keyword=_KEYWORD_GRPC):
+        eb = traceloggingdynamic.EventBuilder()  # pyright: ignore[reportPossiblyUnboundVariable]
+        eb.reset(
+            b"GrpcServerCall",
+            level=_LEVEL_INFO,
+            keyword=_KEYWORD_GRPC,
+            opcode=_OPCODE_STOP,
+            task=_TASK_GRPC_SERVER_CALL,
+        )
+        eb.add_str8(b"FormattedMessage", "gRPC server call complete: " + method_name)
+        _event_provider.write(eb, activity_id)
+
+
+def log_grpc_server_call_streaming_request(method_name: str) -> None:
+    """Log when a gRPC server call is sending a server-streaming request."""
+    if _event_provider and _event_provider.is_enabled(level=_LEVEL_INFO, keyword=_KEYWORD_GRPC):
+        eb = traceloggingdynamic.EventBuilder()  # pyright: ignore[reportPossiblyUnboundVariable]
+        eb.reset(
+            b"GrpcServerCallStreamingRequest",
+            level=_LEVEL_INFO,
+            keyword=_KEYWORD_GRPC,
+            opcode=_OPCODE_INFO,
+        )
+        eb.add_str8(b"FormattedMessage", "gRPC server call streaming request: " + method_name)
+        _event_provider.write(eb)
+
+
+def log_grpc_server_call_streaming_response(method_name: str) -> None:
+    """Log when a gRPC server call has received a server-streaming response."""
+    if _event_provider and _event_provider.is_enabled(level=_LEVEL_INFO, keyword=_KEYWORD_GRPC):
+        eb = traceloggingdynamic.EventBuilder()  # pyright: ignore[reportPossiblyUnboundVariable]
+        eb.reset(
+            b"GrpcServerCallStreamingResponse",
+            level=_LEVEL_INFO,
+            keyword=_KEYWORD_GRPC,
+            opcode=_OPCODE_INFO,
+        )
+        eb.add_str8(b"FormattedMessage", "gRPC server call streaming response: " + method_name)
+        _event_provider.write(eb)

ni_grpc_extensions-0.1.0.dev0/src/ni_grpc_extensions/channelpool.py

@@ -0,0 +1,116 @@
+"""gRPC channel pool."""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+import sys
+from threading import Lock
+from types import TracebackType
+from typing import TYPE_CHECKING, Literal
+from urllib.parse import urlparse
+
+import grpc
+
+from ni_grpc_extensions.loggers import ClientLogger
+
+if TYPE_CHECKING:
+    if sys.version_info >= (3, 11):
+        from typing import Self
+    else:
+        from typing_extensions import Self
+
+
+class GrpcChannelPool:
+    """Class that manages :any:`grpc.Channel` lifetimes."""
+
+    def __init__(self) -> None:
+        """Initialize the :class:`GrpcChannelPool` object."""
+        self._lock: Lock = Lock()
+        self._channel_cache: dict[str, grpc.Channel] = {}
+
+    def __enter__(self: Self) -> Self:
+        """Enter the runtime context of the GrpcChannelPool."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> Literal[False]:
+        """Exit the runtime context of the GrpcChannelPool."""
+        self.close()
+        return False
+
+    def get_channel(self, target: str) -> grpc.Channel:
+        """Return a gRPC channel.
+
+        Args:
+            target (str): The server address
+
+        """
+        new_channel = None
+        with self._lock:
+            if target not in self._channel_cache:
+                self._lock.release()
+                new_channel = self._create_channel(target)
+                self._lock.acquire()
+                if target not in self._channel_cache:
+                    self._channel_cache[target] = new_channel
+                    new_channel = None
+            channel = self._channel_cache[target]
+
+        # Close new_channel if it was not stored in _channel_cache.
+        if new_channel is not None:
+            new_channel.close()
+
+        return channel
+
+    def close(self) -> None:
+        """Close channels opened by get_channel()."""
+        with self._lock:
+            for channel in self._channel_cache.values():
+                channel.close()
+            self._channel_cache.clear()
+
+    def _create_channel(self, target: str) -> grpc.Channel:
+        options = [
+            ("grpc.max_receive_message_length", -1),
+            ("grpc.max_send_message_length", -1),
+        ]
+        if self._is_local(target):
+            options.append(("grpc.enable_http_proxy", 0))
+        channel = grpc.insecure_channel(target, options)
+        if ClientLogger.is_enabled():
+            channel = grpc.intercept_channel(channel, ClientLogger())
+        return channel
+
+    def _is_local(self, target: str) -> bool:
+        hostname = ""
+        # First, check if the target string is in URL format
+        parse_result = urlparse(target)
+        if parse_result.scheme and parse_result.hostname and parse_result.port:
+            hostname = parse_result.hostname
+        else:
+            # Next, check for target string in <host_name>:<port> format
+            match = re.match(r"^(.*):(\d+)$", target)
+            if match:
+                hostname = match.group(1)
+
+        if not hostname:
+            return False
+        if hostname == "localhost" or hostname == "LOCALHOST":
+            return True
+
+        # IPv6 addresses don't support parsing with leading/trailing brackets
+        # so we need to remove them.
+        match = re.match(r"^\[(.*)\]$", hostname)
+        if match:
+            hostname = match.group(1)
+
+        try:
+            address = ipaddress.ip_address(hostname)
+            return address.is_loopback
+        except ValueError:
+            return False

ni_grpc_extensions-0.1.0.dev0/src/ni_grpc_extensions/loggers.py

@@ -0,0 +1,506 @@
+"""gRPC logging interceptors."""
+
+# Suppress mypy errors related to interceptor base classes.
+# https://github.com/grpc/grpc/issues/40550
+# https://github.com/python/typeshed/issues/14641
+# mypy: allow-any-generics
+
+from __future__ import annotations
+
+import abc
+import functools
+import logging
+import sys
+import threading
+import time
+from collections.abc import Iterator
+from types import TracebackType
+from typing import TYPE_CHECKING, Any, Callable, Generic, TypeVar
+
+import grpc
+
+from ni_grpc_extensions import _tracelogging
+
+if TYPE_CHECKING:
+    if sys.version_info >= (3, 11):
+        from typing import Self
+    else:
+        from typing_extensions import Self
+
+_logger = logging.getLogger(__name__)
+
+
+class ClientLogger(
+    grpc.UnaryUnaryClientInterceptor,
+    grpc.UnaryStreamClientInterceptor,
+    grpc.StreamUnaryClientInterceptor,
+    grpc.StreamStreamClientInterceptor,
+):
+    """Intercepts gRPC client calls and logs them for debugging."""
+
+    @classmethod
+    def is_enabled(cls) -> bool:
+        """Indicates whether gRPC client call logging is enabled for the current log level."""
+        return _ClientCallLogger.is_enabled()
+
+    def intercept_unary_unary(
+        self,
+        continuation: Callable[
+            [grpc.ClientCallDetails, grpc._TRequest], grpc._CallFuture[grpc._TResponse]
+        ],
+        client_call_details: grpc.ClientCallDetails,
+        request: grpc._TRequest,
+    ) -> grpc._CallFuture[grpc._TResponse]:
+        """Intercept and log a unary call."""
+        if _ClientCallLogger.is_enabled():
+            call_logger = _ClientCallLogger(client_call_details.method)
+            try:
+                call = continuation(client_call_details, request)
+                return _LoggingResponseCallFuture(call_logger, call)
+            except Exception as e:
+                call_logger.close(e)
+                raise
+        else:
+            return continuation(client_call_details, request)
+
+    def intercept_unary_stream(
+        self,
+        continuation: Callable[
+            [grpc.ClientCallDetails, grpc._TRequest], grpc._CallIterator[grpc._TResponse]
+        ],
+        client_call_details: grpc.ClientCallDetails,
+        request: grpc._TRequest,
+    ) -> grpc._CallIterator[grpc._TResponse]:
+        """Intercept and log a server-streaming call."""
+        if _ClientCallLogger.is_enabled():
+            call_logger = _ClientCallLogger(client_call_details.method)
+            try:
+                call_iterator = continuation(client_call_details, request)
+                return _LoggingResponseCallIterator(call_logger, call_iterator)
+            except Exception as e:
+                call_logger.close(e)
+                raise
+        else:
+            return continuation(client_call_details, request)
+
+    def intercept_stream_unary(
+        self,
+        continuation: Callable[
+            [grpc.ClientCallDetails, Iterator[grpc._TRequest]], grpc._CallFuture[grpc._TResponse]
+        ],
+        client_call_details: grpc.ClientCallDetails,
+        request_iterator: Iterator[grpc._TRequest],
+    ) -> grpc._CallFuture[grpc._TResponse]:
+        """Intercept and log a client-streaming call."""
+        if _ClientCallLogger.is_enabled():
+            call_logger = _ClientCallLogger(client_call_details.method)
+            try:
+                call = continuation(
+                    client_call_details, _LoggingRequestIterator(call_logger, request_iterator)
+                )
+                return _LoggingResponseCallFuture(call_logger, call)
+            except Exception as e:
+                call_logger.close(e)
+                raise
+        else:
+            return continuation(client_call_details, request_iterator)
+
+    def intercept_stream_stream(
+        self,
+        continuation: Callable[
+            [grpc.ClientCallDetails, Iterator[grpc._TRequest]], grpc._CallIterator[grpc._TResponse]
+        ],
+        client_call_details: grpc.ClientCallDetails,
+        request_iterator: Iterator[grpc._TRequest],
+    ) -> grpc._CallIterator[grpc._TResponse]:
+        """Intercept and log a bidirectional streaming call."""
+        if _ClientCallLogger.is_enabled():
+            call_logger = _ClientCallLogger(client_call_details.method)
+            try:
+                call_iterator = continuation(
+                    client_call_details, _LoggingRequestIterator(call_logger, request_iterator)
+                )
+                return _LoggingResponseCallIterator(call_logger, call_iterator)
+            except Exception as e:
+                call_logger.close(e)
+                raise
+        else:
+            return continuation(client_call_details, request_iterator)
+
+
+class ServerLogger(grpc.ServerInterceptor):
+    """Intercepts gRPC server calls and logs them for debugging."""
+
+    @classmethod
+    def is_enabled(cls) -> bool:
+        """Indicates whether gRPC client call logging is enabled for the current log level."""
+        return _ServerCallLogger.is_enabled()
+
+    def intercept_service(
+        self,
+        continuation: Callable[
+            [grpc.HandlerCallDetails], grpc.RpcMethodHandler[grpc._TRequest, grpc._TResponse] | None
+        ],
+        handler_call_details: grpc.HandlerCallDetails,
+    ) -> grpc.RpcMethodHandler[grpc._TRequest, grpc._TResponse] | None:
+        """Intercept and log a server call."""
+        if _ServerCallLogger.is_enabled():
+            call_logger = _ServerCallLogger(handler_call_details.method)
+            handler = continuation(handler_call_details)
+            if handler is None:
+                return handler
+            elif handler.unary_unary:
+                return grpc.unary_unary_rpc_method_handler(
+                    functools.partial(self._log_unary_unary, call_logger, handler.unary_unary),
+                    handler.request_deserializer,
+                    handler.response_serializer,
+                )
+            elif handler.unary_stream:
+                return grpc.unary_stream_rpc_method_handler(
+                    functools.partial(self._log_unary_stream, call_logger, handler.unary_stream),
+                    handler.request_deserializer,
+                    handler.response_serializer,
+                )
+            elif handler.stream_unary:
+                return grpc.stream_unary_rpc_method_handler(
+                    functools.partial(self._log_stream_unary, call_logger, handler.stream_unary),
+                    handler.request_deserializer,
+                    handler.response_serializer,
+                )
+            elif handler.stream_stream:
+                return grpc.stream_stream_rpc_method_handler(
+                    functools.partial(self._log_stream_stream, call_logger, handler.stream_stream),
+                    handler.request_deserializer,
+                    handler.response_serializer,
+                )
+            else:
+                raise RuntimeError("Invalid RpcMethodHandler")
+        else:
+            return continuation(handler_call_details)
+
+    def _log_unary_unary(
+        self,
+        call_logger: _CallLogger,
+        handler_function: Callable[[grpc._TRequest, grpc.ServicerContext], grpc._TResponse],
+        request: grpc._TRequest,
+        context: grpc.ServicerContext,
+    ) -> grpc._TResponse:
+        with call_logger:
+            return handler_function(request, context)
+
+    def _log_unary_stream(
+        self,
+        call_logger: _CallLogger,
+        handler_function: Callable[
+            [grpc._TRequest, grpc.ServicerContext], Iterator[grpc._TResponse]
+        ],
+        request: grpc._TRequest,
+        context: grpc.ServicerContext,
+    ) -> Iterator[grpc._TResponse]:
+        try:
+            return _LoggingResponseIterator(call_logger, handler_function(request, context))
+        except Exception as e:
+            call_logger.close(e)
+            raise
+
+    def _log_stream_unary(
+        self,
+        call_logger: _CallLogger,
+        handler_function: Callable[
+            [Iterator[grpc._TRequest], grpc.ServicerContext], grpc._TResponse
+        ],
+        request_iterator: Iterator[grpc._TRequest],
+        context: grpc.ServicerContext,
+    ) -> grpc._TResponse:
+        with call_logger:
+            return handler_function(_LoggingRequestIterator(call_logger, request_iterator), context)
+
+    def _log_stream_stream(
+        self,
+        call_logger: _CallLogger,
+        handler_function: Callable[
+            [Iterator[grpc._TRequest], grpc.ServicerContext], Iterator[grpc._TResponse]
+        ],
+        request_iterator: Iterator[grpc._TRequest],
+        context: grpc.ServicerContext,
+    ) -> Iterator[grpc._TResponse]:
+        try:
+            return _LoggingResponseIterator(
+                call_logger,
+                handler_function(_LoggingRequestIterator(call_logger, request_iterator), context),
+            )
+        except Exception as e:
+            call_logger.close(e)
+            raise
+
+
+class _CallLogger(abc.ABC):
+    """Logs a single call."""
+
+    __slots__ = ["_closed"]
+
+    # As of 2023, the Python stdlib doesn't support atomic operations, so use a global lock to
+    # atomically update self._closed.
+    _lock = threading.Lock()
+
+    def __init__(self) -> None:
+        self._closed = False
+
+    def close(self, exception: BaseException | None = None) -> None:
+        # close() is idempotent to avoid duplicate logs.
+        with _CallLogger._lock:
+            if self._closed:
+                return
+            self._closed = True
+
+        self._close(exception)
+
+    @abc.abstractmethod
+    def _close(self, exception: BaseException | None) -> None:
+        raise NotImplementedError()
+
+    def __enter__(self: Self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close(exc_val)
+
+    @abc.abstractmethod
+    def log_streaming_request(self) -> None:
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def log_streaming_response(self) -> None:
+        raise NotImplementedError()
+
+
+class _ClientCallLogger(_CallLogger):
+    __slots__ = ["_method_name", "_activity_id"]
+
+    @classmethod
+    def is_enabled(cls) -> bool:
+        return _logger.isEnabledFor(logging.DEBUG) or _tracelogging.is_enabled()
+
+    def __init__(self, method_name: str) -> None:
+        super().__init__()
+        self._method_name = method_name
+        _logger.debug("gRPC client call starting: %s", self._method_name)
+        self._activity_id = _tracelogging.log_grpc_client_call_start(self._method_name)
+
+    def _close(self, exception: BaseException | None = None) -> None:
+        _logger.debug("gRPC client call complete: %s", self._method_name)
+        _tracelogging.log_grpc_client_call_stop(self._method_name, self._activity_id)
+
+    def log_streaming_request(self) -> None:
+        _logger.debug("gRPC client call streaming request: %s", self._method_name)
+        _tracelogging.log_grpc_client_call_streaming_request(self._method_name)
+
+    def log_streaming_response(self) -> None:
+        _logger.debug("gRPC client call streaming response: %s", self._method_name)
+        _tracelogging.log_grpc_client_call_streaming_response(self._method_name)
+
+
+class _ServerCallLogger(_CallLogger):
+    __slots__ = ["_method_name", "_start_time", "_activity_id"]
+
+    @classmethod
+    def is_enabled(cls) -> bool:
+        return _logger.isEnabledFor(logging.INFO) or _tracelogging.is_enabled()
+
+    def __init__(self, method_name: str) -> None:
+        super().__init__()
+        self._method_name = method_name
+        self._start_time = time.perf_counter()
+        _logger.debug("gRPC server call starting: %s", self._method_name)
+        self._activity_id = _tracelogging.log_grpc_server_call_start(self._method_name)
+
+    def _close(self, exception: BaseException | None = None) -> None:
+        if _logger.isEnabledFor(logging.INFO):
+            # For production usage, log a concise one-line summary of the call, similar to what
+            # Serilog provides for ASP.NET Core services. Don't log exception details because
+            # grpcio's logging_pool already handles this.
+            elapsed_time = time.perf_counter() - self._start_time
+            _logger.info(
+                "gRPC server call %s responded %s in %.4f ms",
+                self._method_name,
+                str(_get_status_code(exception)).replace("StatusCode.", ""),
+                elapsed_time * 1000.0,
+            )
+        _logger.debug("gRPC server call complete: %s", self._method_name)
+        _tracelogging.log_grpc_server_call_stop(self._method_name, self._activity_id)
+
+    def log_streaming_request(self) -> None:
+        _logger.debug("gRPC server call streaming request: %s", self._method_name)
+        _tracelogging.log_grpc_server_call_streaming_request(self._method_name)
+
+    def log_streaming_response(self) -> None:
+        _logger.debug("gRPC server call streaming response: %s", self._method_name)
+        _tracelogging.log_grpc_server_call_streaming_response(self._method_name)
+
+
+def _get_status_code(exception: BaseException | None) -> grpc.StatusCode:
+    if exception is None:
+        return grpc.StatusCode.OK
+    elif isinstance(exception, grpc.RpcError):
+        return exception.code()
+    else:
+        return grpc.StatusCode.UNKNOWN
+
+
+_T = TypeVar("_T")
+
+
+class _LoggingRequestIterator(Generic[_T]):
+    __slots__ = ["_call_logger", "_inner_iterator"]
+
+    def __init__(self, call_logger: _CallLogger, inner_iterator: Iterator[_T]) -> None:
+        self._call_logger = call_logger
+        self._inner_iterator = inner_iterator
+
+    def __iter__(self) -> Iterator[_T]:
+        return self
+
+    def __next__(self) -> _T:
+        request = next(self._inner_iterator)
+        self._call_logger.log_streaming_request()
+        return request
+
+
+class _LoggingResponseIterator(Generic[_T]):
+    __slots__ = ["_call_logger", "_inner_iterator"]
+
+    def __init__(self, call_logger: _CallLogger, inner_iterator: Iterator[_T]) -> None:
+        self._call_logger = call_logger
+        self._inner_iterator = inner_iterator
+
+    def __iter__(self) -> Iterator[_T]:
+        return self
+
+    def __next__(self) -> _T:
+        # For server-streaming and bidirectional RPCs, the call is complete when the response
+        # stream is closed or it throws an exception.
+        try:
+            response = next(self._inner_iterator)
+            self._call_logger.log_streaming_response()
+            return response
+        except StopIteration:
+            self._call_logger.close()
+            raise
+        except Exception as e:
+            self._call_logger.close(e)
+            raise
+
+
+if TYPE_CHECKING:
+    # These types are marked as @type_check_only and can be used only in type annotations,
+    # so we redefine them as empty classes at run time. Pyright still warns due to the behavior
+    # described in https://github.com/microsoft/pyright/issues/9934
+    _CallFuture = grpc._CallFuture  # pyright: ignore[reportGeneralTypeIssues]
+    _CallIterator = grpc._CallIterator  # pyright: ignore[reportGeneralTypeIssues]
+else:
+
+    class _CallFuture(Generic[_T]):
+        pass
+
+    class _CallIterator(Generic[_T]):
+        pass
+
+
+@grpc.Call.register
+@grpc.Future.register
+class _LoggingResponseCallFuture(_CallFuture[_T]):  # pyright: ignore[reportGeneralTypeIssues]
+    __slots__ = ["_call_logger", "_inner_call_future"]
+
+    def __init__(self, call_logger: _CallLogger, inner_call_future: grpc._CallFuture[_T]) -> None:
+        self._call_logger = call_logger
+        self._inner_call_future = inner_call_future
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._inner_call_future, name)
+
+    def result(self, timeout: float | None = None) -> _T:
+        # For unary and client-streaming RPCs, the call is complete when it returns a response or
+        # throws an exception.
+        with self._call_logger:
+            return self._inner_call_future.result(timeout)
+
+    def exception(self, timeout: float | None = None) -> Exception | None:
+        with self._call_logger:
+            return self._inner_call_future.exception(timeout)
+
+    def traceback(self, timeout: float | None = None) -> Any:
+        with self._call_logger:
+            return self._inner_call_future.traceback(timeout)
+
+    # At run time, __getattr__ forwards these to the inner CallFuture.
+    if TYPE_CHECKING:
+
+        def add_callback(self, callback: Callable[[], None]) -> bool: ...
+        def add_done_callback(
+            self, fn: Callable[[grpc.Future[grpc._TFutureValue]], None]
+        ) -> None: ...
+        def cancel(self) -> bool: ...
+        def cancelled(self) -> bool: ...
+        def code(self) -> grpc.StatusCode: ...
+        def details(self) -> str: ...
+        def done(self) -> bool: ...
+        def initial_metadata(self) -> grpc._Metadata: ...
+        def is_active(self) -> bool: ...
+        def running(self) -> bool: ...
+        def time_remaining(self) -> float: ...
+        def trailing_metadata(self) -> grpc._Metadata: ...
+
+
+@grpc.Call.register
+@grpc.Future.register
+class _LoggingResponseCallIterator(_CallIterator[_T]):  # pyright: ignore
+    __slots__ = ["_call_logger", "_inner_call_iterator"]
+
+    def __init__(
+        self, call_logger: _CallLogger, inner_call_iterator: grpc._CallIterator[_T]
+    ) -> None:
+        self._call_logger = call_logger
+        self._inner_call_iterator = inner_call_iterator
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._inner_call_iterator, name)
+
+    def __iter__(self) -> Iterator[_T]:
+        return self
+
+    def __next__(self) -> _T:
+        # For server-streaming and bidirectional RPCs, the call is complete when the response
+        # stream is closed or throws an exception.
+        try:
+            response = next(self._inner_call_iterator)
+            self._call_logger.log_streaming_response()
+            return response
+        except StopIteration:
+            self._call_logger.close()
+            raise
+        except Exception as e:
+            self._call_logger.close(e)
+            raise
+
+    # At run time, __getattr__ forwards these to the inner CallIterator.
+    if TYPE_CHECKING:
+
+        def add_callback(self, callback: Callable[[], None]) -> bool: ...
+        def add_done_callback(
+            self, fn: Callable[[grpc.Future[grpc._TFutureValue]], None]
+        ) -> None: ...
+        def cancel(self) -> bool: ...
+        def cancelled(self) -> bool: ...
+        def code(self) -> grpc.StatusCode: ...
+        def details(self) -> str: ...
+        def done(self) -> bool: ...
+        def initial_metadata(self) -> grpc._Metadata: ...
+        def is_active(self) -> bool: ...
+        def running(self) -> bool: ...
+        def time_remaining(self) -> float: ...
+        def trailing_metadata(self) -> grpc._Metadata: ...