django-api-registry 0.1.0__py3-none-any.whl

django_api_registry-0.1.0.dist-info/METADATA

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: django-api-registry
+Version: 0.1.0
+Requires-Python: >=3.10
+Requires-Dist: django>=4.2
+Requires-Dist: drf-spectacular>=0.27
+Provides-Extra: runtime
+Requires-Dist: opentelemetry-sdk>=1.27; extra == "runtime"
+Requires-Dist: opentelemetry-instrumentation-requests>=0.48b0; extra == "runtime"
+Requires-Dist: opentelemetry-instrumentation-httpx>=0.48b0; extra == "runtime"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-django>=4.8; extra == "test"
+Requires-Dist: djangorestframework>=3.14; extra == "test"

django_api_registry-0.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+registry_client/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+registry_client/aggregator.py,sha256=CVMU1Lw7f81JClGPhUkTuySRuQvP13s6ZuhFHi8Naz8,8460
+registry_client/apps.py,sha256=zM9GgXpvj86kjNOHkgx030q1PtUBw2dLQzUlxEEHWUU,1610
+registry_client/conf.py,sha256=7M4G5deBPs9rKnG1AVDkVVovTgwqhM5WVouZLHsQThg,2048
+registry_client/context.py,sha256=hCNa_yTmeiiYc5XhN5Z2yInalCU__LiaX3h_yzo4K30,409
+registry_client/middleware.py,sha256=iL0TCOYCY2Y0QZiSEsKDOBtjXZG8bhHKXD9rIe1PaxM,1083
+registry_client/normalize.py,sha256=YhI0x9optcHxTpJ5A8Ey9ZQ2Chf1A6_1aXwnPsOwF6U,2613
+registry_client/otel.py,sha256=ZgAaaqiBS61OtmEdn4rPwqRelSiyPxO7nfxGA0fb1xE,1410
+registry_client/processor.py,sha256=qinBpWA5Wc_ycYehCQK-3ImcU7OZbD1lZB9WC6_SRVg,3190
+registry_client/runtime_guard.py,sha256=LPVgbvoy7SxuoaiXQ6-Mz-hshjlJRJgp0VGh5MzIsU4,1644
+registry_client/transport.py,sha256=fyqAkMUmSiX7IgsVDiW8f3Xig4rwTMYNT8W-QZxwZAg,2304
+registry_client/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+registry_client/integrations/celery.py,sha256=fO9vJ30kJddYIjq9NTO25ba_k0ljPs1hhgyhUmXTYxo,699
+registry_client/management/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+registry_client/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+registry_client/management/commands/registry_dump.py,sha256=c-lKeEpzfeAkniW7TWZjM2wy-ITHWDlr_8EnPDy7LDc,11736
+registry_client/management/commands/registry_install_skills.py,sha256=NJAbJsm6XpYpE2wGeJK0BvCBGRtK9HJd2HvPhLq0ACc,3660
+registry_client/skills/documentar-endpoint/SKILL.md,sha256=cBI9qwB7J6cUEE1SSYX_3xLYmNcnOo3FzPN2HzG4KDk,6169
+registry_client/skills/documentar-endpoint/references/anotacion.md,sha256=RpLYBBCrRKfbC4fNxEtZkgd5QOBCDMDfGD-mZjhsnq8,9700
+registry_client/skills/documentar-endpoint/references/dependencias.md,sha256=IXGY0RZV-uWClkFVoRdtLlffeNGBwDZ8nSIq2a0nE9Q,3061
+registry_client/skills/documentar-endpoint/references/descubrimiento.md,sha256=MuxHd8Jq8QSCOgb5fWQ22mTw7z6a2I2gLODfrPapt1A,4904
+registry_client/skills/documentar-endpoint/references/entrevista.md,sha256=44wtUFHJTKqXkRDG6-OG6svzpGzbx0Re6f5UKnyBzJs,2720
+django_api_registry-0.1.0.dist-info/METADATA,sha256=iu1_mt8VmROmLsMl3sZD60N_Vx484BbAubW4JcsPMjI,583
+django_api_registry-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+django_api_registry-0.1.0.dist-info/top_level.txt,sha256=Hza1abk4V6JqJhGsn2LA3Ff1SD_YvKL4AQkCh4uccok,16
+django_api_registry-0.1.0.dist-info/RECORD,,

django_api_registry-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

django_api_registry-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+registry_client

registry_client/aggregator.py

@@ -0,0 +1,227 @@
+import atexit
+import logging
+import os
+import random
+import socket
+import threading
+import uuid
+from collections import defaultdict
+from datetime import datetime, timezone
+
+from .transport import send_report
+
+logger = logging.getLogger(__name__)
+
+
+class _Bucket:
+    __slots__ = ("count", "errors", "total_ms", "max_ms", "call_site")
+
+    def __init__(self):
+        self.count = 0
+        self.errors = 0
+        self.total_ms = 0.0
+        self.max_ms = 0.0
+        self.call_site = None
+
+
+class CallAggregator:
+    """Agrega llamadas salientes en memoria por (inbound, host, method, path) y las
+    reporta al hub cada `flush_interval_seconds` en un hilo daemon propio.
+
+    Es también el dueño de la decisión de muestreo. Está aquí y no en `apps.py`
+    porque es el único punto que sabe re-evaluarla después de un fork: con
+    `gunicorn --preload` la app se importa en el master y los workers heredan lo
+    que se hubiera decidido allí.
+    """
+
+    def __init__(self, config):
+        self.config = config
+        self._lock = threading.Lock()
+        self._buckets = defaultdict(_Bucket)
+        self._window_start = self._now()
+        self._dropped = 0
+        self._stop_event = threading.Event()
+        self._thread = None
+        self._pid = os.getpid()
+        self._sampled = self._decidir_muestreo()
+        self.instance = self._nombre_de_instancia()
+        self._registrar_hooks_de_fork()
+
+    @staticmethod
+    def _now():
+        return datetime.now(timezone.utc)
+
+    def _nombre_de_instancia(self):
+        return f"{socket.gethostname()}/pid-{self._pid}"
+
+    def _decidir_muestreo(self):
+        """Una decisión por proceso, nunca por request: muestrear por request
+        sesgaría los contadores agregados."""
+        if self.config.sample_rate >= 1.0:
+            return True
+        return random.random() < self.config.sample_rate
+
+    # ---------------------------------------------------------------- fork
+
+    def _registrar_hooks_de_fork(self):
+        """`fork()` no clona hilos: solo sobrevive el que llama.
+
+        Sin esto, bajo `gunicorn --preload` el hilo de flush arranca en el master
+        y los workers nacen sin él. Agregan en memoria hasta `MAX_KEYS`, empiezan
+        a descartar, y no reportan nunca.
+        """
+        if not hasattr(os, "register_at_fork"):  # Windows
+            return
+        os.register_at_fork(
+            before=self._antes_del_fork,
+            after_in_parent=self._despues_del_fork_en_el_padre,
+            after_in_child=self._despues_del_fork_en_el_hijo,
+        )
+
+    def _antes_del_fork(self):
+        """Toma el lock antes de bifurcar, y lo suelta a ambos lados.
+
+        Si el hilo de flush tuviera el lock tomado en el instante del fork, el
+        hijo nacería con un lock bloqueado y sin ningún hilo capaz de soltarlo:
+        el primer `record()` del worker se colgaría dentro de un request, para
+        siempre. Tomarlo antes garantiza que nadie más lo tiene.
+        """
+        self._lock.acquire()
+
+    def _despues_del_fork_en_el_padre(self):
+        self._lock.release()
+
+    def _despues_del_fork_en_el_hijo(self):
+        self._lock.release()
+        self._adoptar_proceso()
+
+    def _adoptar_proceso(self):
+        """Reinicia el estado heredado de otro proceso tras un fork.
+
+        Los contadores del padre no son de este worker: sumarlos los duplicaría
+        en el hub. El muestreo se vuelve a tirar para que `SAMPLE_RATE` signifique
+        una fracción de los procesos y no un todo-o-nada por pod.
+        """
+        # El lock heredado puede venir en cualquier estado; se descarta.
+        self._lock = threading.Lock()
+        with self._lock:
+            if os.getpid() == self._pid:
+                return
+            self._pid = os.getpid()
+            self._buckets = defaultdict(_Bucket)
+            self._window_start = self._now()
+            self._dropped = 0
+            self._sampled = self._decidir_muestreo()
+            self.instance = self._nombre_de_instancia()
+            self._stop_event = threading.Event()
+            self._thread = None
+
+        if self._sampled:
+            self.start()
+
+    # -------------------------------------------------------------- registro
+
+    def record(self, inbound, host, method, path, status, duration_ms, call_site=None):
+        """Incrementa el bucket de esta clave. Si `max_keys` ya se alcanzó y la clave
+        es nueva, se descarta y se cuenta en `_dropped` (viaja como `dropped_keys`).
+
+        Descartar claves nuevas y no evictar las viejas es deliberado: evictar por
+        menor uso tiraría justo las aristas raras, que son las que interesan.
+        """
+        # uWSGI bifurca desde C, así que `os.register_at_fork` nunca dispara y el
+        # camino caliente tiene que detectar el fork por su cuenta.
+        if os.getpid() != self._pid:
+            self._adoptar_proceso()
+
+        if not self._sampled:
+            return
+
+        key = (inbound, host, method, path)
+        with self._lock:
+            if key not in self._buckets and len(self._buckets) >= self.config.max_keys:
+                self._dropped += 1
+                return
+            bucket = self._buckets[key]
+            bucket.count += 1
+            bucket.total_ms += duration_ms
+            bucket.max_ms = max(bucket.max_ms, duration_ms)
+            if status is not None and status >= 400:
+                bucket.errors += 1
+            if call_site and bucket.call_site is None:
+                bucket.call_site = call_site
+
+    # ----------------------------------------------------------------- hilo
+
+    def start(self):
+        if not self._sampled:
+            logger.info("registry: proceso no muestreado, no se reportará")
+            return
+        if self._thread is not None and self._thread.is_alive():
+            return
+        self._thread = threading.Thread(
+            target=self._loop, name="registry-flush", daemon=True
+        )
+        self._thread.start()
+        atexit.register(self.stop)
+
+    def _loop(self):
+        interval = self.config.flush_interval_seconds
+        while not self._stop_event.wait(interval):
+            try:
+                self.flush()
+            except Exception:
+                logger.debug("registry: flush falló", exc_info=True)
+
+    def stop(self):
+        # Idempotente: `atexit` puede tener varias registraciones tras un fork.
+        if self._stop_event.is_set():
+            return
+        self._stop_event.set()
+        try:
+            self.flush()
+        except Exception:
+            logger.debug("registry: flush final falló", exc_info=True)
+
+    # ---------------------------------------------------------------- flush
+
+    def _drain(self):
+        with self._lock:
+            buckets, self._buckets = self._buckets, defaultdict(_Bucket)
+            window_start, self._window_start = self._window_start, self._now()
+            dropped, self._dropped = self._dropped, 0
+        return buckets, window_start, dropped
+
+    def flush(self):
+        buckets, window_start, dropped = self._drain()
+        if not buckets:
+            return
+
+        calls = []
+        for (inbound, host, method, path), b in buckets.items():
+            entry = {
+                "inbound": inbound,
+                "host": host,
+                "method": method,
+                "path_observed": path,
+                "count": b.count,
+                "errors": b.errors,
+                "avg_ms": round(b.total_ms / b.count, 2),
+                "max_ms": round(b.max_ms, 2),
+            }
+            if b.call_site:
+                entry["call_site"] = b.call_site
+            calls.append(entry)
+
+        send_report(self.config, {
+            # Identifica la ventana, no el envío: si un reintento repite el
+            # mismo lote, el hub lo reconoce y no duplica los contadores.
+            "batch_id": uuid.uuid4().hex,
+            "service": self.config.service,
+            "environment": self.config.environment,
+            "instance": self.instance,
+            "sample_rate": self.config.sample_rate,
+            "window_start": window_start.isoformat(),
+            "window_end": self._now().isoformat(),
+            "dropped_keys": dropped,
+            "calls": calls,
+        })

registry_client/apps.py

@@ -0,0 +1,47 @@
+import logging
+
+from django.apps import AppConfig
+
+logger = logging.getLogger(__name__)
+
+
+class RegistryClientConfig(AppConfig):
+    name = "registry_client"
+    verbose_name = "API Registry Client"
+
+    def ready(self):
+        """Instrumenta el proceso si corresponde. Cualquier fallo se degrada a
+        warning/log — esta herramienta de observabilidad nunca debe tumbar la app
+        que observa."""
+        from .conf import RegistryConfig
+        from .runtime_guard import is_reloader_supervisor
+
+        config = RegistryConfig.from_settings()
+
+        if not config.runtime_enabled:
+            return
+
+        # El autoreloader de runserver arranca dos procesos; solo instrumenta
+        # el hijo que sirve requests.
+        if is_reloader_supervisor():
+            return
+
+        # El muestreo NO se decide aquí. Bajo `gunicorn --preload`, ready() corre
+        # en el master antes del fork y todos los workers heredarían la misma
+        # decisión, dejando el pod entero dentro o fuera y volviendo inútil un
+        # SAMPLE_RATE de 0.1. Lo decide el agregador, que sabe re-evaluarlo en
+        # cada proceso hijo.
+
+        try:
+            from .otel import install
+        except ImportError:
+            logger.warning(
+                "registry: RUNTIME_ENABLED=1 pero los extras no están "
+                "instalados. Usa django-api-registry[runtime]."
+            )
+            return
+
+        try:
+            install(config)
+        except Exception:
+            logger.warning("registry: fallo al instrumentar", exc_info=True)

registry_client/conf.py

@@ -0,0 +1,49 @@
+from dataclasses import dataclass, field
+
+from django.conf import settings
+
+
+@dataclass(frozen=True)
+class RegistryConfig:
+    """Vista tipada del dict `settings.REGISTRY`, validada una sola vez al arrancar.
+
+    `HOSTS` y `CAPTURE_HOSTS` se parecen y no son lo mismo:
+
+    - `HOSTS` declara bajo qué nombres de red se conoce a *este* servicio. Viaja
+      en el manifest y es lo que le permite al hub resolver el `host` que ve en
+      un reporte ajeno —`crm-internal`— al servicio `crm`. Sin esta declaración
+      toda arista entrante queda como host desconocido.
+    - `CAPTURE_HOSTS` filtra qué destinos *salientes* se observan.
+    """
+
+    service: str
+    environment: str = "dev"
+    hub_url: str = ""
+    hub_token: str = ""
+    hosts: tuple[str, ...] = field(default_factory=tuple)
+    runtime_enabled: bool = False
+    sample_rate: float = 1.0
+    flush_interval_seconds: int = 60
+    max_keys: int = 5000
+    capture_hosts: tuple[str, ...] = field(default_factory=tuple)
+    normalize_paths: bool = True
+    capture_call_site: bool = False
+
+    @classmethod
+    def from_settings(cls) -> "RegistryConfig":
+        """Construye la config desde `settings.REGISTRY`. Lanza KeyError si falta SERVICE."""
+        raw = getattr(settings, "REGISTRY", {}) or {}
+        return cls(
+            service=raw["SERVICE"],
+            environment=raw.get("ENVIRONMENT", "dev"),
+            hub_url=raw.get("HUB_URL", ""),
+            hub_token=raw.get("HUB_TOKEN", ""),
+            hosts=tuple(raw.get("HOSTS", ())),
+            runtime_enabled=bool(raw.get("RUNTIME_ENABLED", False)),
+            sample_rate=float(raw.get("SAMPLE_RATE", 1.0)),
+            flush_interval_seconds=int(raw.get("FLUSH_INTERVAL_SECONDS", 60)),
+            max_keys=int(raw.get("MAX_KEYS", 5000)),
+            capture_hosts=tuple(raw.get("CAPTURE_HOSTS", ())),
+            normalize_paths=bool(raw.get("NORMALIZE_PATHS", True)),
+            capture_call_site=bool(raw.get("CAPTURE_CALL_SITE", False)),
+        )

registry_client/context.py

@@ -0,0 +1,16 @@
+import contextlib
+from contextvars import ContextVar
+
+inbound_operation: ContextVar[str | None] = ContextVar(
+    "registry_inbound_operation", default=None
+)
+
+
+@contextlib.contextmanager
+def label(name: str):
+    """Uso: with registry.label("task:facturacion_mensual"): ..."""
+    token = inbound_operation.set(name)
+    try:
+        yield
+    finally:
+        inbound_operation.reset(token)

registry_client/integrations/celery.py

@@ -0,0 +1,22 @@
+"""Atribución automática para tasks de Celery: cada llamada saliente hecha dentro
+de una task queda etiquetada como `task:<nombre>`, sin tocar cada task una por una.
+Importar este módulo activa las señales; no se importa por defecto.
+"""
+
+from celery.signals import task_postrun, task_prerun
+
+from ..context import inbound_operation
+
+_tokens = {}
+
+
+@task_prerun.connect
+def _registry_task_start(task_id=None, task=None, **kwargs):
+    _tokens[task_id] = inbound_operation.set(f"task:{task.name}")
+
+
+@task_postrun.connect
+def _registry_task_end(task_id=None, **kwargs):
+    token = _tokens.pop(task_id, None)
+    if token is not None:
+        inbound_operation.reset(token)