HQbird para desarrolladores
Para desarrolladores de aplicaciones
¿Qué consulta optimizar primero? ¿Qué código generó el error? ¿Quién mantiene el récord en un conflicto? El agente recopila las respuestas a partir del trace y las estadísticas en el propio servidor. El desarrollador las ve en un navegador y no inicia sesión en el servidor.
- 1 min archivos de trace
- 3 ventanas al día informe de rendimiento
- por plan agrupación de consultas
- 15 min búsqueda de conflictos
- REST API local para scripts y CI
trace · process_traces · perf report
Informe de rendimiento
El agente mantiene una sesión de trace abierta todo el tiempo. Cada minuto comprime la salida en un archivo y calcula los totales de cada consulta. Cuando termina una ventana, el agente combina los minutos en un informe: las consultas más lentas y las más pesadas por fetches, lecturas y escrituras. Cada consulta muestra su número de ejecuciones.
- 1Sesión de tracefbtracemgr se ejecuta todo el tiempo; un watchdog reinicia una sesión perdida
- 2Archivo por minutosalida de trace comprimida una vez por minuto
- 3Totales por minutopara cada consulta: ejecuciones, tiempo, fetches, lecturas, escrituras, marcas
- 4Informe de ventanadentro de los 5 minutos posteriores al fin de la ventana; hasta 20 consultas en cada ranking
- 5✓ HQ MonitorPágina Perf Report; enlace desde el informe de estado
Por qué agrupar por plan
Si un programa inserta valores directamente en el texto SQL, cada valor genera un texto nuevo. En un caso real, el número de textos distintos creció de 204 a 83.825 por minuto. Miles de consultas «diferentes» son en realidad una sola consulta con un solo plan. Por eso, de forma predeterminada, el agente agrupa las consultas por una clave: los primeros 10 caracteres del SQL sin comentarios, más el plan de ejecución. Una consulta sin plan conserva su texto completo. Puedes cambiar el modo en la configuración del agente, campo «Perf group by»: por plan o por texto SQL completo. Con el texto, los archivos y los informes se vuelven mucho más grandes. Cambia el modo en el ejemplo de abajo y compara los rankings.
Consultas en un minuto
Ranking por fetches
| Tabla del informe | Qué muestra |
|---|---|
| Top SQL por duración | Las ejecuciones más lentas: tiempo y número de registros. |
| Top SQL por fetches, lecturas, escrituras | Totales de la ventana: ejecuciones, tiempo, fetches, lecturas, escrituras, marcas; proporción sobre toda la ventana; promedio y máximo por ejecución. |
| Procesos y direcciones | Carga por programa y por dirección de cliente: conexiones, tiempo, número de planes y consultas distintos. |
| Fila de consulta | SQL completo, PLAN, parámetros y estadísticas por tabla: natural, index, update, insert, delete, backout, purge, expunge. |
| Diez rankings en pestañas | Duración, frecuencia, tiempo total, fetches, lecturas, escrituras, planes, etiquetas, procedimientos y triggers. Para cada métrica, ves la dispersión de valores. |
| Ejecución de muestra | Cuándo se ejecutó, qué cliente y desde qué dirección, en qué base de datos. Si la ejecución terminó con un error, lo ves; cada consulta tiene un contador de ejecuciones fallidas. |
| Ejecuciones por hora | Cuántas veces y cuánto tiempo se ejecutó la consulta en cada hora de la ventana. |
| Bases de datos | Totales por base de datos del servidor y las bases de datos principales de cada consulta. |
Comparación, historial e informe bajo demanda
El informe de ventana responde a la pregunta «qué fue pesado hoy». Tres nuevas funciones responden a las preguntas «qué cambió» y «qué pasó en esta hora».
- Comparar dos ventanasDos informes lado a lado: qué consultas se volvieron más lentas, cuáles aparecieron y cuáles desaparecieron.
- Historial de consultas de 30 díasCómo cambiaron el tiempo y el número de ejecuciones de una consulta de ventana en ventana.
- Filtro por base de datosUn informe solo para una base de datos. Un enlace en la página de la base de datos lleva a la página del informe.
- A los traces del minutoDesde una consulta del informe a los traces del minuto en que se ejecutó.
- Informe bajo demandaEl botón Build report… genera un informe para cualquier rango de hasta 24 horas. Filtros: base de datos, duración mínima, programa. El agente genera un informe de este tipo a la vez y conserva los últimos 20.
- Buscar y descargarUn campo de búsqueda para el texto de la consulta. Puedes descargar el archivo de origen del informe.
- El informe incompleto se marcaSi aún no han llegado algunos archivos de trace, el informe se marca como incompleto. El informe solo conserva la parte superior de cada ranking, por lo que la página dice «no está en el ranking», no «no se ejecutó».
- Procedimientos y triggersEstos rankings se llenan cuando la configuración de trace activa el registro de finalización de procedimientos y triggers. De forma predeterminada, este registro está desactivado.
- Desde el informe de estadoEl botón Perf report abre la ventana correcta. Las filas de consulta están marcadas y la primera ya está expandida.
- Consulta y tablaLa pestaña Queries de las estadísticas de gstat vincula las consultas con las tablas e índices que leen.
- Un minuto en el gráfico de la base de datosUn clic en un minuto muestra las consultas pesadas del trace y todas las conexiones de ese minuto.
- Copiar SQLCon o sin parámetros, directamente en tu propia herramienta. En modo demo, los botones están ocultos.
trace · Errors
Errores SQL con datos del cliente
Un usuario dice «el programa dio un error». La página Errors muestra cada error de Firebird del trace: hora, conexión, base de datos, texto y cliente. Con el nombre del programa, la dirección y la función de Firebird, puedes encontrar fácilmente el error en tu código.
Bloque de error en el trace
Fila en la página Errors
- Mismos errores — una filaUna fila por minuto, base de datos y tipo de error, con un contador ×N. Una sugerencia muestra la primera y la última vez y el número de conexiones.
- FiltrosInclude y Exclude por texto, base de datos, programa, dirección y función. Un clic en un programa o dirección conserva solo sus errores.
- Exportar CSVTodas las filas con los filtros aplicados, en UTF-8 con BOM: Excel abre el archivo en columnas de inmediato.
- Si no hay programaMuchos drivers JDBC y .NET no envían el nombre del programa. Entonces la fila del cliente es más corta.
trace_monitor_conflicts · find_deadlocks
Conflictos y deadlocks
El error «update conflicts with concurrent update» dice poco por sí solo. Necesitas saber qué hizo la otra transacción. Para ello, el agente mantiene una segunda sesión de trace configurada para cambios de datos y errores. Cada 15 minutos busca conflictos y genera un informe.
Cómo leer el informe
A la izquierda está la lista de minutos con conflictos. Cada grupo es una transacción que causó conflictos: el número de transacción y la hora del error.
La columna izquierda muestra los errores: conexión, programa, códigos de Firebird y la consulta que falló. La columna derecha muestra las consultas exitosas de la transacción competidora: hora, conexión, número de transacción, programa. Cada consulta tiene su SQL, parámetros, estadísticas y tablas.
La dirección de la página conserva la fecha y el minuto. Puedes enviar el enlace a un colega.
| Parámetro | Valor predeterminado | Significado |
|---|---|---|
| Búsqueda de conflictos | cada 15 minutos | Se omite el último minuto: el trace todavía lo está escribiendo. |
| Profundidad de búsqueda | 3 horas | Cuánto historial anterior al conflicto revisar al buscar las consultas de la otra transacción. |
| Retención del trace en bruto | 6 horas | Los archivos en bruto de la sesión de conflicto no se acumulan en el servidor. Los informes se conservan y se envían a HQ Monitor. |
gstat · índices · metadatos
Cómo cambia la base de datos
Una vez al día el agente toma estadísticas completas de gstat. HQ Monitor analiza el archivo: tamaño de tablas e índices, versiones de registros, BLOBs, profundidad de índices. La pestaña «Análisis y recomendaciones» indica qué está mal y qué hacer.
| Pestaña | Qué le aporta al desarrollador |
|---|---|
| Tablas | Tamaño de datos, índices y BLOBs, número de registros, versiones de registros y las versiones máximas de un registro. |
| Índices | Profundidad, páginas, valores únicos, duplicados. Profundidad 4 es una fila amarilla, 5 o más es rojo. |
| Consultas y enlaces | Qué consultas leen una tabla o un índice. Datos de informes de rendimiento cercanos en el tiempo a la instantánea. |
| Tendencias | Comparación de 5, 10, 20 o 30 instantáneas; umbral de cambio del 10%, 2% o 0,5%. La previsión «+25%» a partir de tres o más instantáneas. |
| Exportación | JSON con las mediciones y Excel con el análisis completo. |
- Estadísticas de índicesDesactivadas de forma predeterminada; las activas en la configuración del agente. Entonces, cada 6 horas el agente cuenta los índices inactivos y los índices con baja selectividad. Un índice no reconstruido tras una restauración es grave en el informe de estado.
- Previsión de crecimientoLa etiqueta «+25%» en la tabla de la base de datos muestra la tabla o el índice de crecimiento más rápido y abre la previsión.
- Exportación del esquemaEl agente exporta los metadatos de la base de datos con
isql -xy conserva archivos por fecha. - Seguimiento de metadatosDesactivado de forma predeterminada; lo activas en la configuración del agente. Cada 6 horas el agente compara la nueva exportación del esquema con la anterior y registra cuándo cambió el esquema.
LWM · MON$ · clientes
Conexiones: transacciones largas y versiones de clientes
Una transacción olvidada ralentiza toda la base de datos: las versiones de registros se acumulan y la recolección de basura se detiene.
Cada minuto el agente escribe los contadores de transacciones y los datos de conexión. En el gráfico de la base de datos, Next − OAT crece si una transacción permanece abierta mucho tiempo. La tabla de conexiones de ese minuto, ordenada por Act.Tran, muestra el programa, la dirección y el proceso que mantiene la transacción. Más sobre los contadores en la página de estado del servidor.
Una vez al día el agente lee qué bibliotecas cliente se conectan a la base de datos y cuántas conexiones tiene cada una. La fila «No detectado. ¿Versión antigua?» normalmente indica una biblioteca cliente antigua.
- Métricas MON$Una vez por hora: memoria por programa, las 5 conexiones con más memoria y las 5 con mayor carga.
- Clientes antiguos sin falsas alarmasEl hallazgo de «clientes antiguos» cuenta solo bibliotecas fbclient. Los controladores que funcionan sin fbclient no se cuentan en él.
- Transacciones largas en el informeEl informe de estado marca las transacciones largas y el crecimiento de Next − OAT. El hallazgo indica el usuario, el programa y la dirección y ofrece un comando listo para desconectar.
API local · Prometheus · HQbird MCP
Tus scripts, CI y asistente de IA
Todo lo que ves en HQ Monitor está disponible desde tus propias herramientas. La API local del agente escucha solo en loopback, y cada solicitud lleva un token Bearer. Las tareas pesadas se ejecutan de forma asíncrona: la respuesta da un número de operación y con él lees el estado. El agente escribe en el registro de auditoría cada solicitud que modifica el servidor y cada rechazo 401 o 403. Las solicitudes de lectura no van al registro.
# Local API port = 10000 + Firebird port: here Firebird uses 3055, so 13055 # server status: the same snapshot as in the health report curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/status # latest performance report and latest conflict report curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/artifacts/server/traces/perf-report/latest curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/artifacts/server/traces/deadlocks/latest # run a backup before a migration in CI and wait for the result curl -X POST -H "Authorization: Bearer $TOKEN" -d '{"job_id":"nightly","reason":"before migration"}' \ http://127.0.0.1:13055/v1/jobs/vbackup/run curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/runs/<run_id>
| Ruta | Qué proporciona |
|---|---|
/v1/status | Instantánea del estado del servidor, completa o por sección, por ejemplo copias de seguridad. |
/v1/databases | Lista de bases de datos activas. |
/v1/artifacts/… | Datos del agente: LWM (Light-weight Monitoring) por minuto, gstat, estadísticas de índices, métricas, la última exportación del esquema, informes de trace. |
/v1/jobs/{job}/run | Ejecutar una tarea: copia de seguridad, restauración, sweep, comprobación de la base de datos, recálculo de estadísticas de índices, script SQL. Una repetición con la misma clave no ejecuta la tarea dos veces. |
Las métricas de Prometheus no pasan por la API local. Tienen su propia dirección: de forma predeterminada 127.0.0.1, puerto 25000 + puerto de Firebird. Tienen su propio token Bearer. La exportación está desactivada de forma predeterminada; la activas en la configuración del agente. Métricas: LWM, CPU y memoria, discos, límites del sistema operativo, archivos temporales.
Asistente de IA en el IDE
HQbird MCP conecta Firebird y los datos del agente con Claude Code, Cursor, Codex y otros clientes MCP. El asistente ve los informes del agente y trabaja con la base de datos bajo control humano: una persona confirma las acciones peligrosas.
Plan e índice
Plan de consulta y consejo sobre índices, con una reverificación del plan tras crear el índice. Una comprobación de compilación de la consulta antes de ejecutarla.
Comparar dos bases de datos
Diferencias de esquema y datos, por ejemplo entre desarrollo y el banco de pruebas.
Planificar, confirmar, revertir
Una migración con un plan, una confirmación y un plan de reversión.
← Volver a la descripción general de HQbird 2027 · Estado del servidor en detalle →