grpc-server-kit 0.1.0__py3-none-any.whl

grpc_server_kit/aio/interceptors/metrics.py

@@ -0,0 +1,104 @@
+"""Metrics interceptor for gRPC (backend-neutral recorder seam)."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import TYPE_CHECKING
+
+import grpc
+
+from grpc_server_kit.interceptors.constants import SKIPPED_HEALTH_METHODS
+from grpc_server_kit.interceptors.utils import resolve_status_code
+
+from .base import AsyncServerInterceptor, RpcCall
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Collection
+
+    from .protocols import GrpcServerMetricsProtocol
+
+__all__ = ["AsyncMetricsInterceptor"]
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncMetricsInterceptor(AsyncServerInterceptor):
+    """Interceptor that records gRPC request metrics via a metrics recorder.
+
+    Recording is delegated to any object satisfying ``GrpcServerMetricsProtocol``,
+    so the kit never imports a metrics backend directly. Skips gRPC health check
+    methods by default, and metric-recording failures never fail the request.
+    For streaming RPCs the recorded duration covers the whole stream.
+    """
+
+    def __init__(
+        self,
+        metrics: GrpcServerMetricsProtocol | None = None,
+        service_name: str = "unknown",
+        *,
+        skip_methods: Collection[str] = SKIPPED_HEALTH_METHODS,
+    ) -> None:
+        """Initialize interceptor with the metrics recorder and service name.
+
+        Args:
+            metrics: A ``GrpcServerMetricsProtocol`` implementation or None.
+            service_name: The name of the service to include in labels.
+            skip_methods: Full RPC method names to exclude from metrics
+                (defaults to the gRPC health-check methods).
+
+        Raises:
+            ValueError: If ``service_name`` is empty.
+        """
+        super().__init__(skip_methods=skip_methods)
+        if not service_name:
+            raise ValueError("service_name cannot be empty")
+        self._service_name = service_name
+        self._metrics = metrics
+
+    async def around_call(self, call: RpcCall) -> AsyncIterator[None]:
+        """Record request count and duration around the RPC."""
+        if self._metrics is None:
+            yield
+            return
+
+        start_time = time.perf_counter()
+        status = "success"
+        grpc_code = grpc.StatusCode.OK
+
+        try:
+            yield
+        except BaseException as exc:
+            status = "error"
+            grpc_code = self._classify_error(exc, call)
+            raise
+        else:
+            grpc_code = resolve_status_code(None, call.context, default=grpc.StatusCode.OK)
+        finally:
+            duration = time.perf_counter() - start_time
+            try:
+                self._metrics.record_request(
+                    service=self._service_name,
+                    method=call.method_name,
+                    status=status,
+                    grpc_code=grpc_code.name,
+                    duration=duration,
+                )
+            except Exception:
+                # Metrics errors should not fail the request
+                logger.exception("Failed to record gRPC server metrics")
+
+    def _classify_error(self, exc: BaseException, call: RpcCall) -> grpc.StatusCode:
+        """Resolve the status code to record for a failed RPC."""
+        if isinstance(exc, asyncio.CancelledError | GeneratorExit):
+            # Task cancellation / client gone mid-stream.
+            return grpc.StatusCode.CANCELLED
+        if isinstance(exc, grpc.aio.AbortError):
+            # Deliberate abort — the context carries the real status.
+            return resolve_status_code(None, call.context)
+        code = resolve_status_code(exc if isinstance(exc, grpc.RpcError) else None, call.context)
+        if code in (grpc.StatusCode.OK, grpc.StatusCode.UNKNOWN) and not isinstance(exc, grpc.RpcError):
+            # An exception with no explicit status is an internal error.
+            return grpc.StatusCode.INTERNAL
+        return code

grpc_server_kit/aio/interceptors/protocols.py

@@ -0,0 +1,54 @@
+"""Structural protocols for optional interceptor dependencies (duck-typing seams).
+
+The cross-cutting observability seams (span/tracer, error reporter) are owned by
+:mod:`grpc_server_kit.observability.protocols` and re-exported here for
+interceptor consumers. The protocols defined locally are gRPC-specific shapes
+that belong to this package.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from grpc_server_kit.observability.protocols import (
+    ErrorReporterProtocol,
+    SpanAttributeValue,
+    SpanProtocol,
+    TracerProtocol,
+)
+
+
+class GrpcServerMetricsProtocol(Protocol):
+    """Protocol for a gRPC server metrics recorder.
+
+    The kit's prometheus-backed ``GrpcServerMetrics`` satisfies this
+    structurally, as does any recorder with the same shape.
+    """
+
+    def record_request(
+        self,
+        service: str,
+        method: str,
+        status: str,
+        grpc_code: str,
+        duration: float,
+    ) -> None:
+        """Record a completed gRPC request.
+
+        Args:
+            service: Name of the service.
+            method: Name of the method.
+            status: Status of the request (success, error).
+            grpc_code: gRPC status code name.
+            duration: Request duration in seconds.
+        """
+        ...
+
+
+__all__ = [
+    "ErrorReporterProtocol",
+    "GrpcServerMetricsProtocol",
+    "SpanAttributeValue",
+    "SpanProtocol",
+    "TracerProtocol",
+]

grpc_server_kit/aio/interceptors/request_logger.py

@@ -0,0 +1,103 @@
+"""Request logger interceptor."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING, Any
+
+import grpc
+
+from grpc_server_kit.interceptors.constants import SKIPPED_HEALTH_METHODS
+from grpc_server_kit.interceptors.utils import is_server_error, resolve_status_code
+
+from .base import AsyncServerInterceptor, RpcCall
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Collection
+
+__all__ = ["AsyncRequestLoggerInterceptor"]
+
+logger = logging.getLogger(__name__)
+
+
+def _sanitize_peer(peer: str | None) -> str:
+    """Sanitize peer address to avoid logging internal IPs."""
+    if not peer:
+        return "unknown"
+    # Log only the protocol, hide the actual IP
+    for proto in ("ipv4", "ipv6", "unix"):
+        if peer.startswith(f"{proto}:"):
+            return proto
+    return "unknown"
+
+
+class AsyncRequestLoggerInterceptor(AsyncServerInterceptor):
+    """Interceptor that logs start and completion of gRPC requests.
+
+    Logs via standard logging with ``extra=`` for method and optional peer protocol.
+    Skips logging for health check methods. For streaming RPCs the completion log
+    is emitted after the full stream has been produced.
+    """
+
+    def __init__(
+        self,
+        *,
+        log_peer: bool = False,
+        log_request_on_error: bool = False,
+        skip_methods: Collection[str] = SKIPPED_HEALTH_METHODS,
+    ) -> None:
+        """Initialize interceptor.
+
+        Args:
+            log_peer: Whether to log the peer protocol of the gRPC request.
+            log_request_on_error: Whether to include ``str(request)`` in server-error
+                logs. Off by default — request payloads may contain sensitive data.
+            skip_methods: Full RPC method names to exclude from logging
+                (defaults to the gRPC health-check methods).
+        """
+        super().__init__(skip_methods=skip_methods)
+        self._log_peer = log_peer
+        self._log_request_on_error = log_request_on_error
+
+    async def around_call(self, call: RpcCall) -> AsyncIterator[None]:
+        """Log request start/completion/failure around the RPC."""
+        log_data: dict[str, Any] = {"method": call.method_name}
+        if self._log_peer:
+            log_data["peer_protocol"] = _sanitize_peer(call.context.peer())
+
+        logger.info("gRPC request started", extra=log_data)
+        try:
+            yield
+        except (asyncio.CancelledError, KeyboardInterrupt, SystemExit):
+            logger.info("gRPC request cancelled", extra={"method": call.method_name})
+            raise
+        except grpc.aio.AbortError:
+            # An interceptor or the handler aborted with an explicit status; the
+            # context carries the real code. No stack trace — the abort was deliberate.
+            status = resolve_status_code(None, call.context)
+            self._log_failure(call, status, exc_info=False)
+            raise
+        except grpc.RpcError as exc:
+            status = resolve_status_code(exc, call.context)
+            self._log_failure(call, status, exc_info=is_server_error(status))
+            raise
+        except Exception:
+            # Unexpected exceptions that are not gRPC errors yet: log with stack trace.
+            extra: dict[str, Any] = {"method": call.method_name}
+            if self._log_request_on_error:
+                extra["request"] = str(call.request)
+            logger.exception("gRPC request failed (unexpected exception)", extra=extra)
+            raise
+
+        logger.info("gRPC request completed", extra={"method": call.method_name})
+
+    def _log_failure(self, call: RpcCall, status: grpc.StatusCode, *, exc_info: bool) -> None:
+        """Log a failed RPC at a severity matching the status code."""
+        extra: dict[str, Any] = {"method": call.method_name, "status": status.name}
+        if is_server_error(status):
+            if self._log_request_on_error:
+                extra["request"] = str(call.request)
+            logger.error("gRPC request failed (server error)", extra=extra, exc_info=exc_info)
+        else:
+            logger.info("gRPC request failed (client error)", extra=extra)

grpc_server_kit/aio/interceptors/sentry.py

@@ -0,0 +1,102 @@
+"""Sentry interceptor."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+import grpc
+
+from grpc_server_kit.interceptors.constants import (
+    METHOD_KEY,
+    REQUEST_ID_KEY,
+    SENTRY_GRPC_METHOD,
+    SENTRY_REQUEST_ID,
+    SKIPPED_HEALTH_METHODS,
+    X_REQUEST_ID,
+)
+
+from .base import AsyncServerInterceptor, RpcCall
+from .metadata import get_metadata_dict
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Callable, Collection
+
+    from .protocols import ErrorReporterProtocol
+
+__all__ = ["AsyncSentryInterceptor"]
+
+
+class AsyncSentryInterceptor(AsyncServerInterceptor):
+    """Interceptor that adds error tracking and breadcrumbs.
+
+    Each RPC runs inside the reporter's isolated scope (``reporter.isolate()``),
+    so tags and breadcrumbs of concurrent RPCs never contaminate each other's
+    reports. Health-check methods are skipped by default.
+
+    Place this interceptor INSIDE the exception handler in the chain (later in
+    the interceptor list) so it observes raw handler exceptions before they are
+    mapped into ``grpc.aio.AbortError``. Deliberate aborts and gRPC errors are
+    re-raised without capture.
+    """
+
+    def __init__(
+        self,
+        sentry: ErrorReporterProtocol | None = None,
+        *,
+        capture_filter: Callable[[Exception], bool] | None = None,
+        skip_methods: Collection[str] = SKIPPED_HEALTH_METHODS,
+    ) -> None:
+        """Initialize interceptor.
+
+        Args:
+            sentry: An ``ErrorReporterProtocol`` implementation or None (no-op).
+            capture_filter: Predicate deciding whether an unexpected exception
+                is captured. None captures everything. The dishka bundle wires
+                a filter capturing only server-class errors (per the same
+                mapping the exception handler uses), so client-mapped errors
+                like ``ValueError`` do not spam the error tracker.
+            skip_methods: Full RPC method names to exclude from error tracking
+                (defaults to the gRPC health-check methods).
+        """
+        super().__init__(skip_methods=skip_methods)
+        self._sentry = sentry
+        self._capture_filter = capture_filter
+
+    async def around_call(self, call: RpcCall) -> AsyncIterator[None]:
+        """Tag the isolated scope, add a breadcrumb, and capture unexpected exceptions."""
+        if self._sentry is None:
+            yield
+            return
+
+        metadata = get_metadata_dict(call.context)
+        request_id = str(metadata.get(X_REQUEST_ID, ""))
+
+        with self._sentry.isolate():
+            self._sentry.set_tags(
+                **{
+                    SENTRY_GRPC_METHOD: call.method_name,
+                    SENTRY_REQUEST_ID: request_id,
+                }
+            )
+            self._sentry.add_breadcrumb(
+                message=f"gRPC call: {call.method_name}",
+                category="grpc",
+                level="info",
+                data={METHOD_KEY: call.method_name, REQUEST_ID_KEY: request_id},
+            )
+
+            try:
+                yield
+            except (asyncio.CancelledError, KeyboardInterrupt, SystemExit):
+                raise
+            except grpc.aio.AbortError:
+                # Deliberate abort with an explicit status — not an unexpected error.
+                raise
+            except grpc.RpcError:
+                # Re-raised gRPC errors are handled by the exception handler interceptor.
+                raise
+            except Exception as exc:
+                if self._capture_filter is None or self._capture_filter(exc):
+                    self._sentry.capture_exception(exc)
+                raise

grpc_server_kit/aio/interceptors/tracing.py

@@ -0,0 +1,130 @@
+"""Tracing interceptor (OpenTelemetry-compatible seam).
+
+Creates one span per RPC with OTel semantic-convention attributes
+(``rpc.system``, ``rpc.service``, ``rpc.method``, ``rpc.grpc.status_code``).
+Tracing is delegated to any object satisfying ``TracerProtocol`` — the
+OpenTelemetry tracer fits structurally.
+
+Note:
+    This interceptor is a lightweight seam and does not extract the incoming
+    trace context (``traceparent``) from metadata. For full distributed-tracing
+    propagation use the official instrumentation via
+    :func:`grpc_server_kit.aio.observability.instrument_aio_server` (the
+    ``[tracing]`` extra) — the two approaches compose.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+import grpc
+
+from grpc_server_kit.interceptors.constants import (
+    OTEL_REQUEST_ID,
+    OTEL_RPC_GRPC_STATUS_CODE,
+    OTEL_RPC_METHOD,
+    OTEL_RPC_SERVICE,
+    OTEL_RPC_SYSTEM,
+    SKIPPED_HEALTH_METHODS,
+    X_REQUEST_ID,
+)
+from grpc_server_kit.interceptors.utils import is_server_error, resolve_status_code
+
+from .base import AsyncServerInterceptor, RpcCall, split_method_name
+from .metadata import get_metadata_dict
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Collection
+
+    from .protocols import SpanProtocol, TracerProtocol
+
+__all__ = ["AsyncTracingInterceptor"]
+
+
+class AsyncTracingInterceptor(AsyncServerInterceptor):
+    """Interceptor that adds a tracing span to each gRPC call.
+
+    The span covers the whole RPC (including full response streams), is named
+    after the RPC method, and carries OTel semconv attributes. Health-check
+    methods are skipped by default. Exceptions are recorded against the span
+    for server-side errors — including errors already mapped to an abort by an
+    inner exception handler (recovered from ``AbortError.__context__``).
+    """
+
+    def __init__(
+        self,
+        service_name: str,
+        tracer: TracerProtocol | None = None,
+        *,
+        skip_methods: Collection[str] = SKIPPED_HEALTH_METHODS,
+    ) -> None:
+        """Initialize interceptor with the service name and tracer.
+
+        Args:
+            service_name: Fallback service name for span attributes when the RPC
+                method name cannot be parsed.
+            tracer: A ``TracerProtocol`` implementation or None (no-op).
+            skip_methods: Full RPC method names to exclude from tracing
+                (defaults to the gRPC health-check methods).
+
+        Raises:
+            ValueError: If ``service_name`` is empty.
+        """
+        super().__init__(skip_methods=skip_methods)
+        if not service_name:
+            raise ValueError("service_name cannot be empty")
+        self._service_name = service_name
+        self.tracer = tracer
+
+    async def around_call(self, call: RpcCall) -> AsyncIterator[None]:
+        """Wrap the RPC in a span with semconv attributes."""
+        if self.tracer is None:
+            yield
+            return
+
+        service, method = split_method_name(call.method_name)
+        span_name = call.method_name.removeprefix("/") or call.method_name
+
+        with self.tracer.start_as_current_span(span_name) as span:
+            span.set_attribute(OTEL_RPC_SYSTEM, "grpc")
+            span.set_attribute(OTEL_RPC_SERVICE, service or self._service_name)
+            span.set_attribute(OTEL_RPC_METHOD, method or call.method_name)
+
+            metadata = get_metadata_dict(call.context)
+            if X_REQUEST_ID in metadata:
+                span.set_attribute(OTEL_REQUEST_ID, metadata[X_REQUEST_ID])
+
+            try:
+                yield
+            except (asyncio.CancelledError, KeyboardInterrupt, SystemExit):
+                self._set_status(span, grpc.StatusCode.CANCELLED)
+                raise
+            except grpc.aio.AbortError as exc:
+                status = resolve_status_code(None, call.context)
+                self._set_status(span, status)
+                if is_server_error(status):
+                    # An inner exception handler already mapped the original
+                    # exception into this abort; recover it from the chain so
+                    # server-error spans still carry the real exception event.
+                    cause = exc.__cause__ or exc.__context__
+                    if isinstance(cause, Exception) and not isinstance(cause, grpc.aio.AbortError):
+                        span.record_exception(cause)
+                raise
+            except grpc.RpcError as exc:
+                status = resolve_status_code(exc, call.context)
+                self._set_status(span, status)
+                if is_server_error(status):
+                    span.record_exception(exc)
+                raise
+            except Exception as exc:
+                self._set_status(span, resolve_status_code(None, call.context, default=grpc.StatusCode.INTERNAL))
+                span.record_exception(exc)
+                raise
+            else:
+                self._set_status(span, resolve_status_code(None, call.context, default=grpc.StatusCode.OK))
+
+    @staticmethod
+    def _set_status(span: SpanProtocol, status: grpc.StatusCode) -> None:
+        """Set the numeric ``rpc.grpc.status_code`` semconv attribute."""
+        span.set_attribute(OTEL_RPC_GRPC_STATUS_CODE, status.value[0])

grpc_server_kit/aio/observability/__init__.py

@@ -0,0 +1,5 @@
+"""Async observability wiring (OpenTelemetry instrumentation for the aio gRPC server)."""
+
+from .tracing import instrument_aio_server, uninstrument_aio_server
+
+__all__ = ["instrument_aio_server", "uninstrument_aio_server"]

grpc_server_kit/aio/observability/tracing.py

@@ -0,0 +1,48 @@
+"""OpenTelemetry tracing wiring for the async gRPC server (``[tracing]`` extra).
+
+Thin helpers over ``GrpcAioInstrumentorServer``. Call :func:`instrument_aio_server` once
+at startup (optionally passing ``tracer_provider=...``, ``filter_=...`` etc.).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    from opentelemetry.instrumentation.grpc import GrpcAioInstrumentorServer
+
+    HAS_OTEL_GRPC = True
+except ImportError:  # pragma: no cover - exercised only when the [tracing] extra is absent
+    HAS_OTEL_GRPC = False
+
+__all__ = ["instrument_aio_server", "uninstrument_aio_server"]
+
+_MISSING_MESSAGE = (
+    "Install grpc-server-kit[tracing] (opentelemetry-instrumentation-grpc) "
+    "to instrument the gRPC server with OpenTelemetry"
+)
+
+
+def instrument_aio_server(**kwargs: Any) -> None:
+    """Instrument the async gRPC server with OpenTelemetry.
+
+    Keyword arguments are forwarded to ``GrpcAioInstrumentorServer().instrument()``
+    (e.g. ``tracer_provider``, ``filter_``).
+
+    Raises:
+        ImportError: If the ``[tracing]`` extra is not installed.
+    """
+    if not HAS_OTEL_GRPC:
+        raise ImportError(_MISSING_MESSAGE)
+    GrpcAioInstrumentorServer().instrument(**kwargs)
+
+
+def uninstrument_aio_server() -> None:
+    """Remove OpenTelemetry instrumentation from the async gRPC server.
+
+    Raises:
+        ImportError: If the ``[tracing]`` extra is not installed.
+    """
+    if not HAS_OTEL_GRPC:
+        raise ImportError(_MISSING_MESSAGE)
+    GrpcAioInstrumentorServer().uninstrument()