django-api-registry 0.1.0__tar.gz

django_api_registry-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include registry_client/skills *.md

django_api_registry-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,246 @@
+# django-api-registry — registry_client
+
+Componente **runtime** del paquete `django-api-registry`: instrumenta las
+llamadas HTTP salientes de un backend Django con OpenTelemetry, las atribuye
+al endpoint entrante que las originó, y las reporta agregadas a un hub para
+construir el árbol de dependencias entre servicios.
+
+El diseño completo (motivación, dev vs. producción, esquema del hub) está en
+[`docs/planning/captura_de_datos.md`](docs/planning/captura_de_datos.md). Este
+documento describe el código ya implementado en `registry_client/`.
+
+El paquete tiene un segundo componente, **Manifest** (`registry_dump`), que es
+independiente del runtime: genera el OpenAPI del servicio por introspección
+estática y lo envía al hub. Mientras el runtime dice qué *consume* cada
+endpoint, el manifest dice qué *expone* y **para qué sirve**. Ver
+[Manifest](#manifest) más abajo.
+
+---
+
+## Instalación
+
+```bash
+pip install django-api-registry              # sin runtime, modo silencioso
+pip install "django-api-registry[runtime]"    # con OpenTelemetry
+```
+
+`opentelemetry-sdk` y los instrumentors de `requests`/`httpx` son un extra
+(`[runtime]`), no una dependencia base. Si `RUNTIME_ENABLED=1` pero el extra
+no está instalado, la app arranca igual y solo se emite un `warning`.
+
+## Configuración
+
+```python
+# settings.py de tu proyecto Django
+INSTALLED_APPS = [..., "registry_client"]
+MIDDLEWARE = [..., "registry_client.middleware.InboundRouteMiddleware"]
+
+REGISTRY = {
+    "SERVICE": "billing",                                        # requerido
+    "ENVIRONMENT": os.environ.get("REGISTRY_ENV", "dev"),
+    "HUB_URL": os.environ.get("REGISTRY_HUB_URL", ""),
+    "HUB_TOKEN": os.environ.get("REGISTRY_HUB_TOKEN", ""),
+    "HOSTS": ["billing.internal", "billing"],                    # requerido
+    "RUNTIME_ENABLED": os.environ.get("REGISTRY_RUNTIME", "0") == "1",
+    "SAMPLE_RATE": float(os.environ.get("REGISTRY_SAMPLE_RATE", "1.0")),
+    "FLUSH_INTERVAL_SECONDS": int(os.environ.get("REGISTRY_FLUSH", "60")),
+    "MAX_KEYS": 5000,
+    "CAPTURE_HOSTS": [],
+    "NORMALIZE_PATHS": True,
+    "CAPTURE_CALL_SITE": False,
+}
+```
+
+| Clave | Default | Qué controla |
+|---|---|---|
+| `SERVICE` | — (requerido) | Nombre del servicio, viaja en cada reporte. |
+| `ENVIRONMENT` | `"dev"` | Se declara desde el cliente, no se infiere en el hub. |
+| `HUB_URL` / `HUB_TOKEN` | `""` | Sin `HUB_URL` el reporte se descarta silenciosamente. |
+| `HOSTS` | `[]` | Nombres de red de **este** servicio. Sin ellos el hub no puede resolver `host` → servicio y toda arista que apunte aquí entra como host desconocido. |
+| `RUNTIME_ENABLED` | `False` | Atado a una env var explícita, nunca a `DEBUG`. |
+| `SAMPLE_RATE` | `1.0` | Se decide una vez por proceso, en el agregador, y se vuelve a decidir en cada worker tras un `fork`. |
+| `FLUSH_INTERVAL_SECONDS` | `60` | 60s en dev, 300s recomendado en producción. |
+| `MAX_KEYS` | `5000` | Cota de memoria del agregador; ver `dropped_keys`. |
+| `CAPTURE_HOSTS` | `[]` | Filtra qué destinos **salientes** se observan. No confundir con `HOSTS`. Vacío = todos. |
+| `NORMALIZE_PATHS` | `True` | Opcional en dev, obligatorio en prod (evita saturar `MAX_KEYS`). |
+| `CAPTURE_CALL_SITE` | `False` | Útil en dev (da `file:line`); desactivar en prod (cuesta por llamada). |
+
+## Arquitectura
+
+```
+registry_client/
+├── apps.py              # AppConfig.ready() — punto de arranque, todo fail-safe
+├── runtime_guard.py      # distingue el supervisor de runserver del hijo
+├── conf.py               # RegistryConfig: valida REGISTRY una sola vez
+├── context.py            # contextvar con el endpoint entrante
+├── middleware.py         # captura request.resolver_match.route
+├── otel.py               # TracerProvider aislado + instrumentors
+├── processor.py          # SpanProcessor propio: span CLIENT → registro
+├── normalize.py          # colapso de segmentos de alta cardinalidad
+├── aggregator.py         # agregación en memoria, muestreo y hooks de fork
+├── transport.py          # POST al hub con urllib (no requests/httpx)
+├── integrations/celery.py  # atribución para tasks (opt-in, no autocargado)
+├── management/commands/
+│   ├── registry_dump.py           # Manifest: OpenAPI -> hub
+│   └── registry_install_skills.py # copia los skills a .claude/skills/
+└── skills/documentar-endpoint/    # skill de documentación de endpoints
+```
+
+Recorrido de una llamada saliente:
+
+1. `InboundRouteMiddleware.process_view` guarda `"GET /api/invoices/<int:pk>/"`
+   en un contextvar (`context.py`).
+2. El instrumentor de OTel abre un span `CLIENT` al hacer la llamada saliente.
+3. `RegistrySpanProcessor.on_end` lee el contextvar, arma la clave
+   `(inbound, host, method, path)` y llama a `aggregator.record(...)`.
+4. `CallAggregator` acumula en memoria; cada `FLUSH_INTERVAL_SECONDS` un hilo
+   daemon llama a `transport.send_report`.
+5. El hub resuelve host→servicio y path→template contra el OpenAPI de cada
+   destino, y hace upsert de la arista.
+
+Decisiones no obvias (documentadas también como docstrings/comentarios en el
+código donde aplica):
+
+- **TracerProvider propio**, no el global — no pisa un tracing que el equipo
+  consumidor ya tenga configurado.
+- **`urllib` en `transport.py`**, no `requests`/`httpx` — ambos están
+  instrumentados por este mismo paquete; reportar con ellos generaría spans
+  que el processor volvería a capturar.
+- **Todo `apps.ready()` y `processor.on_end()` atrapan excepciones** — corren
+  en el arranque y en el camino del request respectivamente; una herramienta
+  de observabilidad no puede tumbar lo que observa.
+- **Muestreo por proceso, no por request** — evita sesgar los contadores
+  agregados. Vive en el agregador y no en `apps.ready()`, porque con
+  `gunicorn --preload` `ready()` corre en el master antes del `fork` y todos
+  los workers heredarían la misma decisión.
+- **El agregador sobrevive al `fork`** — `fork()` no clona hilos, así que un
+  worker de `--preload` nacería sin el hilo de flush y no reportaría nunca. Hay
+  hooks `os.register_at_fork` que recrean el lock, descartan los contadores
+  heredados y arrancan un hilo nuevo, más una comprobación de `os.getpid()` en
+  el camino caliente para uWSGI, que bifurca desde C y nunca dispara los hooks.
+- **Solo se normaliza lo que tiene forma de identificador** — un falso positivo
+  (`/api/customers/search/` → `/api/customers/{}/`) haría que el hub emparejara
+  la arista con el template equivocado; un falso negativo solo gasta claves, y
+  eso está acotado por `MAX_KEYS` y medido por `dropped_keys`.
+
+## Manifest
+
+El runtime mide **cuánto** tráfico hace cada endpoint y **a quién** llama. El
+manifest aporta lo que el tráfico no dice: **para qué sirve** cada endpoint, qué
+requiere y de qué depende.
+
+Esa semántica no vive en un archivo aparte —se desincronizaría— sino en el
+código de las vistas, vía docstrings y `@extend_schema` de drf-spectacular. El
+skill `documentar-endpoint` es quien la escribe.
+
+```bash
+# 1. Instalar el skill en el proyecto consumidor
+python manage.py registry_install_skills      # -> .claude/skills/
+
+# 2. Documentar endpoints (desde Claude Code)
+/documentar-endpoint miapp/views.py
+
+# 3. Enviar el manifest al hub
+python manage.py registry_dump                # o --file / --print
+```
+
+El skill infiere del código lo que el código demuestra (autenticación,
+idempotencia, efectos, llamadas salientes) y **pregunta** lo que no puede
+inferir —sobre todo el caso de uso de negocio—, en vez de inventarlo o dejarlo
+en blanco. No documenta consumidores ni criticidad: eso el hub ya lo deduce del
+runtime.
+
+La anotación queda en el schema bajo la extensión `x-registry`:
+
+```python
+@extend_schema(
+    summary="Autoriza un cargo contra el emisor",
+    extensions={"x-registry": {
+        "version": 1,
+        "caso-de-uso": "Checkout de la app móvil.",
+        "requiere": {"auth": "Bearer, scope pagos:write", "idempotente": False,
+                     "efectos": ["reserva fondos por 7 días"]},
+        "depende-de": [{"servicio": "emisor", "llamada": "POST /auth/"}],
+    }},
+)
+def post(self, request): ...
+```
+
+La documentación del **servicio** no se anota: sale del bloque `info` del
+OpenAPI, que a su vez sale de `SPECTACULAR_SETTINGS`. Es la ficha del catálogo,
+y `CONTACT` es el equipo dueño por defecto de todos sus endpoints:
+
+```python
+SPECTACULAR_SETTINGS = {
+    "TITLE": "Facturación",
+    "DESCRIPTION": "Emisión y timbrado de CFDI.",
+    "CONTACT": {"name": "equipo-facturacion"},
+    "VERSION": "1.0.0",
+}
+```
+
+`registry_dump` avisa si falta alguno. No falla: un catálogo sin nombre sigue
+sirviendo, pero nadie sabrá a quién preguntarle.
+
+El payload lleva el OpenAPI completo más una tabla `routes` que une cada
+operación con las dos formas en que el runtime la nombrará:
+
+```json
+{"method": "POST",
+ "openapi_path": "/api/facturas/{id}/timbrar/",
+ "shape": "/api/facturas/{}/timbrar/",
+ "inbound": "POST /api/facturas/<int:pk>/timbrar/",
+ "operation_id": "facturas_timbrar_create"}
+```
+
+Los dos campos sirven a los dos extremos de una arista, y los dos existen para
+que el join sea por igualdad y no por heurística:
+
+- **`inbound`** es idéntico, carácter por carácter, al endpoint entrante que
+  reporta el middleware. Resuelve el extremo *origen*: qué operación de este
+  servicio hizo la llamada.
+- **`shape`** es el path del OpenAPI pasado por la misma regla que
+  `normalize.normalize_path` aplica a los paths salientes. Resuelve el extremo
+  *destino*: `/api/facturas/7/timbrar/` llega al hub ya colapsado como
+  `/api/facturas/{}/timbrar/`, que es exactamente esta cadena.
+
+`shape` se calcula aquí, y no en el hub, para que la regla tenga una sola
+implementación. Si el hub la reprodujera por su cuenta, cualquier cambio en
+`normalize.py` desalinearía las dos mitades sin producir ningún error: solo
+aristas sin resolver, indistinguibles de un servicio que no reporta.
+
+A diferencia del runtime, `registry_dump` **falla ruidosamente**: corre en
+build/CI, donde un envío que falla en silencio deja el pipeline en verde con el
+hub desactualizado.
+
+> **Antes de anotar**, revisa si el proyecto sirve `/api/schema/` sin
+> autenticación: `x-registry` expone nombres de servicios internos, settings de
+> URLs y efectos de negocio. Ver `SPECTACULAR_SETTINGS["SERVE_PERMISSIONS"]`.
+
+## Integración con Celery
+
+```python
+# en algún módulo que se importe al arrancar (p. ej. celery.py de tu proyecto)
+import registry_client.integrations.celery  # noqa: F401 — activa las señales
+```
+
+No se importa por defecto porque `celery` no es una dependencia del paquete.
+
+## Testing
+
+```bash
+pip install -e ".[runtime,test]"
+pytest
+```
+
+Los tests de `processor.py`, `otel.py` y `apps.py` requieren el extra
+`[runtime]` instalado (usan `opentelemetry-sdk` real). `tests/settings.py` es
+el settings mínimo de Django para correr la suite — no es un ejemplo de
+configuración real, ver la sección "Configuración" arriba para eso.
+
+## Desarrollo vs. producción
+
+En desarrollo, los contadores no tienen significado (tráfico artificial) y
+solo importa si la arista existe o no. La migración a producción es un cambio
+de configuración, no de código: ver la sección 17 de
+[`captura_de_datos.md`](docs/planning/captura_de_datos.md#17-migración-a-producción).

django_api_registry-0.1.0/django_api_registry.egg-info/PKG-INFO

@@ -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/django_api_registry.egg-info/SOURCES.txt

@@ -0,0 +1,41 @@
+MANIFEST.in
+README.md
+pyproject.toml
+django_api_registry.egg-info/PKG-INFO
+django_api_registry.egg-info/SOURCES.txt
+django_api_registry.egg-info/dependency_links.txt
+django_api_registry.egg-info/requires.txt
+django_api_registry.egg-info/top_level.txt
+registry_client/__init__.py
+registry_client/aggregator.py
+registry_client/apps.py
+registry_client/conf.py
+registry_client/context.py
+registry_client/middleware.py
+registry_client/normalize.py
+registry_client/otel.py
+registry_client/processor.py
+registry_client/runtime_guard.py
+registry_client/transport.py
+registry_client/integrations/__init__.py
+registry_client/integrations/celery.py
+registry_client/management/__init__.py
+registry_client/management/commands/__init__.py
+registry_client/management/commands/registry_dump.py
+registry_client/management/commands/registry_install_skills.py
+registry_client/skills/documentar-endpoint/SKILL.md
+registry_client/skills/documentar-endpoint/references/anotacion.md
+registry_client/skills/documentar-endpoint/references/dependencias.md
+registry_client/skills/documentar-endpoint/references/descubrimiento.md
+registry_client/skills/documentar-endpoint/references/entrevista.md
+tests/test_aggregator.py
+tests/test_apps.py
+tests/test_conf.py
+tests/test_context.py
+tests/test_middleware.py
+tests/test_normalize.py
+tests/test_processor.py
+tests/test_registry_dump.py
+tests/test_runtime_guard.py
+tests/test_skills.py
+tests/test_transport.py

django_api_registry-0.1.0/django_api_registry.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

django_api_registry-0.1.0/django_api_registry.egg-info/requires.txt

@@ -0,0 +1,12 @@
+django>=4.2
+drf-spectacular>=0.27
+
+[runtime]
+opentelemetry-sdk>=1.27
+opentelemetry-instrumentation-requests>=0.48b0
+opentelemetry-instrumentation-httpx>=0.48b0
+
+[test]
+pytest>=8.0
+pytest-django>=4.8
+djangorestframework>=3.14

django_api_registry-0.1.0/django_api_registry.egg-info/top_level.txt

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

django_api_registry-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "django-api-registry"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = [
+    "django>=4.2",
+    "drf-spectacular>=0.27",
+]
+
+[project.optional-dependencies]
+runtime = [
+    "opentelemetry-sdk>=1.27",
+    "opentelemetry-instrumentation-requests>=0.48b0",
+    "opentelemetry-instrumentation-httpx>=0.48b0",
+]
+test = [
+    "pytest>=8.0",
+    "pytest-django>=4.8",
+    # El manifest se prueba generando un OpenAPI real, no un mock: hace falta
+    # DRF para que haya vistas que enumerar.
+    "djangorestframework>=3.14",
+]
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["registry_client*"]
+
+[tool.setuptools.package-data]
+# `packages.find` solo descubre paquetes; `skills/` no lo es (no tiene
+# __init__.py), así que necesita declararse aquí para viajar en el wheel.
+registry_client = ["skills/**/*.md"]
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+python_files = ["test_*.py"]

django_api_registry-0.1.0/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,
+        })

django_api_registry-0.1.0/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)