Observabilidad¶
WSBuilder expone metricas y logs sin obligarte a meter un stack pesado.
Metricas¶
from wsbuilder import App, install_metrics
app = App()
metrics = install_metrics(app, app_name="my-app")
Eso crea:
GET /api/metricsGET /api/metrics/stream
Acceso a las metricas¶
Las metricas describen rutas, errores y, con ProxyI, los upstreams, asi que por
defecto solo responden a loopback y redes privadas (10/8, 172.16/12,
192.168/16, fc00::/7...). El resto recibe 403. Detras de un proxy, activa
la seguridad con trust_x_forwarded_for=True y trusted_proxy_cidrs=[...] para que se use la IP real del cliente.
app.enable_metrics(access="*") # publico
app.enable_metrics(access=["203.0.113.0/24"]) # redes concretas
app.enable_metrics(access="*", token="s3cret") # Authorization: Bearer s3cret
app.enable_metrics(authorize=lambda request: request.headers.get("x-ops") == "1")
El stream NDJSON esta acotado: como maximo max_streams=4 a la vez (el resto
recibe 429 con Retry-After), y cada uno se cierra tras
max_stream_seconds=300, incluso con follow=1.
AppMetrics¶
AppMetrics registra:
- conexiones TCP
- requests HTTP
- responses HTTP
- upgrades WebSocket
- mensajes WebSocket
- errores
Snapshot¶
snap = app.metrics.snapshot()
El snapshot incluye totales, tasas y el estado de cada subsistema cuando la app agrega snapshots extra.
Streaming¶
for chunk in app.metrics.stream_chunks(interval_seconds=1.0):
print(chunk.decode("utf-8"))
Metricas de la app¶
App.enable_metrics() añade informacion adicional:
- resumen de threads por ruta
- snapshot de cache general
- snapshot de cache HTTP
- snapshot de security
- snapshot de proxyi
- snapshot de tasks
Logs¶
from wsbuilder import App
app = App()
logger = app.enable_logs(path="logs/wsbuilder.ndjson")
logger.event("server_start", host="0.0.0.0", port=8765)
NDJSONLog escribe un evento por linea y funciona bien para ingest para herramientas externas.
Mensajes del framework¶
Los avisos y errores del propio framework (handlers que fallan, errores TLS,
arranque y apagado del servidor) pasan por wsbuilder.logs:
- sin
enable_logs(), salen por stderr como[evento] mensaje; los errores incluyen el traceback completo; - con
enable_logs(), cada mensaje se guarda en el NDJSON conts,level,event,messagey, si hubo excepcion,error.type,error.messageyerror.traceback. Los de nivelwarningo superior tambien se muestran por stderr.
logger = app.enable_logs(path="logs/wsbuilder.ndjson", console_level="error")
logger.info("deploy", "version publicada", version="1.0.3")
logger.exception("pagos", "fallo el cobro", exc)
from wsbuilder.logs import console
console.level = "warning" # sin enable_logs: oculta los mensajes info
Niveles: debug, info, warning, error. console_level=None deja los
mensajes solo en el archivo.
Docs nativas¶
App.enable_docs() publica una vista HTML y un endpoint JSON con App.describe().
Es util para inspeccion local, automatizacion o integracion con dashboards de desarrollo.
Ruta de trabajo sugerida¶
- Activa
install_metrics(). - Activa
enable_logs()si quieres traza historica. - Usa
enable_docs()para exponer la configuracion real de la app. - Consulta
/api/metricscuando algo no cuadre en produccion.