Timestamps Unix explicados: segundos, milissegundos e fusos horários
O que é um timestamp Unix, como distinguir segundos de milissegundos, por que o fuso horário não o altera, o problema de 2038 e como converter epoch em código.
Atualizado
Um timestamp Unix é uma contagem de segundos desde a época Unix, 00:00:00 UTC de 1º de janeiro de 1970. 1696118400 significa 1.696.118.400 segundos depois desse momento, o que é meia-noite UTC de 1º de outubro de 2023. É o mesmo número em todos os países, porque o fuso horário só entra em cena quando você transforma a contagem em uma data de calendário para uma pessoa ler.
Por que os computadores contam segundos
Datas são incômodas de armazenar e comparar. Os meses têm durações diferentes, os anos às vezes têm 366 dias, e cada região escreve as partes em uma ordem diferente. Um único inteiro evita tudo isso. Dois timestamps podem ser comparados com um sinal de menor que, subtraídos para obter uma duração, ordenados como números simples e armazenados em um número fixo de bytes.
É por isso que bancos de dados, arquivos de log, tokens JWT, cabeçalhos de cache e a maioria das APIs trocam o tempo como um valor de epoch. Alguns marcos ajudam você a reconhecer um quando o vê:
0é 1970-01-01T00:00:00Z, a própria época.1000000000é 2001-09-09T01:46:40Z, o bilionésimo segundo.1696118400é 2023-10-01T00:00:00Z.1791676800é 2026-10-11T00:00:00Z.2147483647é 2038-01-19T03:14:07Z, o limite de 32 bits.
Valores negativos são permitidos e significam datas anteriores a 1970, embora nem todo sistema lide com eles.
Segundos versus milissegundos
A definição original conta segundos, e é isso que as ferramentas Unix, o time.time() do Python e a maioria dos bancos de dados retornam. O JavaScript quebrou a convenção. Date.now() retorna milissegundos, então o mesmo instante aparece como 1696118400000. O System.currentTimeMillis() do Java e muitos frameworks de logging seguem o JavaScript.
Misturar os dois é o bug de timestamp mais comum. Passe um valor em milissegundos onde se esperam segundos, e a data vai parar por volta do ano 55.000. Passe segundos onde se esperam milissegundos, e toda data vira 20 de janeiro de 1970. A verificação rápida é a contagem de dígitos: os valores atuais têm 10 dígitos em segundos e 13 em milissegundos. Alguns sistemas vão além, com 16 dígitos para microssegundos e 19 para nanossegundos.
Converter é uma multiplicação ou divisão por 1000. Em JavaScript, os segundos vêm de Math.floor(Date.now() / 1000), e um valor em segundos vira uma data com new Date(ts * 1000). O Conversor de Timestamp Unix detecta a unidade automaticamente pelo comprimento e mostra a data decodificada ao lado da forma ISO 8601, o que poupa você de adivinhar.
Os fusos horários não mudam o número
Um timestamp nomeia um instante, não um horário de relógio. 1696118400 é meia-noite de 1º de outubro em Londres, mas é 20:00 de 30 de setembro em Nova York, 05:30 de 1º de outubro em Mumbai e 09:00 de 1º de outubro em Tóquio. Os quatro são o mesmo instante e o mesmo número. Só a exibição muda.
É por isso que a regra sensata para qualquer sistema é: armazene e transmita timestamps em UTC e converta para o horário local no último momento possível, na interface do usuário. Se você armazenar um horário local, perde o instante. "2:30 de 5 de novembro" acontece duas vezes em Nova York quando os relógios atrasam, e nunca na data da primavera em que eles adiantam.
O horário de verão é o principal motivo para evitar aritmética com horário local. Somar 86400 segundos a um timestamp sempre avança exatamente um dia de tempo real, mas esse dia pode ter 23 ou 25 horas no relógio local. Se você precisa de "mesmo horário amanhã" no fuso de um usuário, faça o cálculo em termos de calendário com uma biblioteca que entenda fusos horários, não somando segundos.
Quando você precisar ver como um determinado instante fica em vários escritórios, o Conversor de Fuso Horário recebe uma data e hora e lista o equivalente em mais de 30 fusos, o que é mais rápido do que raciocinar sobre deslocamentos à mão.
Segundos intercalares e o limite de 2038
O tempo Unix finge que todo dia tem exatamente 86400 segundos. Os dias reais ocasionalmente incluem um segundo intercalar, e quando isso acontece o relógio do sistema repete ou estica um segundo em vez de contar até 60. Para quase todas as aplicações isso é invisível, mas é por isso que o tempo Unix não é exatamente igual ao número de segundos reais decorridos desde 1970.
O problema de 2038 é mais prático. Um inteiro de 32 bits com sinal chega ao máximo em 2147483647. Um segundo depois, em 19 de janeiro de 2038 às 03:14:08 UTC, ele dá a volta para um número negativo grande, que é decodificado como dezembro de 1901. Sistemas operacionais, linguagens e bancos de dados modernos usam valores de 64 bits e estão seguros pelos próximos 292 bilhões de anos. O risco está em dispositivos embarcados antigos, formatos de arquivo legados e qualquer schema que tenha escolhido INT em vez de BIGINT para uma coluna de epoch.
Trabalhando com timestamps em código
As conversões vêm embutidas em todas as linguagens, mas a forma varia:
- Shell:
date +%simprime o timestamp atual, edate -u -d @1696118400decodifica um no Linux. - Python:
datetime.fromtimestamp(1696118400, tz=timezone.utc)eint(dt.timestamp()). - JavaScript:
new Date(1696118400 * 1000).toISOString()eMath.floor(date.getTime() / 1000). - SQL:
to_timestamp(1696118400)no PostgreSQL,FROM_UNIXTIME(1696118400)no MySQL. - Excel:
=A1/86400 + DATE(1970,1,1)transforma um valor em segundos em um número de série de data.
Durações são apenas subtração. Os dois timestamps 1696118400 e 1696204800 diferem em 86400, o que é um dia. Divida por 3600 para obter horas ou por 604800 para semanas. Quando o resultado precisa ser expresso em unidades de calendário, como "2 anos, 3 meses e 14 dias", a subtração simples já não basta, porque a duração dos meses varia. A Calculadora de Duração faz esse detalhamento a partir de duas datas e também mostra os totais em dias, horas e segundos.
Mais conversores de datas, expressões cron e agendamentos ficam na categoria de data e hora.
Experimente
Cole 1696118400 no Conversor de Timestamp Unix para ver 1º de outubro de 2023 em UTC, depois cole 1696118400000 e confirme que ele detecta milissegundos e chega ao mesmo instante.