stac-fastapi.api 6.4.1__tar.gz → 6.6.0__tar.gz

{stac_fastapi_api-6.4.1 → stac_fastapi_api-6.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: stac-fastapi-api
-Version: 6.4.1
+Version: 6.6.0
 Summary: An implementation of STAC API based on the FastAPI framework.
 Project-URL: Homepage, https://github.com/stac-utils/stac-fastapi
 Author-email: ArturoAI <engineering@arturo.ai>
@@ -17,4 +17,6 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.11
 Requires-Dist: brotli-asgi
-Requires-Dist: stac-fastapi-types~=6.4
+Requires-Dist: stac-fastapi-types~=6.6
+Provides-Extra: metrics
+Requires-Dist: prometheus-fastapi-instrumentator>=8.1.0; extra == 'metrics'

{stac_fastapi_api-6.4.1 → stac_fastapi_api-6.6.0}/pyproject.toml

@@ -32,7 +32,12 @@ classifiers = [
 dynamic = ["version"]
 dependencies = [
     "brotli_asgi",
-    "stac-fastapi.types~=6.4",
+    "stac-fastapi.types~=6.6",
+]
+
+[project.optional-dependencies]
+metrics = [
+    "prometheus-fastapi-instrumentator>=8.1.0",
 ]
 
 [dependency-groups]

{stac_fastapi_api-6.4.1 → stac_fastapi_api-6.6.0}/stac_fastapi/api/app.py

@@ -74,6 +74,10 @@ class StacApi:
         health_check:
             A Callable which return application's `health` information.
             Defaults to `def health: return {"status": "UP"}`
+        add_metrics:
+            When ``True``, instrument the app and expose Prometheus metrics at
+            ``{router_prefix}/_mgmt/metrics``. Requires
+            ``stac-fastapi-api[metrics]`` to be installed.
 
     """
 
@@ -142,6 +146,7 @@ class StacApi:
     health_check: Callable[[], dict] | Callable[[], Awaitable[dict]] = attr.ib(
         default=lambda: {"status": "UP"}
     )
+    add_metrics: bool = attr.ib(default=False)
 
     def get_extension(self, extension: type[ApiExtension]) -> ApiExtension | None:
         """Get an extension.
@@ -477,6 +482,14 @@ class StacApi:
         for middleware in self.middlewares:
             self.app.user_middleware.insert(0, middleware)
 
+        if self.add_metrics:
+            from stac_fastapi.api.metrics import instrument_app
+
+            instrument_app(
+                self.app,
+                endpoint=f"{self.app.state.router_prefix}/_mgmt/metrics",
+            )
+
         # customize route dependencies
         for scopes, dependencies in self.route_dependencies:
             self.add_route_dependencies(scopes=scopes, dependencies=dependencies)

{stac_fastapi_api-6.4.1 → stac_fastapi_api-6.6.0}/stac_fastapi/api/errors.py

@@ -27,7 +27,6 @@ DEFAULT_STATUS_CODES = {
     ConflictError: status.HTTP_409_CONFLICT,
     ForeignKeyError: status.HTTP_424_FAILED_DEPENDENCY,
     DatabaseError: status.HTTP_424_FAILED_DEPENDENCY,
-    Exception: status.HTTP_500_INTERNAL_SERVER_ERROR,
     InvalidQueryParameter: status.HTTP_400_BAD_REQUEST,
     ResponseValidationError: status.HTTP_500_INTERNAL_SERVER_ERROR,
 }

stac_fastapi_api-6.6.0/stac_fastapi/api/metrics.py

@@ -0,0 +1,131 @@
+"""Prometheus metrics with low-cardinality STAC operation labels."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+try:
+    from prometheus_client import REGISTRY, Counter, Histogram
+    from prometheus_fastapi_instrumentator import Instrumentator
+    from prometheus_fastapi_instrumentator.metrics import Info
+
+    REQUESTS: Any = Counter(
+        "http_requests_total",
+        "Total HTTP requests by STAC operation.",
+        labelnames=("operation", "method", "status"),
+        registry=REGISTRY,
+    )
+    LATENCY: Any = Histogram(
+        "http_request_duration_seconds",
+        "HTTP request latency by STAC operation.",
+        labelnames=("operation", "method"),
+        buckets=(0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, float("inf")),
+        registry=REGISTRY,
+    )
+except ImportError:  # pragma: no cover
+    REGISTRY = None  # type: ignore
+    Counter = None  # type: ignore
+    Histogram = None  # type: ignore
+    Instrumentator = None  # type: ignore
+    Info = None  # type: ignore
+    REQUESTS = None
+    LATENCY = None
+
+OPERATIONS: dict[tuple[str, str], str] = {
+    ("GET", "/"): "landing",
+    ("GET", "/conformance"): "conformance",
+    ("GET", "/collections"): "list_collections",
+    ("GET", "/collections/{collection_id}"): "get_collection",
+    ("GET", "/collections/{collection_id}/items"): "list_items",
+    ("GET", "/collections/{collection_id}/items/{item_id}"): "get_item",
+    ("GET", "/search"): "search",
+    ("POST", "/search"): "search",
+    ("POST", "/collections"): "create_collection",
+    ("PUT", "/collections/{collection_id}"): "edit_collection",
+    ("PATCH", "/collections/{collection_id}"): "edit_collection",
+    ("DELETE", "/collections/{collection_id}"): "delete_collection",
+    ("POST", "/collections/{collection_id}/items"): "create_item",
+    ("PUT", "/collections/{collection_id}/items/{item_id}"): "edit_item",
+    ("PATCH", "/collections/{collection_id}/items/{item_id}"): "edit_item",
+    ("DELETE", "/collections/{collection_id}/items/{item_id}"): "delete_item",
+    ("POST", "/collections/{collection_id}/bulk_items"): "bulk",
+    ("GET", "/queryables"): "queryables",
+    ("GET", "/collections/{collection_id}/queryables"): "queryables",
+    ("GET", "/aggregations"): "aggregations",
+    ("POST", "/aggregations"): "aggregations",
+    ("GET", "/collections/{collection_id}/aggregations"): "aggregations",
+    ("POST", "/collections/{collection_id}/aggregations"): "aggregations",
+    ("GET", "/aggregate"): "aggregate",
+    ("POST", "/aggregate"): "aggregate",
+    ("GET", "/collections/{collection_id}/aggregate"): "aggregate",
+    ("POST", "/collections/{collection_id}/aggregate"): "aggregate",
+}
+
+
+def register_operations(mapping: dict[tuple[str, str], str]) -> None:
+    """Register or override operation labels for route templates."""
+    OPERATIONS.update(mapping)
+
+
+def resolve_operation(method: str, route: str | None, router_prefix: str = "") -> str:
+    """Map a request method and route template to a STAC operation label."""
+    if not route or route == "none":
+        return "unknown"
+
+    path = route
+    prefix = (router_prefix or "").rstrip("/")
+    if prefix and path.startswith(prefix):
+        path = path[len(prefix) :] or "/"
+
+    operation = OPERATIONS.get((method.upper(), path))
+    if operation:
+        return operation
+
+    if path.startswith("/catalogs"):
+        return "catalog"
+    if "bulk" in path:
+        return "bulk"
+
+    return "unknown"
+
+
+def record_stac_metrics(info: Info) -> None:
+    """Record request count and latency using STAC operation labels."""
+    route = info.request.scope.get("route")
+    route_path = getattr(route, "path", None)
+    router_prefix = getattr(info.request.app.state, "router_prefix", "") or ""
+    operation = resolve_operation(info.method, route_path, router_prefix)
+
+    REQUESTS.labels(operation, info.method, info.modified_status).inc()
+    LATENCY.labels(operation, info.method).observe(info.modified_duration)
+
+
+def instrument_app(app: FastAPI, endpoint: str) -> None:
+    """Instrument a FastAPI app and expose Prometheus metrics.
+
+    Must be called during app construction (e.g. from ``StacApi``), before any
+    requests. Adding middleware after the app has started is not supported.
+
+    Raises:
+        ImportError: If ``stac-fastapi-api[metrics]`` is not installed.
+    """
+    if Instrumentator is None:
+        raise ImportError(
+            "Prometheus metrics require the optional dependency "
+            "`stac-fastapi-api[metrics]`. Install with: "
+            "pip install 'stac-fastapi-api[metrics]'"
+        )
+
+    (
+        Instrumentator(
+            should_group_status_codes=True,
+            should_ignore_untemplated=True,
+            excluded_handlers=[".*/_mgmt/.*"],
+        )
+        .add(record_stac_metrics)
+        .instrument(app)
+        .expose(app, endpoint=endpoint, include_in_schema=False)
+    )

{stac_fastapi_api-6.4.1 → stac_fastapi_api-6.6.0}/stac_fastapi/api/models.py

@@ -4,6 +4,7 @@ from typing import Annotated, Literal, cast
 
 import attr
 from fastapi import Path, Query
+from fastapi.responses import JSONResponse
 from pydantic import BaseModel, create_model
 from stac_pydantic.shared import BBox
 
@@ -19,12 +20,6 @@ from stac_fastapi.types.search import (
     _validate_datetime,
 )
 
-try:
-    import orjson  # noqa
-    from fastapi.responses import ORJSONResponse as JSONResponse
-except ImportError:  # pragma: nocover
-    from starlette.responses import JSONResponse  # type: ignore [assignment]
-
 
 def create_request_model(
     model_name="SearchGetRequest",

{stac_fastapi_api-6.4.1 → stac_fastapi_api-6.6.0}/stac_fastapi/api/version.py

@@ -1,3 +1,3 @@
 """Library version."""
 
-__version__ = "6.4.1"
+__version__ = "6.6.0"