Asset
Definire e verificare il contratto di una misura
Una pratica per rendere attendibile un segnale: esplicitare cosa conta, dove inizia e finisce l'osservazione, come si trattano retry e dati mancanti e quali prove dimostrano che la misura osserva davvero il fenomeno.
IL CONTRATTO VIENE PRIMA DEL GRAFICO. Una misura deve rispondere a una domanda precisa. Nel caso didattico Ordini/Pagamenti, «tempo di conferma» potrebbe indicare il tempo di risposta di un endpoint, la durata dell'elaborazione interna oppure l'attesa percepita dall'utente. Non sono intercambiabili. Questa pratica propone un contratto della misura: una specifica breve, verificabile e mantenuta da un responsabile. Non è un nuovo standard né il risultato di una prova reale. SCEGLI IL LUOGO DELLA VERIFICA. Una dipendenza tra package si può controllare sul codice analizzato; una capacità di ripristino richiede anche una prova periodica; il comportamento delle richieste reali richiede osservazione durante l'esecuzione. Queste evidenze hanno perimetri differenti. Per il runtime, OpenTelemetry distingue segnali quali metriche, log e trace [1]. Usa aggregati per quantificare, eventi per chiarire passaggi significativi e trace per seguire il lavoro attraverso i confini, senza presumere che uno di questi sostituisca gli altri. DEFINISCI UN ESEMPIO CIRCOSCRITTO. La misura proposta osserva l'elaborazione interna dalla registrazione autorevole di una richiesta accettata alla persistenza dell'ordine con conferma resa disponibile. Non include il percorso precedente all'accettazione né dimostra che il cliente abbia visto la conferma. L'unità è l'operazione di dominio, non ciascun tentativo HTTP. Specifica quali richieste sono eleggibili, il significato dell'accettazione, gli esiti terminali, l'unità di tempo, le fonti e le esclusioni. Per osservare l'esperienza completa serve una misura aggiuntiva dal punto di vista appropriato. NON PERDERE GLI INCOMPLETI. Un istogramma delle sole operazioni concluse racconta la durata dei completamenti osservati; non racconta le operazioni ancora aperte. Mantieni quindi visibili richieste accettate, completamenti, fallimenti noti e anzianità delle richieste in attesa. Definisci come riconoscere tentativi ripetuti della stessa operazione, eventi duplicati ed eventi arrivati fuori ordine. Un completamento duplicato non deve diventare due ordini riusciti nel conteggio. L'identità necessaria alla correlazione resta nel perimetro autorizzato; non richiede un'etichetta metrica distinta per ogni ordine. TEMPO, COPERTURA E AGGREGAZIONE. Dichiara se il tempo rappresenta l'evento o la sua ricezione, quale ritardo di acquisizione ammetti e come correggi eventi tardivi. Non sottrarre timestamp di sistemi diversi senza considerare la sincronizzazione degli orologi. Per le durate conserva una distribuzione adeguata: la documentazione Prometheus distingue istogrammi aggregabili e quantili precalcolati, che non si possono mediare per ottenere il percentile globale [2]. Specifica popolazione, finestra e granularità prima di confrontare valori. Un p95 dei completamenti non va presentato come prova sul totale delle richieste. I trace campionati non sono automaticamente un censimento: politiche che trattengono in modo preferenziale errori o lentezze cambiano la popolazione osservata [3]. Per il rapporto di esiti del nostro esempio scegli un conteggio completo delle operazioni eleggibili, oppure dichiara e valida esplicitamente il metodo di stima. DISTINGUI ZERO, ASSENZA E RITARDO. Zero violazioni con copertura valida è diverso da una sorgente che non trasmette più. Verifica aggiornamento, completezza attesa e funzionamento della raccolta. Se una richiesta è autorevolmente registrata e resta aperta oltre un limite definito, hai una proprietà valutabile; se hai perso la fonte che dovrebbe dirti cosa è accaduto, hai un problema di osservazione. Non convertire la seconda situazione in successo. Pubblica la qualità del dato accanto alla misura e stabilisci quando l'esito è non valutabile. VERIFICA CON CAMPIONI NOTI. In un ambiente di test isolato prepara un completamento noto, un errore, un'operazione ancora aperta, un retry della stessa operazione, un evento duplicato, un evento tardivo e un'interruzione della raccolta. Per ogni caso scrivi prima il conteggio e la classificazione attesi; poi confrontali con l'output. Controlla anche il perimetro escluso, così che non cambi silenziosamente. Le prove sono qui prescritte, non eseguite: un grafico plausibile non costituisce evidenza della loro riuscita. DATI E COSTO. Raccogli soltanto il dettaglio necessario, definendo accessi, conservazione e rimozione dei dati sensibili. OpenTelemetry documenta misure quali filtraggio e redazione dei dati nella pipeline [4]; evitare di raccogliere il dato non necessario resta preferibile a diffonderlo e correggerlo dopo. Nessun payload di pagamento, credenziale o dato personale è necessario per l'esempio. OUTPUT MINIMO. Conserva domanda, unità osservata, inizio e fine, popolazione ed esclusioni, fonti, semantica temporale, aggregazione, deduplicazione, copertura e freschezza, trattamento dei mancanti, responsabile, limiti e casi di prova. La scelta delle soglie di servizio viene dopo questa definizione. COLLEGAMENTI CANONICI. KA-006 introduce l'osservabilità; KA-154 seleziona i segnali; KA-153 mostra come verificare un controllo statico. Questa pratica affronta la correttezza dell'osservazione, senza ricreare quei contenuti. FONTI PRIMARIE. [1] OpenTelemetry, Signals: https://opentelemetry.io/docs/concepts/signals/ . [2] Prometheus, Histograms and summaries: https://prometheus.io/docs/practices/histograms/ . [3] OpenTelemetry, Sampling: https://opentelemetry.io/docs/concepts/sampling/ . [4] OpenTelemetry, Handling sensitive data: https://opentelemetry.io/docs/security/handling-sensitive-data/ . Il contratto e i casi Ordini/Pagamenti sono una proposta didattica originale, non un'implementazione o una configurazione universale.