Convertire un timestamp Unix

Un timestamp Unix conta il tempo trascorso dal primo gennaio 1970 a mezzanotte UTC. In secondi, oggi sono dieci cifre; in millisecondi, tredici. È l’unica differenza fra i due, e produce l’errore più comune di tutta questa faccenda: leggere dei millisecondi come secondi sposta la data nell’anno 56.000 circa, leggere dei secondi come millisecondi la riporta al 1970.

Il riconoscimento automatico usa la grandezza del numero e sbaglia solo in un caso, un timestamp in millisecondi di una data vicinissima all’epoca — cioè quasi sempre uno zero mascherato o un errore a monte. Per questo l’unità usata viene sempre dichiarata e resta forzabile: una risposta che non dice cosa ha assunto è peggio di una domanda.

Il numero è privo di fuso orario: designa un istante, non un orario locale. Renderlo leggibile richiede la scelta di un fuso, e quella scelta cambia la data e non solo l’ora — un timestamp di mezzanotte e mezza UTC in Italia è già l’una e mezza del giorno stesso, e a fine dicembre può significare due giorni diversi in due report diversi.

Qui escono entrambi: l’UTC, che è quello che c’è scritto nel dato, e la tua ora locale, che è quella che stai cercando. La tua è `Europe/Rome` se il sistema è configurato così: UTC+1 d’inverno, UTC+2 con l’ora legale. Confrontare un valore di log con l’orologio a muro senza esplicitare quale dei due si sta guardando è il modo consueto di perdere un’ora su un problema che non esiste.

In Italia le lancette si spostano l’ultima domenica di marzo e l’ultima di ottobre. In marzo le due del mattino diventano le tre e quell’ora non esiste: nessun timestamp la produce, e una query che filtri su quell’intervallo non restituisce niente. In ottobre le tre tornano le due e quell’ora capita due volte, con due timestamp diversi che si scrivono come lo stesso orario locale.

Il timestamp Unix di tutto questo non si accorge, perché conta secondi in UTC e basta. La conseguenza è che un report giornaliero calcolato in ora locale ha un giorno da 23 ore e uno da 25 all’anno, e che chiunque abbia confrontato due sistemi la notte dell’ultima domenica di ottobre ha visto eventi apparentemente fuori ordine. Conservare in UTC e convertire solo per mostrare è la regola che toglie di mezzo entrambi i casi.

Un contatore di secondi in un intero a 32 bit con segno finisce il 19 gennaio 2038 alle 03:14:07 UTC. Il valore successivo va in overflow e diventa negativo, cioè il 13 dicembre 1901: è lo stesso meccanismo del problema dell’anno 2000, con una scadenza diversa e meno pubblicità.

I sistemi moderni usano 64 bit e non hanno il problema per qualche miliardo di anni. Restano i dispositivi incorporati, i formati binari con campi di dimensione fissa e le colonne di database dichiarate come intero a 32 bit anni fa: se lavori con date future — scadenze di contratti, mutui trentennali, garanzie — il limite lo incontri oggi e non fra tredici anni.

Il formato `2024-03-31T01:00:00Z` mette le componenti dalla più grande alla più piccola, e da lì viene la sua proprietà utile: l’ordinamento alfabetico coincide con l’ordinamento cronologico. Un elenco di nomi di file datati così si ordina da solo, e nessun formato con il giorno davanti lo fa.

La `Z` finale significa UTC, ed è la parte che si perde più spesso in un copia-incolla. Una stringa ISO senza fuso viene interpretata in modo diverso a seconda di dove finisce, il che riporta esattamente all’ambiguità che il formato dovrebbe risolvere. In Italia il formato con il giorno davanti resta quello giusto per un documento destinato a persone; per un dato che verrà elaborato, ISO 8601 con la `Z` è l’unica forma che non ha bisogno di spiegazioni.

Il tempo Unix è definito come se ogni giorno avesse esattamente 86.400 secondi, e i secondi intercalari — quelli che ogni tanto vengono aggiunti per riallineare gli orologi alla rotazione terrestre — semplicemente non compaiono nel conteggio. Nel momento in cui ne viene inserito uno, lo stesso valore vale per due secondi reali consecutivi.

Nella pratica quotidiana non cambia niente, e la conversione qui è quella corretta rispetto alla definizione. Diventa visibile solo dove la differenza fra due istanti dev’essere esatta al secondo su intervalli lunghi — misure scientifiche, sincronizzazione di sistemi finanziari — e in quei contesti si usa una scala diversa, non un timestamp Unix.

La settimana ISO inizia di lunedì, e la settimana 1 è quella che contiene il primo giovedì dell’anno. Ne segue che i primi giorni di gennaio possono appartenere all’ultima settimana dell’anno precedente: il primo gennaio 2023, che era una domenica, sta nella settimana 52 del 2022.

È il motivo per cui un numero di settimana va sempre scritto con il suo anno ISO e non con l’anno della data. Un report settimanale che li mescoli produce una settimana vuota a gennaio e una doppia a dicembre, ed è un difetto che si nota solo a fine anno, quando è già in produzione da undici mesi.

La distanza dal momento attuale — «quattro ore fa», «tre mesi fa» — è la risposta che serve davvero quando si sta guardando un log. Non interessa sapere che erano le 14:37 di martedì; interessa sapere se quell’evento è di prima o di dopo il deploy.

Va usata sapendo cos’è: un valore calcolato sull’orologio del tuo dispositivo, quindi tanto affidabile quanto quello. Su una macchina con l’ora sbagliata di dieci minuti anche questa risposta lo è, mentre l’UTC e l’ISO restano esatti perché derivano solo dal numero. Se le due cose non tornano, il sospettato è l’orologio locale.

Un timestamp da solo sembra innocuo, e da solo lo è. Nel contesto in cui lo hai copiato non lo è quasi mai: viene da una riga di log accanto a un identificatore di sessione, da una colonna `last_login` o dal payload di un ordine, e in quei casi indica quando una persona precisa ha fatto una cosa precisa.

La conversione qui avviene nella pagina, quindi quel numero non arriva a noi e non compare in nessun log altrui. Vale anche per il fuso: la tua ora locale la calcola il browser con la configurazione che ha già, senza che nessuno debba chiedere dove ti trovi.