Registrar un recolector de base de datos

Resumen: qué hace

Administración ▸ Recolectores es el registro de recolectores de InfraGuard (la tabla infr_collector). Saca del código las credenciales y los mapas de host escritos a mano y los guarda como datos. Los recolectores se abstraen por método de acceso (access).

Este artículo trata el recolector access=database. La aplicación InfraGuard se conecta periódicamente a una BD registrada y lee SHOW GLOBAL STATUS · information_schema.processlist · information_schema.tables, escribiendo una serie temporal en infr_db_metric. Nunca lee ni escribe las filas de sus datos: solo métricas de carga y de estructura.

Los recolectores de BD son la fuente de la pantalla de monitorización de carga de BD y de las alertas. Registre aquí una BD y aparecerá automáticamente en ambas.

Cuándo usarlo

• Quiere vigilar la saturación de conexiones, el rendimiento, las consultas lentas y el tamaño de los esquemas de instancias MySQL / MariaDB en producción desde una sola consola.
• Está incorporando un nuevo servidor de BD a la monitorización.
• Quiere reutilizar credenciales de BD que ya existen en .env sin volver a introducir el secreto (cred_ref=env:PREFIX).
• Gestiona varias BD a la vez (valores compartidos + array de elementos): use el editor agrupado.

Disposición

La lista de recolectores muestra tarjetas agrupadas por método de acceso. Las filas access=database se pliegan en una única tarjeta de grupo «Bases de datos» (para evitar la proliferación de tarjetas). El botón [Editar] de la tarjeta de grupo abre el editor agrupado (2 pestañas).

Pestañas del editor agrupado

Aunque la interfaz muestre una sola tarjeta de grupo, al guardar se hace upsert de cada elemento como su propia fila db@{alias} (access=database). La cadena de recolección, Servicio ▸ Base de datos y la asignación de destinos de las alertas funcionan todas por recolector. Quitar un elemento elimina su fila db@.

Campos por recolector (infr_collector)

Cómo se usa

1. Registrar una BD nueva (editor agrupado)

1. Vaya a Administración ▸ Recolectores.
2. En la tarjeta de grupo «Bases de datos», pulse [Editar] → pestaña Básico y rellene los valores compartidos.
   • driver: mysql o mariadb
   • port: por defecto 3306
   • database: solo el esquema de conexión predeterminado; déjelo vacío para conectar a information_schema (el alcance de la recolección lo deciden los permisos de la cuenta)
   • username: la cuenta de monitorización (p. ej. infra_ro)
   • umbral de cola (slow_time): cuenta como «en espera/atascada» toda consulta que lleve ejecutándose más de estos segundos (1–60 s, por defecto 2)
   • cred_ref: env:PREFIX para reutilizar credenciales de .env
3. Pestaña Bases de datos → [Añadir BD] → por elemento: alias (obligatorio) · host/IP · contraseña opcional.
4. [Guardar]. Cada elemento se crea o se actualiza como una fila db@{alias}.

2. Tratamiento del secreto: dos vías

(A) Introducir la contraseña directamente: escrita en el campo de contraseña, se guarda cifrada en secret_enc. La lista y las respuestas de la API nunca exponen el texto plano; solo se devuelven los booleanos has_secret/has_db_pw.

La contraseña es de solo escritura. Al editar, dejar el campo de contraseña vacío conserva el valor existente (no lo sobrescribe). Para eliminarla explícitamente, use la opción de borrado.

(B) Reutilizar credenciales de .env (cred_ref=env:PREFIX): no guarde la contraseña en la BD; haga referencia a un conjunto de credenciales que ya está en .env. DbCollectorService::resolveConn() lee estas claves:

Los valores rellenados en config tienen prioridad; los vacíos se completan desde las variables de entorno PREFIX_* (host/port/database/username/password).

3. Consultas en espera a nivel de servidor: el permiso PROCESS

Las dos métricas principales (saturación de conexiones = Threads_running/Threads_connected/max_connections, y QPS · tasa de lentas = ΔQuestions/ΔSlow_queries) se pueden recolectar con una cuenta simple (USAGE). Sin embargo, la agregación de consultas en espera a nivel de servidor y el análisis del tamaño de todos los esquemas requieren permisos adicionales.

• Sin PROCESS → solo se ve la processlist de la propia conexión (waiting_scope=0).
• Con PROCESS → se agregan todas las sesiones (waiting_scope=1, a nivel de servidor).

Script de cuenta con privilegios mínimos, para ejecutarlo una vez como root en cada host de BD de destino: sql/infr_db_monitor_grant.sql.

-- Cuenta dedicada de solo lectura (restrinja el host de origen a la IP del servidor de la aplicación InfraGuard)
CREATE USER 'infra_ro'@'%' IDENTIFIED BY 'CHANGE_ME_TO_A_STRONG_SECRET';

-- Permisos globales de observación (NO de acceso a los datos)
GRANT PROCESS, REPLICATION CLIENT ON *.* TO 'infra_ro'@'%';

-- Análisis del tamaño de los esquemas (todas las BD, solo lectura). Para una sola BD, restrinja a design.*
GRANT SELECT ON *.* TO 'infra_ro'@'%';

-- Aislamiento del radio de impacto: evita el monopolio de conexiones (lección del incidente [1040] del 2026-08-06)
ALTER USER 'infra_ro'@'%' WITH MAX_USER_CONNECTIONS 5;
FLUSH PRIVILEGES;

MariaDB 10.5+ puede usar BINLOG MONITOR en lugar de REPLICATION CLIENT. PROCESS y SELECT son idénticos.

4. Ejecutar y verificar la recolección

La recolección la realiza el comando artisan infr:collect-db. El panel del planificador del lanzador de desarrollo (composer dev) lo invoca cada minuto.

# Muestrear un recolector una vez de inmediato (omitiendo el control de la política de operaciones)
php artisan infr:collect-db --key=db@blue --force

# Recolectar todas las BD registradas (is_run=1) según la política
php artisan infr:collect-db

Que la recolección se ejecute o no lo decide la Política de operaciones.

Use --key para probar un recolector de base de datos concreto. Los botones [Probar] / [Sincronizar código] son solo para recolectores access=web y no se aplican a los recolectores de base de datos: verifíquelo con el comando anterior.

5. Umbrales de estado

DbCollectorService::statusOf() decide entre up y degraded comparando con los umbrales de la Política de operaciones.

Fuentes de datos

Sin fugas de conexiones. DbCollectorService::withConn() crea una conexión en tiempo de ejecución por muestra y la cierra de inmediato en finally mediante DB::purge. Un tiempo de espera de PDO (5 s por defecto) impide que las peticiones web y las tareas programadas se bloqueen por la latencia remota. Nunca lance un demonio de bucle infinito desde el planificador: agota el pool de conexiones compartido de MySQL (el incidente [1040] Too many connections del 2026-08-06).

Acceso

• Acceso a la pantalla y todo el CRUD: administrador (nivel ≥ 10); CollectorController::isAdmin() comprueba infr_user_level >= 10 en la sesión (demo=1 y staff=5 no pueden entrar).
• Si falla, 403. Guardar, eliminar y fill se registran todos en la auditoría de infr_audit_log/los logs.
• fill/{key} (inyectar la configuración en un mash-up de Inventario ▸ Herramientas) es una excepción de inyección de secretos (documentada como §Opción B): solo administradores y con auditoría.

Consulte los niveles de acceso para ver el esquema completo.

Resolución de problemas y preguntas frecuentes

• Las consultas en espera solo muestran mi propia conexión: falta el permiso PROCESS, de modo que waiting_scope=0. Concédalo con sql/infr_db_monitor_grant.sql.
• El tamaño de los esquemas solo muestra algunas BD: necesita un permiso SELECT global (o SELECT sobre esa BD concreta).
• Cambié la contraseña y no se aplicó: al editar, un campo de contraseña vacío conserva el valor existente. Introduzca un valor nuevo para sustituirlo.
• La tarjeta muestra brevemente down (rojo) en modo economy: la recolección se retrasó porque no hay ningún usuario de consola presente. Entrar en la pantalla dispara una muestra bajo demanda (ensureFresh), o cambie al modo always (véase la prevención del falso rojo en Servicio ▸ Base de datos).
• Quiero cambiar la clave: la clave db@{alias} es inmutable al editar (para la estabilidad de la asignación de destinos de las alertas). Añada un elemento con un alias nuevo para acuñar una clave nueva.
• Soy nivel 5 pero se me deniega el acceso: algunos textos dicen «nivel 5 o superior», pero el control real es administrador (nivel ≥ 10).

Relacionado

• Servicio ▸ Base de datos: la pantalla de monitorización de carga y estructura de BD
• Conceptos de ajuste de BD: conceptos de bloqueos, caché e índices
• Infraestructura ▸ Alertas: alertas por condiciones de BD (cola de espera · consultas lentas)
• Política de operaciones: modo de recolección, intervalo, umbrales de estado
• Niveles de acceso: el control por nivel de administrador
• Registro de auditoría: historial de cambios de los recolectores