Esta página fue traducida automáticamente. Lee el original en inglés. English

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.

  1. 1Sesión de tracefbtracemgr se ejecuta todo el tiempo; un watchdog reinicia una sesión perdida
  2. 2Archivo por minutosalida de trace comprimida una vez por minuto
  3. 3Totales por minutopara cada consulta: ejecuciones, tiempo, fetches, lecturas, escrituras, marcas
  4. 4Informe de ventanadentro de los 5 minutos posteriores al fin de la ventana; hasta 20 consultas en cada ranking
  5. 5✓ HQ MonitorPágina Perf Report; enlace desde el informe de estado
Tres ventanas de informe al día: mañana 07:00–12:30, día 12:31–18:00, noche 18:01–06:59; el agente comprueba las ventanas cada 5 min, por lo que un informe aparece dentro de los 5 min posteriores al fin de una ventana
Ventanas predeterminadas. Mañana, día y noche. Puedes cambiar las ventanas y su número en la configuración del agente. Un minuto sin datos se omite; el informe se sigue generando.

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 informeQué muestra
      Top SQL por duraciónLas ejecuciones más lentas: tiempo y número de registros.
      Top SQL por fetches, lecturas, escriturasTotales de la ventana: ejecuciones, tiempo, fetches, lecturas, escrituras, marcas; proporción sobre toda la ventana; promedio y máximo por ejecución.
      Procesos y direccionesCarga por programa y por dirección de cliente: conexiones, tiempo, número de planes y consultas distintos.
      Fila de consultaSQL completo, PLAN, parámetros y estadísticas por tabla: natural, index, update, insert, delete, backout, purge, expunge.
      Diez rankings en pestañasDuració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 muestraCuá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 horaCuántas veces y cuánto tiempo se ejecutó la consulta en cada hora de la ventana.
      Bases de datosTotales 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

      2026-10-17T12:00:05.0000 (4521:0x7f..) ERROR AT JStatement::execute /db/shop.fdb (ATT_370201, SHOP_APP:NONE, UTF8, TCPv4:10.0.0.5/50123) C:\Shop\shop.exe:7712 335544665 : violation of PRIMARY or UNIQUE KEY constraint "UK_ITEM"

      Fila en la página Errors

      tstmpattIDdb · errTxt 12:00370201/db/shop.fdb ×3 335544665 : violation of PRIMARY or UNIQUE KEY constraint "UK_ITEM" C:\Shop\shop.exe:7712 · 10.0.0.5/50123 · JStatement::execute

      • 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.

      La transacción 1001 modificó un registro; la 1002 intenta modificar el mismo registro y recibe un error; el informe encuentra las consultas de la 1001 por su número

      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.

      Página de conflictos. Minutos a la izquierda, el grupo de transacciones a la derecha: proceso y códigos de error.
      ParámetroValor predeterminadoSignificado
      Búsqueda de conflictoscada 15 minutosSe omite el último minuto: el trace todavía lo está escribiendo.
      Profundidad de búsqueda3 horasCuánto historial anterior al conflicto revisar al buscar las consultas de la otra transacción.
      Retención del trace en bruto6 horasLos 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.

      Análisis y recomendaciones. Problema, número de casos, objetos vinculados, recomendación y acción.
      Tendencias. Comparación de las últimas instantáneas: qué creció y cuándo un objeto crecerá un 25%.
      PestañaQué le aporta al desarrollador
      TablasTamaño de datos, índices y BLOBs, número de registros, versiones de registros y las versiones máximas de un registro.
      ÍndicesProfundidad, páginas, valores únicos, duplicados. Profundidad 4 es una fila amarilla, 5 o más es rojo.
      Consultas y enlacesQué consultas leen una tabla o un índice. Datos de informes de rendimiento cercanos en el tiempo a la instantánea.
      TendenciasComparació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ónJSON 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 -x y 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.

      Versiones de clientes. La cadena de versión del cliente y el número de conexiones. Las conexiones propias del agente aparecen como una fila aparte.
      • 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>
      RutaQué proporciona
      /v1/statusInstantánea del estado del servidor, completa o por sección, por ejemplo copias de seguridad.
      /v1/databasesLista 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}/runEjecutar 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.

      Consulta

      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.

      Esquema

      Comparar dos bases de datos

      Diferencias de esquema y datos, por ejemplo entre desarrollo y el banco de pruebas.

      Migración

      Planificar, confirmar, revertir

      Una migración con un plan, una confirmación y un plan de reversión.

      Más: HQbird MCP

      ← Volver a la descripción general de HQbird 2027 · Estado del servidor en detalle →