Jobs agendados

Um Job agendado executa uma tarefa automaticamente nos horários que você definir, como gerar um relatório toda madrugada ou limpar dados antigos a cada hora. Você não precisa manter uma aplicação ligada o tempo todo: a Zenifra inicia a tarefa no horário, acompanha a execução e cobra só pelo tempo em que ela rodou.

Este guia mostra como usar Jobs pelo Console. Para automatizar pela API ou pela CLI, veja a referência da API de Jobs agendados.

Como funciona

• Horário em UTC: o horário é definido por uma Expressão cron de cinco campos e é sempre interpretado em UTC.
• No máximo uma execução por vez: se chegar o próximo horário enquanto uma execução ainda está em andamento, esse horário é pulado. Ele não é enfileirado nem executado depois.
• Limite de 60 minutos: uma execução que não termina em 60 minutos é encerrada e aparece como Tempo limite excedido.
• Sem nova tentativa automática: se uma execução falhar, a Zenifra não tenta de novo para aquele horário. A próxima execução acontece no próximo horário agendado.
• Cobrança por minuto: você paga pelo tempo em que a tarefa realmente rodou, em BRL.

Criar um Job no Console

Vídeo: criação de um Job agendado, do formulário à página com horário e execuções.

1. No menu, clique em Criar projeto e escolha Job agendado.
2. Escolha seu plano. Cada plano mostra os recursos (vCPU, memória e armazenamento) e o preço por minuto.
3. Em Informações Básicas, dê um nome ao projeto.
4. Em Configurar Job agendado, preencha:
   • Imagem da tarefa: a referência completa de uma imagem Docker pública, com registro e tag ou digest (por exemplo, docker.io/library/alpine:3.20). O Console usa o comando padrão da própria imagem, então ela precisa executar a tarefa e terminar sozinha.
   • Expressão cron: cinco campos, em UTC. Logo abaixo, o Console mostra os Próximos horários de execução (UTC) para você conferir.
   • Armazenamento da tarefa: a capacidade em GB. Ative Manter dados entre execuções e informe o Diretório persistente (por exemplo, /data) se a tarefa precisar guardar arquivos de uma execução para a outra.
5. Em Variáveis de Ambiente, adicione as configurações que a tarefa usa, como chaves e endereços. Linhas vazias são ignoradas.
6. Confira o Resumo de Custos e clique em Criar Job.

O Console não pede porta, domínio nem instâncias, porque um Job não é um site ou uma API: ele roda, termina e espera o próximo horário.

Para usar uma imagem privada, um repositório do GitHub ou um comando e argumentos diferentes dos padrões da imagem, crie o Job pela API.

Exemplos de horário

Lembre-se de converter o seu horário local para UTC. Por exemplo, 00:00 no horário de Brasília (UTC−3) corresponde a 03:00 UTC.

Como o resultado de uma execução é definido

O resultado depende de como o processo da sua imagem termina:

• código de saída 0 significa sucesso, e a execução aparece como Concluída;
• qualquer código de saída diferente de zero (não-zero) significa falha, e a execução aparece como Falhou; o código 1 é só o exemplo mais comum;
• se o processo não terminar em 60 minutos, a execução aparece como Tempo limite excedido.

Imagens de servidor web, que ficam esperando requisições, nunca terminam sozinhas e sempre acabam em Tempo limite excedido. Para um Job, use uma imagem cujo comando padrão execute a rotina e termine.

Acompanhar as execuções

A página do projeto concentra tudo o que acontece com o seu Job.

Horário do Job

O card Horário do Job mostra a expressão cron atual e o fuso horário (UTC). Clique em Editar para mudar o horário; a mudança vale para as próximas execuções.

Lista de execuções

O card Execuções lista as execuções do ciclo de cobrança atual, com:

• Agendada para: o horário programado;
• Status: a situação da execução;
• Duração: quanto tempo a tarefa rodou;
• Minutos cobrados: os minutos usados no cálculo do valor.

Clique em Atualizar execuções para ver as novidades. Os status possíveis são:

Logs

Clique em Ver logs em uma execução para ler o que a tarefa escreveu durante aquela execução. Os logs ajudam a entender uma falha ou confirmar o que foi processado.

Métricas

Clique em Ver métricas para acompanhar o uso de CPU e memória da execução. Enquanto ela roda, o Console mostra Coletando métricas com os valores mais recentes; depois do término, mostra média e pico. Métricas indisponíveis significa que não houve amostras suficientes (por exemplo, em execuções de poucos segundos) — não significa uso zero.

As métricas por execução fazem parte do plano job-premium. Nos outros planos, o botão Ver métricas não aparece. Além do plano, a pessoa precisa da permissão Visualizar métricas.

Cancelar, pausar, retomar e excluir

Cancelar uma execução

Na lista de execuções, clique em Cancelar execução na execução em andamento e confirme. A Zenifra dá até 30 segundos para a tarefa terminar de forma graciosa e, se ela não terminar, faz a limpeza forçada.

A cobrança vai só até o momento em que você confirmou o cancelamento; os segundos de encerramento não são cobrados. Cancelar uma execução não muda o horário: a próxima execução acontece normalmente.

Pausar e retomar

Clique em Pausar e confirme em Pausar projeto para interromper os próximos horários. Se houver uma execução em andamento, ela também é cancelada, com cobrança até o momento da pausa. Para voltar a executar nos horários programados, clique em Retomar.

Excluir um Job

Clique em Excluir e confirme. Se houver uma execução em andamento, ela é cancelada e cobrada até o momento da exclusão, e então o projeto é removido. Se aparecer um aviso de que execuções ainda estão sendo finalizadas, aguarde alguns instantes e tente de novo — não é preciso repetir várias vezes.

Permissões

Cada ação do Console depende de uma permissão do papel da pessoa na organização. As permissões são configuradas na tela Membros, na seção Projetos:

Quando falta uma permissão, o Console esconde ou desabilita a ação correspondente e informa que o seu acesso não a inclui.

Cobrança

Preço por minuto

Cada plano tem um preço por minuto, em BRL, mostrado no Console ao escolher o plano. Como os valores são frações de centavo, o Console mostra até seis casas decimais para o preço por minuto e até quatro para valores e totais — por exemplo, R$ 0,000167 por minuto.

Como os minutos são contados

• A cobrança considera o início e o fim reais da tarefa. O tempo de preparação, como o download da imagem, não é cobrado, e uma execução que nunca chegou a iniciar não gera cobrança.
• A duração é arredondada para o minuto cheio seguinte, com mínimo de 1 minuto e máximo de 60.
• O valor de cada execução é armazenado exato, sem arredondamento para cima: uma execução que custa R$ 0,0005 é cobrada como R$ 0,0005.
• Execuções que falharam, foram canceladas depois de iniciar ou excederam o tempo limite cobram o tempo efetivamente usado.
• Uma execução em andamento ainda não gera cobrança; o valor aparece quando ela termina.

Custo do ciclo atual

O card Custo do ciclo atual soma os valores armazenados das execuções concluídas no ciclo, mostrando também quantas execuções houve e quantos minutos foram contabilizados. Cada execução entra no custo depois que o valor dela é registrado, o que leva alguns instantes após o término, mesmo antes do processamento financeiro da cobrança. Esse valor não muda se o preço do plano mudar depois.

A linha Reinicia em mostra a próxima data de cobrança. Nessa data, a lista de execuções, o custo do ciclo, os logs e as métricas exibidos recomeçam do zero, independentemente da liquidação financeira. Cada execução pertence ao ciclo em que começou, mesmo que termine depois da virada.

Os registros de execução e de métricas são mantidos internamente por até 90 dias. O uso materializado e os registros financeiros ficam guardados para auditoria e não são apagados quando o ciclo exibido recomeça.

Na cobrança do ciclo, os valores são somados e descontados primeiro do saldo da organização; o que faltar é cobrado no cartão em centavos inteiros, e a fração de centavo restante fica para o próximo ciclo. Veja mais em Pagamentos e cobrança.

Armazenamento

O armazenamento efêmero é criado para cada execução e não adiciona cobrança, mas os dados não são preservados para a próxima execução. Com Manter dados entre execuções ativo, os arquivos no Diretório persistente ficam guardados, e o armazenamento persistente é cobrado à parte, por GB-hora, enquanto o projeto existir — inclusive pausado — até a exclusão.

Diagnóstico rápido

Próximos passos

• Referência da API de Jobs agendados — automação, imagens privadas, GitHub e comandos personalizados
• Métricas e Logs
• Pagamentos e cobrança