Registro y métricas

Ajustes para el registro del bouncer y las métricas de Prometheus.

Registro

logging.level Opcional

Env: LOG_LEVEL · Por defecto: info

Nivel de detalle del log:

Nivel	Descripción
debug	Información detallada para depuración (muy verboso)
info	Mensajes de funcionamiento normal
warn	Condiciones de advertencia
error	Solo condiciones de error

logging:
  level: "debug" # Útil para diagnosticar problemas

logging.format Opcional

Env: LOG_FORMAT · Por defecto: text

Formato de salida del log:

• text — salida legible y con colores (ideal para consola/journalctl)
• json — JSON estructurado (ideal para sistemas de agregación de logs)

logging.file Opcional

Env: LOG_FILE · Por defecto: —

Ruta a un archivo de log. Déjala vacía —el valor por defecto— y el bouncer escribe solo en stderr, igual que antes de que esta clave hiciera nada.

Cuando se define, las líneas de log van a stderr y al archivo. El archivo es una adición, no un desvío: journalctl -u cs-routeros-bouncer y docker logs siguen funcionando. Se abre en modo append, así que un reinicio nunca descarta el historial de baneos, y se crea con modo 0640 porque las líneas registran las IP de los clientes baneados.

El directorio padre debe existir ya

El bouncer no crea directorios. Si falta el padre, o la ruta no es escribible, el arranque falla indicando la ruta y el error del sistema, en lugar de caer en silencio a stderr: un archivo de log que configuraste y no obtuviste es peor que no tener ninguno.

Se acepta cualquier ruta de archivo. Bajo la unidad systemd endurecida que escribe setup, ReadWritePaths=/var/log es la única ubicación escribible, así que una ruta fuera de /var/log fallará aunque exista — y ahí una ruta relativa se resuelve contra /, no contra el directorio de trabajo de tu shell. Para despliegues con systemd, indica una ruta absoluta bajo /var/log.

No hay rotación integrada y el descriptor del archivo se mantiene abierto durante toda la vida del proceso. Una herramienta de rotación que renombre el archivo (logrotate sin copytruncate) dejará al bouncer escribiendo en el inodo renombrado hasta que reinicie: usa copytruncate, o apóyate en journalctl y deja esta clave sin definir.

Métricas de Prometheus

metrics.enabled Opcional

Env: METRICS_ENABLED · Por defecto: false

Habilita el endpoint de métricas de Prometheus. Cuando está habilitado, el bouncer expone métricas en /metrics. La comprobación de salud /health se sirve siempre en el listener de métricas, independientemente de este ajuste.

metrics.listen_addr Opcional

Env: METRICS_ADDR · Por defecto: 0.0.0.0

Dirección de escucha del servidor HTTP de métricas.

metrics.listen_port Opcional

Env: METRICS_PORT · Por defecto: 2112

Puerto de escucha del servidor HTTP de métricas.

metrics:
  enabled: true
  listen_addr: "0.0.0.0"
  listen_port: 2112

metrics.routeros_poll_interval Opcional

Env: METRICS_ROUTEROS_POLL_INTERVAL · Por defecto: 30s

Frecuencia con la que se consulta RouterOS para obtener métricas del sistema (carga de CPU, memoria, temperatura). Configúralo en 0 para deshabilitar la recopilación de métricas del sistema.

metrics:
  routeros_poll_interval: "30s"

metrics.track_processed Avanzado

Env: METRICS_TRACK_PROCESSED · Por defecto: true

Habilita el seguimiento del tráfico procesado (no bloqueado) a través del firewall. Cuando está habilitado, el bouncer crea reglas de conteo passthrough en RouterOS para medir todo el tráfico que pasa por las cadenas monitorizadas y envía los datos tanto a Prometheus como a LAPI.

Configúralo en false para deshabilitar el seguimiento del tráfico procesado, lo que evita crear reglas adicionales en el router y reduce la sobrecarga de métricas.

metrics:
  track_processed: true

metrics.pprof_enabled Avanzado

Env: METRICS_PPROF_ENABLED · Por defecto: false

Sirve el perfilador de Go bajo /debug/pprof en el listener de métricas, para investigar dónde gasta CPU o retiene memoria el bouncer:

go tool pprof -seconds 30 http://127.0.0.1:2112/debug/pprof/profile
go tool pprof http://127.0.0.1:2112/debug/pprof/heap

Déjalo apagado salvo que estés perfilando, y pon metrics.listen_addr: "127.0.0.1" mientras esté activo. Dos razones, ambas concretas: un perfil de heap contiene fragmentos de lo que el proceso haya tenido en memoria —tu API key de CrowdSec y la contraseña del router entre ellos— y /debug/pprof/profile mantiene una petición abierta durante toda su ventana de muestreo, lo que lo convierte en una palanca de denegación de servicio en un listener expuesto.

El bouncer registra un aviso en cada arranque mientras esto está activo, de modo que un ajuste olvidado se ve en lugar de pasar callado.

metrics:
  pprof_enabled: false
  listen_addr: "127.0.0.1"

Métricas disponibles

Referencia de métricas de PrometheusLista completa de todas las métricas exportadas con ejemplos de PromQL

Seguridad

El endpoint de métricas no debe exponerse a internet. Usa reglas de firewall o segmentación de red para restringir el acceso.