reqly 0.3.0__tar.gz → 0.5.0__tar.gz

{reqly-0.3.0 → reqly-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reqly
-Version: 0.3.0
+Version: 0.5.0
 Summary: Self-hosted API monitoring for FastAPI, Flask, Django, Starlette and Litestar in two lines: latency percentiles, error rates and release tracking per route, with deploy-aware alerts and weekly AI anomaly reports.
 Author: Tanish Poddar
 License-Expression: GPL-3.0-or-later
@@ -110,6 +110,34 @@ MIDDLEWARE = [
 REQLY = {"service_name": "checkout-api", "api_key": "your-ingest-key"}  # optional
 ```
 
+**Any other WSGI or ASGI app** (Bottle, Pyramid, Falcon, CherryPy, a bare ASGI app) — wrap it
+and serve the result. A `route_resolver` returns the route template, because only the framework
+knows it; without one every request is recorded as `__unmatched__`, never as a raw path:
+
+```python
+app = reqly.instrument_wsgi(
+    app, service_name="checkout-api",
+    route_resolver=lambda environ: environ["bottle.route"].rule,  # Bottle
+)
+# Pyramid: environ["bfg.routes.route"].pattern; ASGI: reqly.instrument_asgi(app, route_resolver=...)
+```
+
+**Who is calling** — tag each request with its API consumer. The id is hashed (HMAC-SHA256
+with your secret salt) before it leaves the app:
+
+```python
+reqly.instrument(app, consumer_header="X-API-Key", consumer_salt=os.environ["REQLY_CONSUMER_SALT"])
+# or any logic: consumer=lambda info: info.headers.get("x-tenant-id")
+```
+
+**LLM cost per route** — record token usage where you call a model; the collector prices it:
+
+```python
+completion = client.chat.completions.create(model="gpt-4o-mini", messages=messages)
+reqly.record_llm_response(completion)   # OpenAI / Anthropic responses, or:
+reqly.record_llm_usage("gpt-4o-mini", input_tokens=1200, output_tokens=240)
+```
+
 `instrument()` detects the framework by itself — no decorators, no middleware to wire up.
 Routes are recorded as templates in one style across frameworks: Django's
 `users/<int:pk>/` and DRF's `^users/(?P<pk>[^/.]+)/$` both become `/users/{pk}/`.
@@ -131,7 +159,12 @@ In the Reqly dashboard and collector:
 - **Deploy markers and per-release health** — each release's error rate and p95
 - **Hourly alerts** to Slack, Discord or a webhook when a route breaks from its usual
   weekday-hour pattern, with **root-cause hints**
-- **Weekly AI report** — statistics find the anomalies, Groq (Llama 3.3-70b) writes the
+- **Top consumers** — requests and error rate per API client, and which clients an incident
+  hit (in the alert itself)
+- **LLM cost per route** — tokens and estimated spend per route and model
+- **API surface vs your OpenAPI spec** — undocumented endpoints that get traffic, documented
+  ones nobody calls, and deprecated ones still in use (`push_openapi=True`)
+- **Weekly AI report** — statistics find the anomalies, Groq (gpt-oss-120b) writes the
   summary; plain-text fallback without an API key
 
 An alert from the demo data looks like this:
@@ -164,6 +197,11 @@ Resolution order: **argument → environment variable → default**.
 | `max_batch_size` | `REQLY_MAX_BATCH_SIZE` | `200` |
 | `max_queue_size` | `REQLY_MAX_QUEUE_SIZE` | `2000` |
 | `ignore_routes` | `REQLY_IGNORE_ROUTES` (comma-separated) | `/health,/metrics` |
+| `consumer_header` | `REQLY_CONSUMER_HEADER` | `None` — header that identifies the caller, e.g. `X-API-Key` |
+| `consumer` | — | `None` — `callable(RequestInfo) -> str \| None`, instead of a header |
+| `consumer_salt` | `REQLY_CONSUMER_SALT` | `None` — secret for hashing consumer ids (set it) |
+| `hash_consumer` | `REQLY_HASH_CONSUMER` | `True` — `False` sends ids unhashed (only for non-secret ids) |
+| `push_openapi` | `REQLY_PUSH_OPENAPI` | `False` — upload the app's OpenAPI spec (FastAPI, Litestar) on the first request |
 | `capture_request_body` | `REQLY_CAPTURE_REQUEST_BODY` | `False` (not implemented yet) |
 
 With `sample_rate` below 1.0, request counts in the dashboard are the sampled volume;
@@ -201,7 +239,8 @@ are shipped instead of silently queuing forever.
 | Litestar | 2.0+ |
 | Flask | 2.3+ |
 | Django | 4.2+, sync and async views; DRF and Django Ninja |
-| Collector | any version; `release`, `environment` and body sizes are stored by collector 0.3.0+ and ignored by older ones |
+| Other WSGI / ASGI | any, with `instrument_wsgi()` / `instrument_asgi()` and a `route_resolver` |
+| Collector | any version; `release`, `environment` and body sizes are stored by collector 0.3.0+ and ignored by older ones; `push_openapi` needs 0.7.0+; consumer and LLM views need 0.8.0+ |
 
 ## Self-hosting the collector
 

{reqly-0.3.0 → reqly-0.5.0}/README.md

@@ -63,6 +63,34 @@ MIDDLEWARE = [
 REQLY = {"service_name": "checkout-api", "api_key": "your-ingest-key"}  # optional
 ```
 
+**Any other WSGI or ASGI app** (Bottle, Pyramid, Falcon, CherryPy, a bare ASGI app) — wrap it
+and serve the result. A `route_resolver` returns the route template, because only the framework
+knows it; without one every request is recorded as `__unmatched__`, never as a raw path:
+
+```python
+app = reqly.instrument_wsgi(
+    app, service_name="checkout-api",
+    route_resolver=lambda environ: environ["bottle.route"].rule,  # Bottle
+)
+# Pyramid: environ["bfg.routes.route"].pattern; ASGI: reqly.instrument_asgi(app, route_resolver=...)
+```
+
+**Who is calling** — tag each request with its API consumer. The id is hashed (HMAC-SHA256
+with your secret salt) before it leaves the app:
+
+```python
+reqly.instrument(app, consumer_header="X-API-Key", consumer_salt=os.environ["REQLY_CONSUMER_SALT"])
+# or any logic: consumer=lambda info: info.headers.get("x-tenant-id")
+```
+
+**LLM cost per route** — record token usage where you call a model; the collector prices it:
+
+```python
+completion = client.chat.completions.create(model="gpt-4o-mini", messages=messages)
+reqly.record_llm_response(completion)   # OpenAI / Anthropic responses, or:
+reqly.record_llm_usage("gpt-4o-mini", input_tokens=1200, output_tokens=240)
+```
+
 `instrument()` detects the framework by itself — no decorators, no middleware to wire up.
 Routes are recorded as templates in one style across frameworks: Django's
 `users/<int:pk>/` and DRF's `^users/(?P<pk>[^/.]+)/$` both become `/users/{pk}/`.
@@ -84,7 +112,12 @@ In the Reqly dashboard and collector:
 - **Deploy markers and per-release health** — each release's error rate and p95
 - **Hourly alerts** to Slack, Discord or a webhook when a route breaks from its usual
   weekday-hour pattern, with **root-cause hints**
-- **Weekly AI report** — statistics find the anomalies, Groq (Llama 3.3-70b) writes the
+- **Top consumers** — requests and error rate per API client, and which clients an incident
+  hit (in the alert itself)
+- **LLM cost per route** — tokens and estimated spend per route and model
+- **API surface vs your OpenAPI spec** — undocumented endpoints that get traffic, documented
+  ones nobody calls, and deprecated ones still in use (`push_openapi=True`)
+- **Weekly AI report** — statistics find the anomalies, Groq (gpt-oss-120b) writes the
   summary; plain-text fallback without an API key
 
 An alert from the demo data looks like this:
@@ -117,6 +150,11 @@ Resolution order: **argument → environment variable → default**.
 | `max_batch_size` | `REQLY_MAX_BATCH_SIZE` | `200` |
 | `max_queue_size` | `REQLY_MAX_QUEUE_SIZE` | `2000` |
 | `ignore_routes` | `REQLY_IGNORE_ROUTES` (comma-separated) | `/health,/metrics` |
+| `consumer_header` | `REQLY_CONSUMER_HEADER` | `None` — header that identifies the caller, e.g. `X-API-Key` |
+| `consumer` | — | `None` — `callable(RequestInfo) -> str \| None`, instead of a header |
+| `consumer_salt` | `REQLY_CONSUMER_SALT` | `None` — secret for hashing consumer ids (set it) |
+| `hash_consumer` | `REQLY_HASH_CONSUMER` | `True` — `False` sends ids unhashed (only for non-secret ids) |
+| `push_openapi` | `REQLY_PUSH_OPENAPI` | `False` — upload the app's OpenAPI spec (FastAPI, Litestar) on the first request |
 | `capture_request_body` | `REQLY_CAPTURE_REQUEST_BODY` | `False` (not implemented yet) |
 
 With `sample_rate` below 1.0, request counts in the dashboard are the sampled volume;
@@ -154,7 +192,8 @@ are shipped instead of silently queuing forever.
 | Litestar | 2.0+ |
 | Flask | 2.3+ |
 | Django | 4.2+, sync and async views; DRF and Django Ninja |
-| Collector | any version; `release`, `environment` and body sizes are stored by collector 0.3.0+ and ignored by older ones |
+| Other WSGI / ASGI | any, with `instrument_wsgi()` / `instrument_asgi()` and a `route_resolver` |
+| Collector | any version; `release`, `environment` and body sizes are stored by collector 0.3.0+ and ignored by older ones; `push_openapi` needs 0.7.0+; consumer and LLM views need 0.8.0+ |
 
 ## Self-hosting the collector
 

{reqly-0.3.0 → reqly-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reqly"
-version = "0.3.0"
+version = "0.5.0"
 description = "Self-hosted API monitoring for FastAPI, Flask, Django, Starlette and Litestar in two lines: latency percentiles, error rates and release tracking per route, with deploy-aware alerts and weekly AI anomaly reports."
 readme = "README.md"
 requires-python = ">=3.9"

{reqly-0.3.0 → reqly-0.5.0}/reqly/__init__.py

@@ -4,10 +4,18 @@ import logging
 
 from .core.client import ReqlyClient
 from .core.config import Config, _get_sdk_version
+from .core.request_context import RequestInfo, record_llm_response, record_llm_usage
 
 __version__ = _get_sdk_version()
 
-__all__ = ["instrument"]
+__all__ = [
+    "instrument",
+    "instrument_asgi",
+    "instrument_wsgi",
+    "record_llm_usage",
+    "record_llm_response",
+    "RequestInfo",
+]
 
 logger = logging.getLogger("reqly")
 
@@ -34,10 +42,24 @@ def _detect_framework(app) -> str:
     raise TypeError(
         "reqly.instrument(): could not detect framework for app of type "
         f"{type(app)!r}. Supported: FastAPI, Starlette, Litestar, Flask "
-        "(Django: add reqly.integrations.django.ReqlyMiddleware to MIDDLEWARE)."
+        "(Django: add reqly.integrations.django.ReqlyMiddleware to MIDDLEWARE; any other "
+        "WSGI/ASGI app: reqly.instrument_wsgi() / reqly.instrument_asgi())."
     )
 
 
+def _enable_openapi_push(app, framework: str, client: ReqlyClient) -> None:
+    if framework == "fastapi":
+        client.enable_openapi_push(app.openapi)
+    elif framework == "litestar":
+        client.enable_openapi_push(lambda: app.openapi_schema.to_schema())
+    else:
+        logger.warning(
+            "reqly: push_openapi needs an app that generates its own spec (FastAPI, Litestar); "
+            "for %s, upload the spec with PUT /v1/services/<service>/openapi instead",
+            framework,
+        )
+
+
 def instrument(
     app,
     *,
@@ -52,6 +74,11 @@ def instrument(
     capture_request_body: bool | None = None,
     release: str | None = None,
     environment: str | None = None,
+    push_openapi: bool | None = None,
+    consumer_header: str | None = None,
+    consumer=None,
+    consumer_salt: str | None = None,
+    hash_consumer: bool | None = None,
 ) -> ReqlyClient | None:
     """Instrument a FastAPI, Starlette, Litestar or Flask app with one line.
     (Django: add ``reqly.integrations.django.ReqlyMiddleware`` to MIDDLEWARE.)
@@ -60,6 +87,16 @@ def instrument(
     environment variable (REQLY_*) > default. See core.config.Config
     for the full list of environment variables.
 
+    Consumers (who is calling): ``consumer_header="X-API-Key"`` or
+    ``consumer=lambda info: ...`` (gets a RequestInfo, returns an id or
+    None). Ids are HMAC-SHA256-hashed with ``consumer_salt``
+    (REQLY_CONSUMER_SALT) before leaving the app unless ``hash_consumer=False``.
+
+    ``push_openapi=True`` (or REQLY_PUSH_OPENAPI=true) uploads the app's
+    OpenAPI spec (FastAPI, Litestar) to the collector on the first request,
+    so the dashboard can show undocumented, unused and deprecated-but-used
+    endpoints.
+
     This function itself is guarded: a failure to detect the framework or
     initialize the client is logged and the app is returned uninstrumented
     rather than raising, so adding Reqly can never be the reason an
@@ -87,8 +124,15 @@ def instrument(
             capture_request_body=capture_request_body,
             release=release,
             environment=environment,
+            push_openapi=push_openapi,
+            consumer_header=consumer_header,
+            consumer=consumer,
+            consumer_salt=consumer_salt,
+            hash_consumer=hash_consumer,
         )
         client = ReqlyClient(config)
+        if config.push_openapi:
+            _enable_openapi_push(app, framework, client)
 
         if config.capture_request_body:
             logger.warning(
@@ -121,3 +165,58 @@ def instrument(
             exc_info=True,
         )
         return None
+
+
+_GENERIC_OPTIONS = (
+    "service_name", "collector_url", "api_key", "sample_rate", "flush_interval_seconds",
+    "max_batch_size", "max_queue_size", "ignore_routes", "capture_request_body",
+    "release", "environment", "consumer_header", "consumer", "consumer_salt", "hash_consumer",
+)
+
+
+def _generic_client(kind: str, route_resolver, options: dict) -> ReqlyClient:
+    if route_resolver is None:
+        logger.warning(
+            "reqly: instrument_%s() without route_resolver records every request as "
+            "__unmatched__; pass a function that returns the route template", kind,
+        )
+    if options.pop("push_openapi", None):
+        logger.warning("reqly: push_openapi is not available for generic %s apps", kind.upper())
+    unknown = set(options) - set(_GENERIC_OPTIONS)
+    if unknown:
+        logger.warning("reqly: instrument_%s() ignoring unknown options %s", kind, sorted(unknown))
+    return ReqlyClient(Config.resolve(**{key: options.get(key) for key in _GENERIC_OPTIONS}))
+
+
+def instrument_wsgi(app, *, route_resolver=None, **options):
+    """Wrap any WSGI app (Bottle, Pyramid, Falcon, CherryPy...) and return
+    the wrapped app -- serve that one::
+
+        app = reqly.instrument_wsgi(app, service_name="api",
+                                    route_resolver=lambda environ: environ["bottle.route"].rule)
+
+    ``route_resolver(environ)`` runs after the app handled the request and
+    returns the route template or None. ``options`` are those of
+    ``instrument()``. Like ``instrument()``, a failure leaves the app
+    unwrapped instead of raising."""
+    try:
+        from .integrations.wsgi import ReqlyWSGIMiddleware
+
+        return ReqlyWSGIMiddleware(app, _generic_client("wsgi", route_resolver, options), route_resolver)
+    except Exception:
+        logger.warning("reqly: instrument_wsgi() failed, app will run uninstrumented", exc_info=True)
+        return app
+
+
+def instrument_asgi(app, *, route_resolver=None, **options):
+    """Wrap any ASGI app and return the wrapped app. ``route_resolver(scope)``
+    gets a copy of the scope as it arrived; a template the framework puts in
+    ``scope["route"]`` or ``scope["path_template"]`` is used first."""
+    try:
+        from .integrations.fastapi import ReqlyASGIMiddleware
+
+        client = _generic_client("asgi", route_resolver, options)
+        return ReqlyASGIMiddleware(app, client, route_resolver)
+    except Exception:
+        logger.warning("reqly: instrument_asgi() failed, app will run uninstrumented", exc_info=True)
+        return app

{reqly-0.3.0 → reqly-0.5.0}/reqly/core/capture.py

@@ -31,6 +31,10 @@ class RequestEvent:
     host: str = _HOSTNAME
     request_bytes: int | None = None
     response_bytes: int | None = None
+    consumer_id: str | None = None
+    llm_model: str | None = None
+    llm_input_tokens: int | None = None
+    llm_output_tokens: int | None = None
     sdk_version: str = field(default_factory=_get_sdk_version)
 
     def to_dict(self) -> dict:
@@ -59,7 +63,10 @@ def build_event(
     sdk_version: str,
     request_bytes: int | None = None,
     response_bytes: int | None = None,
+    consumer_id: str | None = None,
+    llm: tuple[str, int, int] | None = None,
 ) -> RequestEvent:
+    llm_model, llm_input_tokens, llm_output_tokens = llm if llm else (None, None, None)
     return RequestEvent(
         service_name=service_name,
         method=method,
@@ -71,4 +78,8 @@ def build_event(
         sdk_version=sdk_version,
         request_bytes=request_bytes,
         response_bytes=response_bytes,
+        consumer_id=consumer_id,
+        llm_model=llm_model,
+        llm_input_tokens=llm_input_tokens,
+        llm_output_tokens=llm_output_tokens,
     )

{reqly-0.3.0 → reqly-0.5.0}/reqly/core/client.py

@@ -5,6 +5,8 @@ import logging
 from .buffer import EventBuffer
 from .capture import build_event
 from .config import Config
+from .openapi_push import OpenAPIPusher
+from .request_context import ConsumerResolver
 from .sampling import Sampler
 from .shipper import Shipper
 
@@ -26,8 +28,17 @@ class ReqlyClient:
         self.config = config
         self._disabled = False
         self._ignore_routes = set(config.ignore_routes)
+        self._openapi_pusher: OpenAPIPusher | None = None
+        self._consumers: ConsumerResolver | None = None
 
         try:
+            if config.consumer_header or config.consumer is not None:
+                self._consumers = ConsumerResolver(
+                    header=config.consumer_header,
+                    func=config.consumer,
+                    salt=config.consumer_salt,
+                    hash_ids=config.hash_consumer,
+                )
             self._sampler = Sampler(config.sample_rate)
             shipper = Shipper(
                 collector_url=config.collector_url,
@@ -61,15 +72,24 @@ class ReqlyClient:
         error_type: str | None,
         request_bytes: int | None = None,
         response_bytes: int | None = None,
+        request_info=None,
+        llm: tuple[str, int, int] | None = None,
     ) -> None:
+        """``request_info``: zero-argument callable returning a RequestInfo,
+        only called when consumer tracking is on. ``llm``: (model,
+        input_tokens, output_tokens) recorded during the request."""
         if self._disabled:
             return
         try:
+            if self._openapi_pusher is not None:
+                self._openapi_pusher.maybe_push()
             if route in self._ignore_routes:
                 return
             if not self._sampler.should_sample():
                 return
             event = build_event(
+                consumer_id=self._consumer_id(request_info),
+                llm=llm,
                 service_name=self.config.service_name,
                 method=method,
                 route=route,
@@ -89,6 +109,26 @@ class ReqlyClient:
             )
             self._disabled = True
 
+    def _consumer_id(self, request_info) -> str | None:
+        if self._consumers is None or request_info is None:
+            return None
+        try:
+            return self._consumers.resolve(request_info)
+        except Exception:
+            # A failing consumer= callable costs the consumer id, not the event.
+            logger.warning("reqly: consumer lookup failed", exc_info=True)
+            return None
+
+    def enable_openapi_push(self, spec_factory) -> None:
+        """Upload ``spec_factory()`` (the app's OpenAPI document) to the
+        collector once, when the first request is recorded."""
+        self._openapi_pusher = OpenAPIPusher(
+            spec_factory=spec_factory,
+            collector_url=self.config.collector_url,
+            api_key=self.config.api_key,
+            service_name=self.config.service_name,
+        )
+
     def stats(self) -> dict:
         if self._disabled:
             return {"disabled": True}

{reqly-0.3.0 → reqly-0.5.0}/reqly/core/config.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import os
 from dataclasses import dataclass, field
+from typing import Any
 from importlib.metadata import PackageNotFoundError, version as _pkg_version
 
 
@@ -86,6 +87,11 @@ class Config:
     capture_request_body: bool = False
     release: str | None = None
     environment: str | None = None
+    push_openapi: bool = False
+    consumer_header: str | None = None
+    consumer: Any = None  # callable(RequestInfo) -> str | None
+    consumer_salt: str | None = None
+    hash_consumer: bool = True
     sdk_version: str = field(default_factory=_get_sdk_version)
 
     @classmethod
@@ -102,6 +108,11 @@ class Config:
         capture_request_body: bool | None,
         release: str | None = None,
         environment: str | None = None,
+        push_openapi: bool | None = None,
+        consumer_header: str | None = None,
+        consumer: Any = None,
+        consumer_salt: str | None = None,
+        hash_consumer: bool | None = None,
     ) -> "Config":
         import sys as _sys
 
@@ -161,4 +172,17 @@ class Config:
                 ]
                 or None
             ),
+            push_openapi=(
+                push_openapi
+                if push_openapi is not None
+                else _env_bool("REQLY_PUSH_OPENAPI", False)
+            ),
+            consumer_header=consumer_header or os.environ.get("REQLY_CONSUMER_HEADER") or None,
+            consumer=consumer,
+            consumer_salt=consumer_salt or os.environ.get("REQLY_CONSUMER_SALT") or None,
+            hash_consumer=(
+                hash_consumer
+                if hash_consumer is not None
+                else _env_bool("REQLY_HASH_CONSUMER", True)
+            ),
         )

reqly-0.5.0/reqly/core/openapi_push.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Callable
+
+import httpx
+
+logger = logging.getLogger("reqly")
+
+
+class OpenAPIPusher:
+    """Uploads the app's OpenAPI spec to the collector once per process, so
+    Reqly can compare the documented API with the traffic it sees.
+
+    The upload happens on the first recorded request rather than at
+    instrument() time: apps often register routes after instrumenting, and
+    by the time requests are served the spec is complete. It runs on a
+    daemon thread and every failure is logged, never raised.
+    """
+
+    def __init__(
+        self,
+        *,
+        spec_factory: Callable[[], dict],
+        collector_url: str,
+        api_key: str | None,
+        service_name: str,
+    ) -> None:
+        self._spec_factory = spec_factory
+        self._url = f"{collector_url.rstrip('/')}/v1/services/{service_name}/openapi"
+        self._api_key = api_key
+        self._started = False
+        self._lock = threading.Lock()
+
+    def maybe_push(self) -> None:
+        if self._started:
+            return
+        with self._lock:
+            if self._started:
+                return
+            self._started = True
+        threading.Thread(target=self._push, name="reqly-openapi-push", daemon=True).start()
+
+    def _push(self) -> None:
+        try:
+            spec = self._spec_factory()
+            headers = {"X-Reqly-Key": self._api_key} if self._api_key else {}
+            response = httpx.put(self._url, json=spec, headers=headers, timeout=10.0)
+            if response.status_code == 200:
+                logger.info("reqly: uploaded OpenAPI spec (%s operations)", response.json().get("operations"))
+            else:
+                logger.warning(
+                    "reqly: OpenAPI spec upload failed: HTTP %s %s",
+                    response.status_code, response.text[:200],
+                )
+        except Exception:
+            logger.warning("reqly: OpenAPI spec upload failed", exc_info=True)