Widget

Monitora connessioni attive, QPS e stato del server dalla schermata home o dalla scrivania senza aprire l'app.

Dove si trova: Widget › Generale

Il Widget di Calíope mostra metriche chiave del server —MySQL, MariaDB o PostgreSQL— in tempo reale direttamente sulla scrivania di macOS o sulla schermata home dell'iPad, senza bisogno di aprire l'applicazione.

Metriche mostrate:
- Connessioni attive — numero di connessioni aperte e il massimo configurato sul server.
- QPS o TPS — la portata del server: query al secondo su MySQL e MariaDB, transazioni al secondo su PostgreSQL. Sono due grandezze diverse, quindi l'etichetta dice quale stai guardando.
- Uptime — tempo di attività del server nel formato Nd Nh Nm.
- Thread attivi (nelle versioni media e grande del widget) — numero di thread in esecuzione.
- Query lente/s (media e grande) — tasso di query lente.
- Successo cache (media e grande) — percentuale di letture servite dalla cache del server.
- Badge di stato — verde (attivo e dati recenti), rosso (il server non ha più risposto all'ultimo sondaggio) o ambra (i dati non si possono più presentare come attuali). Quando non ci sono ancora dati non c'è nessun badge: il widget ti chiede di scegliere un server e non afferma altro.
- Barra delle connessioni — barra visiva con colore semantico: ciano (basso), ambra (>65%), rosso (>85%).

Dimensioni disponibili:
- Piccolo — connessioni attive con la loro barra, il nome del server e il badge di stato. Nient'altro: è la dimensione in cui la cifra deve entrare intera.
- Medio — aggiunge la portata, i thread attivi e il tasso di successo della cache — o l'uptime al suo posto, se il motore non pubblica dati di cache.
- Grande — tutto quanto sopra più l'uptime e le query lente al secondo.
- Extra grande — lo stesso, distribuito su due colonne vere. Su iPad sta nella schermata home; sul Mac solo sulla scrivania, perché il Centro Notifiche non accetta questa dimensione.
- Schermata di blocco — rettangolare (iPad) — nome del server, connessioni attive/max e QPS.
- Schermata di blocco — circolare (iPad) — anello con il rapporto di utilizzo delle connessioni e il suo numero assoluto al centro.
- Schermata di blocco — in linea (iPad) — una sola riga con il numero di connessioni attive accanto all'orologio.

Come aggiungere il widget:
- macOS: fai clic destro sulla scrivania e seleziona Modifica widget. Cerca Calíope e trascina la dimensione desiderata sulla scrivania o nel Centro Notifiche.
- iPad: tieni premuta la schermata home finché le icone non vibrano, tocca Modifica in alto a sinistra, poi Aggiungi widget, cerca Calíope e seleziona la dimensione.

Frequenza di aggiornamento:
La cadenza la scegli tu, e da lì dipende tutto il resto. Con il Cruscotto aperto, le metriche si scrivono al ritmo del suo selettore di aggiornamento (da 1 a 30 secondi). Con il Cruscotto chiuso occorre attivare Preferenze › Widget › Aggiornamento in background e scegliere lì l'intervallo: 30 secondi, 1, 5 o 15 minuti.

Quando il badge diventa ambra:
Quando i dati non si rinnovano da più di tre volte quella cadenza, con un minimo di 90 secondi. Con l'intervallo a 5 minuti il widget resta verde per 15; con 15 minuti, per 45. La soglia si deriva dalla tua configurazione invece di essere un numero fisso, perché un widget che diventa ambra mentre l'aggiornamento funziona esattamente come richiesto non sta avvisando di nulla.

E se non ci sono mai stati dati — perché non hai scelto un server — il widget non dice Nessun dato: ti chiede di sceglierne uno.

Parole chiave: widget, scrivania, schermata home, connessioni, qps, uptime, cache, innodb, stato, badge, metriche, home screen, macOS, iPad

Un secondo widget che mostra l'intera fattoria invece di un solo server: quanti sono sorvegliati, quanti richiedono attenzione e qual è il peggiore.

Dove si trova: Widget › Widget, galleria, schermata Home

Il widget Metriche guarda un server. Questo li guarda tutti, e risponde a un'altra domanda: c'è qualcosa che devo andare a vedere?

Dove funziona
- iPhone e iPad. Su macOS c'è solo il widget delle metriche.

Dimensioni disponibili:
- Piccolo — lo stato peggiore della fattoria e quanti server sono sorvegliati.
- Medio — la lista, fino a tre server, i peggiori davanti.
- Grande — la stessa lista, fino a sei. In entrambi, ciò che non entra viene detto con «e altri N», e alle dimensioni di accessibilità entrano meno righe.

Da dove viene il dato
- Dal Monitor di salute, in questa stessa app. Ogni sondaggio scrive il risultato nel contenitore che il widget legge.
- Non viaggia in rete e non dipende da iCloud: quello che vedi sulla schermata Home è stato misurato su questo dispositivo.
- Se la pubblicazione su iCloud è spenta, il widget continua a funzionare. Quell'interruttore decide cosa esce dal dispositivo, non cosa ti mostra il tuo schermo.

Quando non dice nulla
- Apri il Monitor di salute una volta: su questo dispositivo non è ancora stato misurato nulla.
- Non è sorvegliato nessun server: il monitor ha girato e la sua lista è vuota.

Il colore non è mai l'unico segnale: ogni stato ha la sua forma, e ciò che pronuncia VoiceOver dice il conteggio, il peggiore e quanti richiedono attenzione.

Toccandolo si apre il Monitor di salute.

Parole chiave: fattoria, widget, salute, monitor, schermata home, server, gravità

Un tocco o clic sul widget apre Calíope e connette automaticamente al server fissato.

Dove si trova: Widget › Deep link

Toccando o facendo clic sul widget di Calíope, l'applicazione si apre e connette direttamente al server che quel widget ha scelto, portandoti alla Dashboard del workspace corrispondente.

Come funziona:
- Il widget include un deep link del tipo caliope://server/<id> che punta al server scelto nella configurazione di quel widget, non a quello che sta mostrando in quel momento. La differenza conta quando non ci sono ancora metriche: il widget dice «Scegli un server» e apre comunque il suo.
- Se l'app non era aperta, viene avviata prima e poi apre la sessione.
- Se l'app era già aperta ed esiste una sessione attiva con quel server, la porta semplicemente in primo piano.

Quale server apre:
- Quello che hai scelto aggiungendo il widget, o quello che hai impostato dopo: tieni premuto il widget (iPad) o fai clic destro (Mac) → Modifica widget → Server.
- Se quel widget non ne ha nessuno, apre quello dei dati che sta mostrando, cioè l'ultima Dashboard attiva.
- Il profilo fissato di Preferenze › Widget è un'altra cosa: è il server che si aggiorna in secondo piano, non quello che apre il link.

Se non è stato scelto nessun server, il widget ti chiede di sceglierne uno; toccandolo si apre Calíope nella schermata del Gestore connessioni.

Parole chiave: widget, deep link, toccare, clic, aprire, pin, fissare, tap, caliope://, url scheme

Ogni widget può monitorare un server diverso — configuralo quando lo aggiungi o dopo modificandolo.

Dove si trova: Widget › Configurazione

Il widget di Calíope è configurabile: quando lo aggiungi alla scrivania o alla schermata home, il sistema chiede quale server deve mostrare. Così puoi avere più widget simultanei, ognuno che mostra le metriche di un server diverso (produzione, staging, replica, ecc.).

Configurare quando aggiungi il widget
- macOS: fai clic destro sulla scrivania e scegli Modifica widget, poi trascina sulla scrivania la variante che vuoi. Rilasciandola non appare nessun picker: il server si sceglie dopo, con clic destro sul widget già posato → Modifica “Calíope” → Server.
- iPad: tieni premuta la schermata home, tocca Modifica → Aggiungi widget, cerca Calíope e scegli la dimensione. Il server si sceglie dopo, tenendo premuto il widget già posato → Modifica widget → Server.

Cambiare il server di un widget esistente
- macOS: fai clic destro sul widget → Modifica “Calíope” → cambia il parametro Server.
- iPad: tieni premuto il widget → Modifica widget → cambia il parametro Server.

Cosa si sincronizza con l'App Group
- Calíope pubblica un catalogo minimo (id, name, host) dei tuoi profili all'avvio dell'app e ogni volta che salvi modifiche nel Gestore connessioni. Il widget legge quel catalogo per popolare il picker; ci entrano solo i profili il cui motore può pubblicare metriche —quelli di MongoDB non vengono offerti, perché sceglierli lascerebbe il widget vuoto per sempre— e non vede password, chiavi SSH né certificati.
- Le metriche vengono salvate per profilo (caliope_widget_metrics_<id>.json), così ogni widget legge le proprie indipendentemente da quale sessione sia attiva nell'app.

Widget senza server configurato
- Se non scegli nessun server, il widget mostra le metriche dell'ultimo server attivo nell'app. Ma se ne scegli uno e non ci sono ancora metriche sue, non mostra quelle di un altro: dice che non ci sono dati. Un widget fissato a un server non può finire per mostrare nome e cifre di un altro.

Parole chiave: widget, configurazione, scegliere server, AppIntent, multi-server, più widget, picker, modificare widget, profilo

Come Calíope condivide le metriche con l'estensione del Widget su tutte e tre.

Dove si trova: Calíope › Preferenze › Widget

Il widget di Calíope vive in un'estensione separata che non può leggere la memoria dell'app principale. Perché appaiano dati in tempo reale, l'app e l'estensione condividono un contenitore comune attraverso un App Group.

Identificatore
- iPad: group.org.caliope.widget.
- macOS: lo stesso, preceduto dall'identificatore del team (ASH9Q9BLUY.group.org.caliope.widget) — lì il sistema lo esige così.

Lo stesso contenitore alimenta i due widget di iOS: quello delle metriche e quello della salute della fattoria. Su iPhone e iPad è lo stesso binario, quindi è lo stesso App Group.

Cosa si condivide
- Le metriche più recenti di ogni server (connessioni attive, portata —QPS o TPS a seconda del motore—, uptime, thread, query lente/s, tasso di successo della cache).
- Il timestamp dell'ultimo aggiornamento e la cadenza con cui è stato scritto. Il widget usa entrambi per decidere quando mettere il badge in ambra: la soglia è tre volte la cadenza, con un minimo di 90 secondi.
- L'identificatore del profilo fissato e l'URL caliope://server/<id> per il deep link.

Come si aggiorna
- Mentre l'app principale è aperta e connessa, WidgetDataStore scrive nell'App Group ogni volta che arriva un tick di polling.
- Dopo la scrittura, Calíope chiama WidgetCenter.shared.reloadAllTimelines() affinché il widget si aggiorni alla prossima occasione che il sistema gli concede.
- Se l'app si chiude, il widget continua a mostrare gli ultimi dati finché il sistema non gli richiede una nuova timeline. Superata la soglia derivata dalla cadenza, il badge diventa ambra e l'etichetta Nessun dato.

Reinstallare l'app o cambiare Apple ID
- L'App Group è vincolato al Team ID dello sviluppatore. Installando Calíope da Mac App Store o App Store, macOS/iOS crea il contenitore automaticamente. Non devi configurare nulla.
- Se trasferisci l'iPad a un altro Apple ID, il contenitore viene eliminato insieme all'app e il widget resta vuoto finché non riavvii Calíope almeno una volta.

La lingua non viaggia di qui. Si sceglie per applicazione nelle impostazioni di sistema, e quella scelta raggiunge anche l'estensione: il widget legge la sua e parla la stessa dell'app senza che nessuno gliela debba passare.

Parole chiave: app group, widget, group.org.caliope.widget, WidgetDataStore, WidgetCenter, reloadAllTimelines, contenitore, estensione, team id, metriche condivise

Diagnosi passo passo quando il badge è in ambra e non appaiono metriche.

Dove si trova: Widget › Risoluzione dei problemi

Se il widget di Calíope mostra il badge ambra con l'etichetta Nessun dato, significa che i dati non si rinnovano da troppo tempo. «Troppo» non è un numero fisso: è tre volte la cadenza con cui sono stati scritti, con un minimo di 90 secondi.

Prima di tutto, guarda cosa dice il widget:
- Scegli un server — non ci sono mai stati dati. È il punto 1.
- Nessun dato — ce n'erano e sono scaduti. È tutto il resto.
- Offline, in rosso — l'aggiornamento in secondo piano ha sondato e il server non ha risposto. Le cifre che vedi sono le ultime vere, ed è per questo che sono attenuate.

1. C'è un server scelto?
- Ogni widget sceglie il suo: tieni premuto (iPad) o fai clic destro (Mac) sul widget → Modifica widget → Server.
- Se non ne scegli nessuno, il widget ripiega sull'ultimo server attivo nell'app; se non c'è nemmeno quello, non ha nulla da mostrare.

2. Chi sta scrivendo le metriche?
Ci sono solo due scrittori, e se non ne sta girando nessuno il widget resta fermo per definizione:
- Il Cruscotto aperto su quel server. Chiudendo la scheda le cifre restano: il widget continua a mostrare l'ultima misura e la marca come vecchia quando è il momento. Prima venivano cancellate alla chiusura, e questo lasciava tutti i widget senza niente proprio all'uscita dall'app.
- L'aggiornamento in background, in Preferenze › Widget. Va attivato e va scelto lì il profilo fissato; è ciò che tiene vivo il widget con l'app in secondo piano.

3. E se l'intervallo è lungo?
Con 15 minuti il widget resta verde per 45 e poi passa in ambra anche se funziona tutto: è semplicemente passato il tempo fra due scritture. Se preferisci che l'ambra arrivi prima, abbassa l'intervallo in Preferenze › Widget.

4. Hai riavviato il dispositivo?
Dopo un riavvio il widget resta senza stato finché l'app principale non viene eseguita almeno una volta.

5. Lo sta bloccando il sistema?
- Su iPad, Impostazioni › Generali › Aggiornamento app in background deve essere attivo per Calíope, altrimenti l'aggiornamento programmato non arriva mai a girare.
- Su Mac non c'è un equivalente, ma non c'è nemmeno nessuno che scriva con Calíope chiusa: il widget conserva l'ultima cosa ricevuta e la segna come vecchia quando è il momento.

6. Se niente di tutto questo corrisponde
Togli il widget dalla scrivania o dalla schermata home e riaggiungilo: questo obbliga il sistema a ricostruire la timeline da zero.

Parole chiave: sin datos, no data, widget, badge ambra, troubleshoot, risolvere, fissare profilo, aggiornamento in background, reimposta cache, diagnostica