viclix-agent

Registro de tráfico para apps FastAPI, listo para visualizar en Viclix.

Instala un middleware ASGI que registra cada request (IP, usuario, endpoint, hora, duración, status…) en un archivo JSONL dedicado. La escritura ocurre en un hilo de fondo con el archivo siempre abierto, así que el camino del request nunca hace I/O de disco. Después, esos logs alimentan la visualización animada 2D/3D de Viclix: quién entró, desde qué IP, a qué páginas y en qué orden.

Instalación

pip install viclix-agent

Uso mínimo

from fastapi import FastAPI
from viclix_agent import MiddlewareLogger

app = FastAPI()
app.add_middleware(MiddlewareLogger)

Eso ya escribe viclix_traffic-YYYY-MM-DD.jsonl en el directorio de trabajo.

Configuración

app.add_middleware(
    MiddlewareLogger,
    log_path="logs/viclix_traffic.jsonl",  # ruta base (se le añade la fecha)
    trust_proxy=True,                       # IP real desde X-Forwarded-For (PythonAnywhere)
    rotation="daily",                       # "daily" o None
    include_query=False,                    # incluir query string (ojo con datos sensibles)
    ignore_paths=["/static", "/health"],    # prefijos que no se registran
)

Sesiones (trazar el flujo de un visitante)

Con track_sessions=True (por defecto), cada visitante recibe una cookie anónima viclix_sid y cada evento lleva un campo session. Así puedes seguir la secuencia completa de páginas de un mismo visitante aunque no haya login — por ejemplo, para ver qué flujo llevó a un usuario a un error 4xx/5xx:

GET /            -> 200   sess=44ef64b0
GET /checkout    -> 200   sess=44ef64b0
GET /boom        -> 500   sess=44ef64b0   ← el flujo que terminó en error

Identificar al usuario

Por defecto se lee request.state.user (lo que deje tu capa de auth). Si guardas un objeto, se prueban username, email, id, pk. Para lógica propia:

def resolver(scope):
    state = scope.get("state") or {}
    user = state.get("user")
    return getattr(user, "email", None)

app.add_middleware(MiddlewareLogger, user_resolver=resolver)

Visor (CLI)

El paquete instala el comando viclix-agent. Al ejecutarlo en tu terminal:

viclix-agent

1. Busca recursivamente (hasta 3 niveles) un log del middleware y usa el primero.
2. Levanta un servidor local y abre el navegador con una visualización interactiva.
3. Muestra estadísticas, línea de tiempo por sesión/IP (con animación del tráfico), endpoints e IPs más activas, y una tabla filtrable por IP, path, usuario o clase de status.

Mundo vivo (experimental)

En /experimental (enlace en el dashboard) hay una representación isométrica donde cada IP es una personita que sale de la "entrada" y camina hacia el endpoint que solicitó. Los endpoints se agrupan por clase (primer segmento del path) en distritos — /products, /products/42 → distrito products — y el mapa empieza en 0 y crece a medida que se descubren IPs y endpoints. El color del pulso indica la clase de status del último request (verde/amarillo/naranja/rojo). Controles: reproducir, velocidad, scrub temporal, arrastrar para mover, rueda para zoom, Fit para reencuadrar. El motor de personajes es el de POKER (sprites.js).

Esta vista es autocontenida y pública: es la base de lo que luego se mostrará en Viclix.

Metrópolis 3D (experimental)

En /experimental3d la misma idea, pero en three.js: una ciudad 3D donde las IPs son personitas low-poly que caminan del portón a su edificio-endpoint. Los edificios crecen con los hits, se agrupan por distrito, y cada request lanza un pulso de neón con el color de su status. Incluye sombras, niebla, cielo degradado y estrellas. Órbita arrastrando, zoom con la rueda, auto-rotación y encuadre automático del mapa que crece. three.js va empaquetado (funciona offline). No modifica la vista 2D.

Opciones:

viclix-agent [LOG]           # ruta a un .jsonl específico (opcional)
  --dir .                    # directorio raíz de búsqueda
  --depth 3                  # profundidad máxima de búsqueda
  --port 8787                # puerto del servidor local
  --all-days                 # agregar todos los archivos diarios de la misma base
  --no-browser               # no abrir el navegador automáticamente

Formato del log (JSONL)

Una línea JSON por request:

{"v":1,"ts":"2026-07-24T16:50:55.349029+00:00","ip":"1.2.3.4","method":"GET","path":"/dashboard","status":200,"duration_ms":3.06,"user":"jp@sizth.com","ua":"Mozilla/5.0","referer":null}

Notas de rendimiento

• Los eventos se encolan en memoria y los escribe un hilo daemon; el request no espera al disco.
• Si la cola se satura (queue_maxsize, 10k por defecto), los eventos nuevos se descartan en vez de bloquear la app. El writer lleva contadores written y dropped.
• El archivo se hace flush cada segundo y se cierra limpiamente al terminar el proceso (atexit).