Esta página describe Calíope 1.5, la versión que estamos construyendo ahora mismo. La 1.4 está terminada y en revisión de App Store, y la tienda sirve hoy la 1.3 en el Mac y la 1.2 en iPad. El changelog dice en qué versión llegó cada función.
Añade un botón «Abrir en Calíope» a cada tema. Sólo funciona con la app instalada.
Monitorea conexiones activas, QPS y estado del servidor desde la pantalla de inicio o el escritorio sin abrir la app.
Dónde está: Widget › General
El Widget de Calíope muestra métricas clave del servidor —MySQL, MariaDB o PostgreSQL— en tiempo real directamente en el escritorio de macOS o en la pantalla de inicio del iPad, sin necesidad de abrir la aplicación.
Métricas mostradas:
- Conexiones activas — número de conexiones abiertas y el máximo configurado en el servidor.
- QPS o TPS — el caudal del servidor: consultas por segundo en MySQL y MariaDB, transacciones por segundo en PostgreSQL. Son dos magnitudes distintas, así que el rótulo dice cuál de las dos estás viendo.
- Uptime — tiempo en línea del servidor en formato Nd Nh Nm.
- Hilos activos (en las versiones mediana y grande del widget) — número de hilos en ejecución.
- Consultas lentas/seg (mediana y grande) — tasa de consultas lentas.
- Acierto caché (mediana y grande) — porcentaje de lecturas servidas desde la caché del servidor.
- Insignia de estado — verde (activo y datos frescos), rojo (el servidor dejó de responder en el último sondeo) o ámbar (los datos ya no se pueden dar por actuales). Cuando todavía no hay ningún dato no hay insignia: el widget te pide que elijas servidor y no afirma nada más.
- Barra de conexiones — barra visual de color semántico: cian (bajo), ámbar (>65%), rojo (>85%).
Tamaños disponibles:
- Pequeño — conexiones activas con su barra, el nombre del servidor y la insignia de estado. Nada más: es el tamaño donde la cifra tiene que caber entera.
- Mediano — añade el caudal, los hilos activos y la tasa de acierto de caché — o el uptime en su lugar, si el motor no publica caché.
- Grande — todo lo anterior más el uptime y las consultas lentas por segundo.
- Extra grande — lo mismo repartido en dos columnas. En el iPad va en la pantalla de inicio; en el Mac sólo en el escritorio, porque el Centro de notificaciones no acepta este tamaño.
- Pantalla de bloqueo — rectangular (iPad) — nombre del servidor, conexiones activas/máx y QPS.
- Pantalla de bloqueo — circular (iPad) — anillo con el ratio de uso de conexiones y su número absoluto en el centro.
- Pantalla de bloqueo — en línea (iPad) — una sola línea con el número de conexiones activas junto al reloj.
Cómo añadir el widget:
- macOS: haz clic derecho en el escritorio y selecciona Editar widgets. Busca Calíope y arrastra el tamaño deseado al escritorio o al Centro de Notificaciones.
- iPad: mantén pulsada la pantalla de inicio hasta que los íconos vibren, toca Editar arriba a la izquierda y luego Añadir widget, busca Calíope y elige el tamaño.
Frecuencia de actualización:
La cadencia la eliges tú, y de ella depende todo lo demás. Con el Tablero abierto, las métricas se escriben al ritmo de su selector de actualización (de 1 a 30 segundos). Con el Tablero cerrado, hace falta activar Preferencias › Widget › Actualizar en segundo plano y elegir ahí el intervalo: 30 segundos, 1, 5 o 15 minutos.
Cuándo el badge se pone en ámbar:
Cuando los datos llevan sin renovarse más de tres veces esa cadencia, con un suelo de 90 segundos. Con el intervalo en 5 minutos el widget aguanta 15 en verde; con 15 minutos, 45. El techo se deriva de tu configuración en vez de ser un número fijo, porque un widget que se pone en ámbar mientras el refresco funciona exactamente como se pidió no está avisando de nada.
Y si nunca hubo datos —porque no has elegido servidor— el widget no dice Sin datos: te pide que elijas uno.
Un segundo widget que enseña la granja entera en vez de un servidor: cuántos se vigilan, cuántos necesitan atención y cuál está peor.
Dónde está: Widget › Widget, galería, pantalla de inicio
El widget de Métricas mira un servidor. Éste los mira todos, y contesta otra pregunta: ¿hay algo que tenga que ir a ver?
Dónde funciona
- iPhone y iPad. En macOS sólo está el widget de métricas.
Tamaños disponibles:
- Pequeño — el peor estado de la granja y cuántos servidores se vigilan.
- Mediano — la lista, hasta tres servidores, los peores delante.
- Grande — la misma lista, hasta seis. En los dos, lo que no cabe se dice con «y N más», y a tamaños de accesibilidad caben menos filas.
De dónde sale el dato
- Del Monitor de salud, en esta misma app. Cada sondeo escribe el resultado en el contenedor que el widget lee.
- No viaja por la red ni depende de iCloud: lo que ves en la pantalla de inicio se midió en este aparato.
- Si la publicación a iCloud está apagada, el widget sigue funcionando. Ese interruptor decide qué sale del aparato, no lo que tu propia pantalla te enseña.
Cuando no dice nada
- Abre el Monitor de salud una vez: todavía no se ha medido nada en este aparato.
- No se está vigilando ningún servidor: el monitor corrió y su lista está vacía.
El color nunca es la única señal: cada estado lleva su forma, y lo que pronuncia VoiceOver dice el recuento, el peor y cuántos necesitan atención.
Un toque o clic en el widget abre Calíope y conecta automáticamente al servidor anclado.
Dónde está: Widget › Deep link
Al tocar o hacer clic en el widget de Calíope, la aplicación se abre y conecta directamente al servidor que ese widget tiene elegido, llevándote al Tablero del workspace correspondiente.
Cómo funciona:
- El widget incluye un deep link del tipo caliope://server/<id> que apunta al servidor elegido en la configuración de ese widget, no al que esté enseñando en ese momento. La diferencia importa cuando todavía no hay métricas: el widget dice «Elige un servidor» y aun así te abre el suyo.
- Si la app no estaba abierta, se lanza primero y luego abre la sesión.
- Si la app ya estaba abierta y existe una sesión activa con ese servidor, simplemente la trae al frente.
Qué servidor abre:
- El que elegiste al añadir el widget, o el que hayas puesto después: mantén pulsado el widget (iPad) o haz clic derecho (Mac) → Editar widget → Servidor.
- Si ese widget no tiene ninguno elegido, abre el del dato que esté enseñando, que es el del último Tablero activo.
- El perfil anclado de Preferencias › Widget es otra cosa: es el servidor que se refresca en segundo plano, no el que abre el enlace.
Si no hay servidor elegido, el widget te pide que elijas uno; al tocarlo se abre Calíope en el Gestor de Conexiones.
Cada widget puede monitorear un servidor distinto — configúralo al añadirlo o después editándolo.
Dónde está: Widget › Configuración
El widget de Calíope es configurable: al añadirlo al escritorio o a la pantalla de inicio, el sistema pregunta qué servidor debe mostrar. Así puedes tener múltiples widgets simultáneos, cada uno mostrando métricas de un servidor distinto (producción, staging, réplica, etc.).
Configurar al añadir el widget
- macOS: haz clic derecho en el escritorio y elige Editar widgets; arrastra al escritorio la variante que quieras. Al soltarla no aparece ningún selector: el servidor se elige después, con clic derecho sobre el widget ya colocado → Editar “Calíope” → Servidor.
- iPad: mantén pulsada la pantalla de inicio, toca Editar → Añadir widget, busca Calíope y elige el tamaño. El servidor se elige después, manteniendo pulsado el widget ya colocado → Editar widget → Servidor.
Cambiar el servidor de un widget existente
- macOS: haz clic derecho sobre el widget → Editar “Calíope” → cambia el parámetro Servidor.
- iPad: mantén pulsado el widget → Editar widget → cambia el parámetro Servidor.
Qué se sincroniza al App Group
- Calíope publica un catálogo mínimo (id, name, host) de tus perfiles al iniciar la app y cada vez que guardas cambios en el Gestor de Conexiones. El widget lee ese catálogo para poblar el selector; no ve contraseñas, claves SSH ni certificados. En el catálogo sólo entran los perfiles cuyo motor puede publicar métricas: los de MongoDB no se ofrecen, porque elegirlos dejaría el widget vacío para siempre.
- Las métricas se guardan por perfil (caliope_widget_metrics_<id>.json), así cada widget lee las suyas independientemente de cuál sesión esté activa en la app.
Widget sin servidor configurado
- Si no eliges ningún servidor, el widget muestra las métricas del último servidor activo en la app. Pero si sí eliges uno y todavía no hay métricas suyas, no enseña las de otro: dice que no hay datos. Un widget fijado a un servidor no puede acabar enseñando el nombre y las cifras de otro.
Cómo comparte Calíope las métricas con la extensión del Widget en las tres.
Dónde está: Calíope › Preferencias › Widget
El widget de Calíope vive en una extensión separada que no puede leer la memoria de la app principal. Para que aparezcan datos en tiempo real, la app y la extensión comparten un contenedor común a través de un App Group.
Identificador
- iPad: group.org.caliope.widget.
- macOS: el mismo, precedido del identificador del equipo (ASH9Q9BLUY.group.org.caliope.widget) — allí el sistema lo exige así.
El mismo contenedor alimenta los dos widgets de iOS: el de métricas y el de salud de la granja. En iPhone y iPad es el mismo binario, así que es el mismo App Group.
Qué se comparte
- Las métricas más recientes de cada servidor (conexiones activas, caudal —QPS o TPS según el motor—, uptime, hilos, queries lentas/s, tasa de acierto de caché).
- El timestamp de la última actualización y la cadencia con la que se escribió. El widget usa las dos para decidir cuándo poner el badge en ámbar: el techo es tres veces la cadencia, con un suelo de 90 segundos.
- El identificador del perfil anclado y la URL caliope://server/<id> para el deep link.
Cómo se actualiza
- Mientras la app principal está abierta y conectada, WidgetDataStore escribe en el App Group cada vez que llega un tick de polling.
- Tras escribir, Calíope llama a WidgetCenter.shared.reloadAllTimelines() para que el widget refresque a la próxima oportunidad que el sistema le conceda.
- Si la app se cierra, el widget sigue mostrando los últimos datos hasta que el sistema le pida un nuevo timeline. Pasado el techo derivado de la cadencia, el badge cambia a ámbar y la etiqueta a Sin datos.
Reinstalar la app o cambiar de Apple ID
- El App Group está vinculado al Team ID del desarrollador. Al instalar Calíope desde Mac App Store o App Store, macOS/iOS crea el contenedor automáticamente. No necesitas configurar nada.
- Si transfieres el iPad a otro Apple ID, el contenedor se elimina junto con la app y el widget queda vacío hasta que vuelvas a iniciar Calíope al menos una vez.
El idioma no viaja por aquí. Se elige por aplicación en los ajustes del sistema, y esa elección alcanza también a la extensión: el widget lee el suyo y habla el mismo que la app sin que nadie se lo tenga que pasar.
Diagnóstico paso a paso cuando el badge está en ámbar y no aparecen métricas.
Dónde está: Widget › Solución de problemas
Si el widget de Calíope muestra el badge ámbar con la etiqueta Sin datos, significa que los datos llevan demasiado tiempo sin renovarse. «Demasiado» no es un número fijo: es tres veces la cadencia con la que se escribieron, con un suelo de 90 segundos.
Antes de nada, mira qué pone el widget:
- Elige un servidor — nunca ha habido datos. Es el punto 1.
- Sin datos — los hubo y han caducado. Es todo lo demás.
- Offline, en rojo — el refresco en segundo plano intentó sondear y el servidor no respondió. Las cifras que ves son las últimas ciertas, y por eso salen atenuadas.
1. ¿Hay un servidor elegido?
- Cada widget elige el suyo: mantén pulsado (iPad) o haz clic derecho (Mac) sobre el widget → Editar widget → Servidor.
- Si no eliges ninguno, el widget cae al último servidor activo en la app, y sin ninguno tampoco, se queda sin nada que enseñar.
2. ¿Quién está escribiendo las métricas?
Sólo hay dos escritores, y si no está ninguno el widget se queda quieto por definición:
- El Tablero abierto en ese servidor. Al cerrar la pestaña, las cifras se quedan: el widget sigue enseñando la última medida y la marca como vieja cuando toca. Antes se borraban al cerrar, y eso dejaba a todos los widgets sin nada justo al salir de la app.
- El refresco en segundo plano, en Preferencias › Widget. Hay que activarlo y elegir ahí el perfil anclado; es lo que mantiene el widget vivo con la app de fondo.
3. ¿Y si el intervalo es largo?
Con 15 minutos, el widget aguanta 45 en verde y luego pasa a ámbar aunque todo funcione: sencillamente ha pasado el tiempo entre dos escrituras. Si prefieres que el ámbar llegue antes, baja el intervalo en Preferencias › Widget.
4. ¿Has reiniciado el dispositivo?
Tras un reinicio el widget no tiene estado hasta que la app principal vuelve a ejecutarse al menos una vez.
5. ¿Lo está bloqueando el sistema?
- En iPad, Ajustes › General › Actualización en segundo plano debe estar activado para Calíope, o el refresco programado no llega a correr.
- En Mac no hay equivalente, pero tampoco hay quien escriba con Calíope cerrada: el widget conserva lo último que recibió y lo marca como viejo cuando toca.
6. Si nada de lo anterior encaja
Quita el widget del escritorio o de la pantalla de inicio y vuelve a añadirlo: eso obliga al sistema a rehacer el timeline desde cero.
Palabras clave: sin datos, no data, widget, badge ámbar, troubleshoot, solucionar, anclar perfil, actualización en segundo plano, reiniciar caché, diagnóstico