La DevGuide di ExeWatch

Una clausola uses e una riga di inizializzazione. Tutto il resto della guida non fa che rifinire quelle due cose.

1. Aggiungi l’SDK alla tua clausola uses. In un’app VCL, cioè la stragrande maggioranza delle app Delphi, sono due unit: la seconda è quella che cattura le eccezioni della GUI.

Delle due unit di hook ne metti una sola, quella del framework che stai usando. Se l’app non ha una GUI, per esempio un servizio Windows o un’utility a riga di comando, non aggiungere né la .VCL né la .FMX: non c’è nessun message loop da agganciare e ExeWatchSDKv1 da solo ti basta.

2. Inizializza una volta sola, presto (nel .dpr prima di Application.Run, oppure nell’evento OnCreate del form principale):

Due argomenti: l’API key che copi dalla console e l’id del cliente a cui appartiene questa installazione. Fatto, l’app è monitorata.

Cosa ti sei portato a casa con quelle due righe. Da questo momento i crash vengono registrati con il loro stack trace senza che tu scriva altro, e le due unit si dividono il lavoro. ExeWatchSDKv1 aggancia System.ExceptProc, dove finiscono le eccezioni non gestite del codice normale. ExeWatchSDKv1.VCL (oppure .FMX) prende invece quelle che scappano dentro un evento, un OnClick o un OnCreate: le intercetta il message loop del framework e le consegna ad Application.OnException, e lì il giro finisce, a System.ExceptProc non arrivano mai. In un’app desktop sono la categoria di crash più frequente, ed è per questo che la seconda unit conta.

Parte anche un log automatico Application started, la conferma che l’integrazione è viva, e le informazioni sul device (sistema operativo, macchina, versione del binario) vengono inviate e collegate al cliente. Niente di tutto questo viaggia sul thread della tua applicazione: gli eventi finiscono in una coda su disco e un thread in background li spedisce, quindi una rete lenta o un server irraggiungibile non rallentano né bloccano l’app.

L’unit di hook non ti porta via il gestore che avevi: se avevi già un tuo Application.OnException, l’hook logga e poi lo richiama; se non ce l’avevi, chiama Application.ShowException. La finestra di errore che il tuo utente vedeva prima continua a comparire identica. E se un domani te ne dimentichi in un altro progetto non resti al buio: l’SDK si accorge di girare in un’app con GUI senza hook installato e scrive lui stesso un Warning con tag exewatch, che ti ritrovi in dashboard.

3. Logga ciò che ti interessa. Da qui in poi logghi, conti e cronometri ogni volta che hai qualcosa che merita di essere registrato:

Apri la dashboard e trovi gli eventi. Da qui in avanti la guida serve a farti venire in mente tutto quello che merita di finire lì dentro, perché la lista è più lunga di quella che ti verrebbe in mente adesso.

La Quickstart era in Delphi, l’SDK di punta. Il cosa e il perché nel resto della guida valgono identici per ogni SDK: cambia solo il modo di integrarlo e inizializzarlo. Ecco il setup per ciascuno. In tutti l’ultimo argomento è l’etichetta di release (AppVersion), e l’API key ha il prefisso della piattaforma (ew_win_, ew_lin_, ew_web_ e così via).

Delphi (nativo). Come nella Quickstart: ExeWatchSDKv1 nella clausola uses, più ExeWatchSDKv1.VCL (oppure .FMX) se l’app ha una GUI, poi InitializeExeWatch(ApiKey, CustomerId, '4.2.0'). La unit VCL/FMX cattura per te le eccezioni GUI non gestite.

.NET. Referenzia il pacchetto ExeWatch (aggiungi ExeWatch.WinForms per un’app WinForms), poi inizializza una volta all’avvio:

Un’app console o un servizio salta la riga Install: il client aggancia AppDomain.UnhandledException da solo. WinForms richiede invece la chiamata Install esplicita prima di Application.Run.

Python. Installa l’SDK, inizializza il singleton e poi usa l’oggetto ew a livello di modulo:

Python non ha una GUI da agganciare, quindi cattura i fallimenti dove li gestisci con ew.error_with_exception(exc, "tag"), oppure punta sys.excepthook sull’SDK per avere una rete globale.

JavaScript (browser). Dichiari la configurazione in window.ewConfig e poi carichi lo script da exewatch.com. La chiave è una chiave ew_web_, e l’SDK cattura automaticamente window.onerror:

L’ordine conta: l’SDK si inizializza da solo al DOMContentLoaded leggendo window.ewConfig, quindi la configurazione deve essere già sulla pagina quando lo script viene caricato. Lo script lo servi da exewatch.com, non da una copia tua, così le correzioni arrivano ai tuoi utenti senza che tu debba ridistribuire niente.

Questo SDK è solo per browser, non esiste una build per Node. Gli errori non catturati vengono raccolti per te, insieme ai fallimenti di fetch e XHR e alle console.error. In una pagina che carica script di terze parti, ignoreUrls nella stessa ewConfig scarta gli errori che arrivano da domini che non controlli, tipo advertising e analytics: è rumore che non ti dice niente sulla tua applicazione.

DLL (C, C++, VB, .NET legacy, qualsiasi cosa con una ABI C). Carica ExeWatchSDKv1DLL.dll e chiama gli export flat. Le stringhe sono wide (PWideChar), ogni funzione è stdcall e i risultati tornano come codici di ritorno:

Poiché una ABI C flat non può camminare lo stack dell’host né eseguire una callback, due compiti ricadono sull’host: passare una stringa di stack già risolta a ew_ErrorWithStackTrace, e pilotare i gauge periodici da un timer tuo (non c’è callback per i gauge periodici). Un host Delphi che preferisce la DLL alle unit native può usare la import unit ExeWatchSDKv1Imports e chiamare EWInitialize(…​) al posto di InitializeExeWatch.

Lo stesso, per intero, con MSVC. Nessuna import library e nessun runtime Embarcadero: definisci EW_DYNAMIC_LOAD prima dell’header e ogni ew_* diventa un puntatore a funzione, che ExeWatchSDKv1.dynload.c risolve a runtime con LoadLibrary e GetProcAddress. Questo è un programma completo, non un frammento:

Si compila in un comando solo, da un prompt "x64 Native Tools Command Prompt for VS 2022", passando la cartella che contiene header e loader:

L’unica riga che qui non è cerimonia è ew_WaitForSending. Un’utility a riga di comando può terminare prima che il thread shipper abbia svuotato la coda, e quella chiamata scrive il buffer su disco e aspetta che la coda si svuoti, restituendo quanti eventi sono ancora in attesa. Non è un problema di perdita di dati, perché la coda è su disco e riparte alla prossima esecuzione, ma senza l’attesa i tuoi eventi compaiono in dashboard con un giro di ritardo. Il sample compilabile con tutto il resto, identità utente, tag globali, breadcrumb, timing annidate e gauge, è in ExeWatchSamples/MSVCWithDLLSDK.

La stessa DLL da una console Delphi. Anche un host Delphi può usare la DLL invece delle unit native, e in due casi è la scelta giusta: quando sei su un Delphi più vecchio di XE8, che è il minimo del SDK nativo, e quando hai più applicazioni che devi aggiornare distribuendo un binario solo. La import unit ExeWatchSDKv1Imports arriva fino a Delphi 5. Anche questo è un programma intero:

I wrapper con il prefisso EW accettano string e la conversione a PWideChar la fanno loro, quindi nel tuo codice non compare un cast. Trattandosi di una console, valgono le stesse due righe di prima: ew_WaitForSending prima di uscire, e ew_Shutdown per chiudere pulito.

Una cosa da sapere prima di distribuire. Di default la unit lega la DLL staticamente, quindi ExeWatchSDKv1DLL_x64.dll deve essere accanto all’eseguibile al momento dell’avvio: se manca, il processo non parte affatto, lo blocca Windows con un errore di DLL mancante prima ancora della tua prima riga di codice. Se preferisci che l’applicazione parta comunque e rinunci soltanto alla telemetria, definisci EW_DYNAMIC_LOAD nelle opzioni di progetto: la unit passa a LoadLibrary, e chiami EWLoadDLL all’avvio verificandone il risultato, come fa l’esempio MSVC qui sopra.

E con Free Pascal. La DLL non ha niente di specifico di Delphi: è una ABI C flat, stdcall, stringhe wide. Su Windows la stessa ExeWatchSDKv1Imports compila con FPC, che la unit riconosce e mette in {$MODE DELPHI} da sé. Dove string non è Unicode l’alias interno diventa WideString e i wrapper EW* convertono per te, quindi il codice che scrivi resta quello dell’esempio qui sopra.

La singola chiamata a InitializeExeWatch della Quickstart è tutto ciò di cui la maggior parte delle app avrà mai bisogno. Quel terzo argomento è AppVersion, la tua etichetta di release ('4.2.0', '2026-Q1', 'v2-beta'); la versione del binario è invece un campo separato, rilevato in automatico dall’eseguibile, quindi da quell’unica riga ottieni entrambe. Ecco a cosa ricorrere quando quella riga non basta.

È un flusso deliberato e supportato, non un espediente. Finché l’id cliente è vuoto l’SDK trattiene il record di device-info, perché gli serve l’id per collegare il device al cliente giusto, e lo invia nell’istante in cui chiami SetCustomerId. Se in seguito l’id cambia (un cliente diverso sulla stessa macchina) l’SDK reinvia la device-info sotto il nuovo cliente, così il device compare correttamente per entrambi. La regola è semplice: prima inizializza, poi identifica appena puoi.

Cliente e utente sono due identità diverse, impostate con due chiamate diverse. SetCustomerId imposta il cliente: l’account o tenant a cui appartiene questa installazione, ossia il criterio con cui la dashboard raggruppa device e alert. Chi sta effettivamente usando l’app è un’altra cosa, l'utente, e quello lo imposti con SetUser:

Id, email e nome viaggiano poi con ogni evento come user_id, così un crash mostra non solo quale cliente lo ha incontrato ma anche quale persona. Usa SetCustomerId per l’account e SetUser per la persona: sono indipendenti, e puoi impostare l’uno, l’altro, entrambi o nessuno dei due.

Quando la chiamata a tre argomenti non basta, costruisci un TExeWatchConfig e passa quello. Ogni campo ha un default sensato, quindi imposta solo ciò che ti serve:

Le impostazioni che vale la pena conoscere:

Gli altri SDK adottano gli stessi concetti sotto nomi di campo molto simili; il riferimento ha la firma esatta per ognuno.

Una dashboard vuota mette in soggezione, e la prima domanda è sempre la stessa: da dove comincio? La risposta breve è che se una cosa ti interessa, va registrata. Ti interessa sapere se quella funzione fallisce? Logga. Quante volte viene usata? Conta. Se è lenta e quanto? Cronometra. L’errore che si paga caro non è aver mandato qualche evento di troppo, è ritrovarsi davanti a un problema in produzione e scoprire che proprio quel pezzo di codice non racconta niente.

Quel momento arriva sempre, e arriva di martedì pomeriggio con un cliente al telefono. Hai lo stack trace del crash ma non sai cosa stesse facendo l’utente un attimo prima, perché quel passaggio non lo avevi loggato. Sai che la sincronizzazione ci mette una vita ma non quale fase la mangia, perché avevi cronometrato solo il totale. In quei venti minuti non rimpiangi mai le righe che hai mandato in più. Rimpiangi le tre che non hai scritto.

Quindi parti generoso. Se qualcosa può fallire, se può diventare lenta, se ti serve sapere quanto viene usata, se spiega perché l’app si è comportata in un certo modo, mandala. Aggiungerne è facile finché stai scrivendo il codice; aggiungerne dopo, quando la build incriminata è già installata da trecento clienti, vuol dire un rilascio e settimane di attesa. E il rumore, se un domani ce ne fosse troppo, lo togli quando vuoi: il livello minimo e il campionamento di ogni applicazione si cambiano dalla console, senza ricompilare niente.

Non vale la pena mandare solo quello che non dice niente nemmeno a te: un Debug('sono qui'), un Info('step 1'), un messaggio senza contesto che capisci soltanto mentre lo scrivi. Il resto della guida serve a farti venire in mente cosa invece merita di esserci, e a scegliere lo strumento adatto a ciascuna cosa, visto che un crash, un conteggio d’uso e una durata si registrano in tre modi diversi.

Prima delle ricette, la mappa. ExeWatch ti mette a disposizione cinque strumenti, e ognuno esiste per rispondere a una domanda diversa. Quasi ogni decisione del tipo "cosa traccio qui?" diventa ovvia una volta che sai quale domanda ti stai ponendo.

Due cose sfuggono facilmente, ed entrambe ti risparmiano lavoro vero più avanti.

I tag sono il sesto strumento silenzioso. Ogni chiamata di log, counter, gauge e timing accetta un tag, ed esiste un SetTag valido per l’intero processo per il contesto che viaggia con tutto. I tag sono il modo in cui affetti la dashboard in "payment" contro "sync" contro "ui" senza inventare una metrica separata per ogni funzionalità. Azzeccali e ogni grafico è filtrabile esattamente come ragioni tu; sbagliali e la dashboard diventa rumore. La sezione sull’igiene dei tag è la prossima, ed è breve.

La device-info è automatica e gratis. Versione app, versione binario, OS e hardware viaggiano con ogni batch senza una singola chiamata da parte tua. Non riloggarli. L’unico campo che imposti a mano è AppVersion, l’etichetta di release, ed è proprio ciò che più avanti rende possibile il confronto fra versioni.

Un tag serve a filtrare, non a trasportare dati. Tienili corti, pochi e stabili nel tempo, e la dashboard resta leggibile anche dopo qualche anno di aggiunte.

In pratica:

Imposta una volta sola, all’avvio, il contesto che non cambia mai, così non lo ripeti a ogni chiamata:

Da quel momento ogni evento porta con sé quel contesto, e puoi filtrare l’intera dashboard fino a, per esempio, la sola edizione Pro sul canale stable senza toccare un’altra riga di codice.

I tag che imposti con SetTag (o con GlobalTags all’init) diventano un filtro Global Tags nella console, così puoi affettare ogni vista per ambiente, edizione, feature flag e qualunque altra cosa tu abbia taggato.

Le ricette che seguono usano Delphi. I concetti sono identici fra gli SDK; cambia solo la grafia. Questa tabella è la mappa, così un lettore .NET o Python può tradurre a colpo d’occhio qualunque snippet. Il riferimento nella console ha le firme complete.

Due fatti specifici degli SDK da portarsi dietro in ogni ricetta: la DLL non ha callback per i gauge periodici, quindi la piloti da un timer tuo, e JavaScript è solo per browser. Tutto il resto è una semplice riscrittura uno a uno.

Ogni ricetta parte da una situazione in cui ti sei già trovato, o ti troverai, e risale fino all’unica cosa che vale la pena instrumentare. Uno snippet Delphi canonico per ciascuna; usa la tabella qui sopra per tradurlo al tuo SDK. Dove il comportamento cambia davvero, è segnalato.

Questi tre strumenti vengono confusi di continuo, e confonderli non lancia un errore, registra in silenzio dati che non significano niente, il che è peggio. La distinzione è semplice, una volta detta ad alta voce:

Nel dubbio, prova a sommare due letture. Se la somma ha senso, 12 export più 8 export fanno 20 export, è un counter. Se non ha senso, una coda di 12 più una coda di 8 non fa una coda di 20, è un gauge. Se quello che ti interessa è il tempo trascorso, è un timing.

Un alert è ciò che ti permette di smettere di guardare la dashboard. Invece di controllare ogni tanto sperando di cogliere un problema, descrivi il problema una volta ed ExeWatch ti manda una email quando accade. Oggi ne esistono due tipi, e conviene sapere con precisione su cosa scatta ciascuno, perché i limiti onesti dell’alerting plasmano il modo in cui usi tutto quel che viene sopra.

Gli alert sul volume di log scattano quando il conteggio degli eventi di log pari o superiori a un livello supera una soglia dentro una finestra. Imposti threshold (un conteggio), window_minutes, min_level (default error), un filtro tags opzionale, un customer_external_id opzionale e cooldown_minutes (default 60) così un solo incidente non ti notifica cinquanta volte. Uno tipico recita: "più di 20 eventi fatal in 15 minuti per il cliente Acme".

Lo stesso alert come form nella console: una soglia su una finestra temporale a un livello minimo, con un cooldown, all’occorrenza ristretto per tag e per cliente. Impostare "Filter by Customer" su Acme è il modo per farti avvisare degli errori di Acme senza sentir parlare di nessun altro.

Tasso d’errore nel tempo. Un picco come quelli qui è esattamente ciò che un alert sul volume di log sorveglia, così ti raggiunge via email nell’istante in cui parte invece che quando ti capita di aprire questo grafico.

Gli alert di timing scattano quando le operazioni che corrispondono a un pattern di id di timing girano più lente di una soglia di durata, abbastanza spesso da superare una soglia di conteggio dentro una finestra. I campi sono un timing_id_pattern, una soglia di durata in millisecondi, una soglia di occorrenze threshold (default 5), window_minutes, un customer_external_id opzionale e cooldown_minutes (default 240). È così che ti fai avvisare che "report.render sta girando lento sul campo" senza doverlo sorvegliare.

Il modo per tenere gli alert utili invece che ignorati: mantieni onesti i tuoi livelli di log (vedi anti-pattern, altrimenti la tua soglia error scatta su cose che errori non sono), dai a ogni alert un ambito per tag o per cliente così ha un titolare chiaro, e imposta un cooldown abbastanza lungo perché un vero incidente arrivi come una sola email.

Rilasci una versione e vuoi sapere se è diventata più lenta o più rumorosa della precedente. Oggi quel confronto passa dall’export CSV, e vale la pena esplicitare il flusso perché risponde a una domanda che i clienti pongono di continuo.

Lo stesso export c’è nelle pagine Log e Metriche, così puoi confrontare il volume d’errori o i livelli di metrica fra le versioni allo stesso modo. Un filtro di timing per-versione dentro l’interfaccia è nel backlog; quando arriverà, questo diventerà un paio di clic invece di una pivot. Fino ad allora, la strada del CSV è il modo supportato per il confronto versione su versione, e funziona abbastanza bene che parecchi team si fermano qui.

Poiché ogni evento porta il suo AppVersion, la console sa già come sono distribuite le tue release sul campo. Quella stessa etichetta di versione è ciò su cui crei la pivot del timing esportato.

Le chiamate isolate sono facili da approvare con un cenno e difficili da collocare. Ecco quindi l’instrumentazione calata in codice ordinario: un metodo di sync su un data module, il tipo che ogni app Delphi gestionale ha. Prima la versione nuda, che fa il suo lavoro senza telemetria:

Ora lo stesso metodo instrumentato, ogni aggiunta fa esattamente un lavoro:

Cosa è andato dove, e perché:

Nota la forma: l’instrumentazione incornicia il codice reale, non lo rimpiazza. Cancella ogni riga EW. e il metodo funziona ancora esattamente come prima. La instrumentazione si limita a osservare.

Nessuno di questi è "hai loggato troppo". Sono i casi in cui quello che mandi ti fuorvia invece di aiutarti, e la correzione sta accanto a ciascuno.

Ripetere la stessa riga dentro un ciclo. Una chiamata Debug in un ciclo caldo, o un IncrementCounter a ogni iterazione. Il punto non è la quantità: è che cinquecento righe identiche rispondono tutte alla stessa domanda a cui aveva già risposto la prima, e nel frattempo consumano la quota che serviva agli eventi veri. Registra l’operazione, non le sue iterazioni: una riga quando parte, una quando finisce o fallisce, e un solo incremento di counter per operazione logica. Se il dettaglio per-iterazione ti serve davvero durante una diagnosi, tienilo a livello Debug e alza il livello minimo dell’applicazione dalla console quando hai finito.

Dati personali nei log. Email, nomi, token o contenuti di file in un messaggio o in un tag. I log vengono conservati ed esportati in CSV, e i tag sono dimensioni a bassa cardinalità, non payload, quindi questo è insieme un problema di privacy e un pasticcio. Logga id e categorie; usa il campo id cliente per l’identità.

Livelli che mentono. Tutto loggato a Error, oppure fallimenti veri loggati a Info. Gli alert usano di default min_level = error, quindi se i tuoi livelli sono sbagliati lo sono anche i tuoi alert, e o vieni notificato per niente o non vieni mai notificato. La scala che li tiene onesti: Fatal significa che l’app non può continuare, Error che un’operazione è fallita, Warning degradato ma funzionante, Info un cambio di stato notevole, Debug dettaglio per soli sviluppatori.

Gauge e counter, scambiati. Un counter per "profondità di coda attuale" somma livelli in un totale privo di senso; un gauge per "numero di export" butta via il totale. Applica il test dell’addizione della tabella qui sopra prima di scegliere.

Tag che esplodono. Un id, un timestamp, o un qualsiasi valore per-richiesta in un tag. I tag sono dimensioni con un piccolo insieme fisso di valori; valori illimitati si moltiplicano in migliaia di dimensioni usa-e-getta e rendono la dashboard inutilizzabile. Tieni piccolo il vocabolario.

Riloggare ciò che ottieni già gratis. Loggare a mano OS, versione o hardware che già viaggiano nello snapshot del device a ogni batch. Non farlo. L’unico campo che imposti a mano è AppVersion, l’etichetta di release.

Le app desktop girano su portatili che si infilano nei tunnel, su macchine dietro VPN capricciose, su un PC che qualcuno stacca dalla rete alla chiusura. Quindi la domanda è legittima: che ne è della tua telemetria quando l’SDK non riesce a raggiungere il server?

Non si perde niente. L’SDK non spedisce gli eventi direttamente dal punto in cui li chiami. Li accumula in un buffer, li scrive su disco, e a spedirli ci pensa un thread shipper in background. Quando la rete è giù l’invio semplicemente fallisce, i file restano su disco, e lo shipper riprova a intervalli. Nell’istante in cui la connettività torna, i file in coda vengono spediti in ordine. Un crash loggato in aereo compare sulla tua dashboard la prima volta che il portatile torna online.

A governarlo sono quattro impostazioni di TExeWatchConfig:

L’arretrato puoi tenerlo d’occhio tu stesso: GetPendingCount restituisce quanti eventi sono ancora in attesa di spedizione.

Un fatto tecnico da conoscere, e arriva alla fine della guida di proposito: la quota mensile è un conteggio vivo delle righe che invii nel mese. Contano insieme i log e gli aggiornamenti delle metriche, cioè counter, gauge e timing, non i soli log. I messaggi interni dell’SDK, quelli con tag ew.system, non rientrano nel conteggio.

Non è un invito a instrumentare di meno. L’ordine giusto è quello che hai seguito fin qui: prima decidi cosa vuoi vedere, poi, se e quando il volume diventa un tema, lo governi. Gli strumenti per governarlo esistono e nessuno ti chiede di rinunciare a un dato che ti interessa.

Se sei stabilmente vicino al tetto con un’instrumentazione che ti serve tutta, non c’è niente da tagliare: stai seguendo più applicazioni o più clienti di quando hai scelto il piano, e a quel punto conviene passare al livello successivo.

Alcune cose che la gente chiede sono pianificate ma non ancora rilasciate. Sono elencate qui, onestamente, così sai dove sono oggi i confini e non vai a cercare una funzionalità che ancora non c’è.

Per tutto ciò che oggi esiste, il riferimento dell’SDK nella console ha le firme esatte, le chiavi di configurazione e i passi d’installazione. Questa guida è il cosa e il perché; quello è il come.