Linux / Comando time: medir duração e uso de recursos

time mede a duração de um comando ou pipeline e o tempo de CPU (unidade central de processamento) que ele consome. No Bash, a palavra reservada time também mede funções e comandos internos; o programa externo GNU Time oferece estatísticas adicionais, como memória e entrada/saída (E/S).

Use o time do Bash para comparar a duração de uma tarefa e o GNU Time quando precisar de dados adicionais do sistema operacional. Os exemplos de sintaxe do shell abaixo pressupõem Bash no modo padrão, sem o modo POSIX; as opções do programa externo pressupõem a implementação GNU, instalada separadamente.

O que é o comando time?

No Bash, time é uma palavra reservada reconhecida pelo analisador de sintaxe. Por isso, consegue medir um pipeline inteiro, uma função ou um comando interno do próprio shell, sem exigir que exista um executável com aquele nome. Um pipeline conecta a saída de um comando à entrada do seguinte pelo operador |.

O programa GNU Time pode estar instalado em /usr/bin/time, mas esse caminho e sua presença não são garantidos. As linhas abaixo identificam como o shell interpreta o nome e verificam se há um arquivo nesse caminho. type -a time pode mostrar tanto a palavra reservada quanto um executável; command -V time sozinho não confirma a instalação do programa externo. O guia de type explica esses resultados.

type -a time
command -V time
ls -l /usr/bin/time

Sintaxe básica do time no Bash

time [-p] comando [argumentos...]
time [-p] comando1 | comando2

O bloco anterior é uma sinopse: os colchetes indicam partes opcionais e os nomes comando e argumentos devem ser substituídos. Para uma primeira medição, execute apenas time sleep 1. A segunda linha abaixo é outro exemplo: percorre arquivos em /usr sem alterá-los, mas pode levar tempo e encontrar diretórios sem permissão.

time sleep 1
time find /usr -type f >/dev/null

Com o formato padrão do Bash, o relatório ao fim da tarefa contém real, user e sys. Em sleep 1, espere uma duração próxima de um segundo e pouco consumo de CPU, sem exigir um valor exato. No exemplo com find, >/dev/null descarta a saída padrão; mensagens de erro continuam visíveis e devem ser verificadas.

O significado de real, user, sys

Quando o trabalho usa vários processos ou núcleos em paralelo, user + sys pode superar real, pois soma tempo de CPU. Se a tarefa passa muito tempo esperando E/S, o tempo decorrido pode ser alto e o consumo de CPU baixo. Não interprete real - user - sys como uma medição exata de espera de disco ou rede.

Medir todo o pipeline

Neste exemplo, o Bash mede até o término de todo o pipeline: find procura arquivos, xargs recebe os nomes separados por bytes nulos e chama wc para contar linhas. A saída final é descartada para observar a duração. A leitura de /var/log depende de permissões; erros não significam que todos os arquivos foram processados.

time find /var/log -type f -print0 | xargs -0 wc -l >/dev/null

A posição e a implementação de time determinam o que é medido. Um programa externo colocado antes do primeiro comando mede esse programa, sem incluir automaticamente o restante do pipeline. Para medir um pipeline inteiro com GNU Time, pode-se executar um shell explicitamente, por exemplo /usr/bin/time bash -c 'comando1 | comando2', substituindo os comandos; nesse caso, a medição também inclui o shell iniciado.

Medir vários comandos como uma tarefa

Chaves ou parênteses agrupam vários comandos em uma única tarefa cronometrada. O primeiro exemplo exige make, um projeto com Makefile e o alvo clean. A limpeza pode remover artefatos de compilação: confira as regras do projeto antes de executá-la. -j4 permite até quatro tarefas de compilação simultâneas.

time {
  make clean && make -j4
}

time (
  cd /srv/app && ./build.sh
)

No primeiro bloco, && só inicia a compilação se a limpeza terminar com sucesso. No segundo, substitua /srv/app pelo diretório real do projeto e use aspas se o caminho tiver espaços e confirme que build.sh existe e é executável; o script só roda se cd funcionar. As chaves executam no shell atual, enquanto os parênteses criam um subshell e preservam o diretório e as variáveis do shell chamador. O tempo inclui as etapas executadas, inclusive uma etapa que falhe.

Formato de saída POSIX com -p

time -p sleep 1

-p seleciona o formato POSIX, com os rótulos real, user e sys e valores em segundos. Para processar o relatório automaticamente, considere também a localidade, a precisão e o destino do erro padrão. No modo POSIX do Bash há uma particularidade: se o próximo token começa com -, o analisador não reconhece time como palavra reservada, e a resolução pode selecionar um executável externo. Não extrapole este exemplo para qualquer shell.

Ajustar a saída do Bash com TIMEFORMAT

A variável TIMEFORMAT controla o relatório da palavra reservada do Bash. No exemplo, %3R, %3U e %3S pedem três casas decimais. Os rótulos elapsed, user e sys são texto escolhido para a saída; a precisão exibida não garante igual precisão na medição.

TIMEFORMAT='elapsed=%3R s user=%3U s sys=%3S s'
time sleep 1

A atribuição anterior permanece no shell atual. Para experimentar sem alterar seu formato, use o subshell abaixo em uma pasta de teste onde ainda não exista job.sh. Ele cria um script completo que escreve uma mensagem na saída padrão, espera um segundo e escreve outra no erro padrão. noclobber impede sobrescrever um arquivo regular já existente com esse nome; se a criação falhar, o bloco termina. O arquivo criado será reutilizado nos exemplos seguintes.

(
  set -o noclobber
  cat > job.sh <<'EOF' || exit 1
#!/usr/bin/env bash
printf '%s\n' 'Início da tarefa'
sleep 1
printf '%s\n' 'Fim da tarefa' >&2
EOF
  chmod u+x job.sh || exit 1
  TIMEFORMAT='elapsed=%R s'
  time ./job.sh
)

Você verá Início da tarefa, depois Fim da tarefa e um relatório elapsed=... em segundos. Os números dependem do ambiente. Ao sair do subshell, o valor anterior de TIMEFORMAT permanece no shell chamador, mas o arquivo job.sh continua na pasta. Quando terminar os testes, remova apenas os arquivos de exemplo que você criou e não precisa mais.

Usar o programa externo GNU Time

Confirme primeiro se /usr/bin/time --version identifica GNU Time. Se o arquivo não existir, procure o pacote da sua distribuição e confirme o caminho instalado; não confunda a palavra reservada disponível com a presença do programa. Com o job.sh criado acima, execute uma das linhas abaixo conforme o nível de detalhe desejado.

/usr/bin/time ./job.sh
/usr/bin/time -v ./job.sh

-v apresenta estatísticas como memória residente máxima, falhas de página, E/S do sistema de arquivos e trocas de contexto. Uma falha de página é um evento de gerenciamento de memória, não necessariamente um erro da aplicação. Nem todo sistema fornece todos os dados; o GNU Time pode mostrar zero para recursos indisponíveis, portanto zero não prova ausência de atividade.

Opções úteis do GNU Time

Exibir duração e memória no formato desejado

/usr/bin/time -f 'elapsed=%e max_rss=%MKB' ./job.sh

%e é a duração em segundos. %M é o tamanho máximo do conjunto residente (maximum resident set size, RSS): o pico de memória física residente informado pelo sistema durante a execução. O manual GNU o expressa em quilobytes. Esse valor não é a média de uso, o total de alocações nem uma prova isolada de vazamento de memória. Os códigos de formato do GNU Time são diferentes dos de TIMEFORMAT do Bash.

Salvar o relatório em um arquivo

/usr/bin/time -v -o time-report.txt ./job.sh
/usr/bin/time -v -a -o time-report.txt ./job.sh

Execute a primeira linha para gravar o relatório e, se quiser registrar outra execução no mesmo arquivo, a segunda para acrescentá-la. Sem -a, -o sobrescreve um relatório existente: escolha um nome livre ou preserve o conteúdo anterior. Abra time-report.txt para conferir os dados. A saída padrão e o erro padrão de job.sh continuam nos destinos normais; -o redireciona o relatório do GNU Time.

Separar o relatório da saída da tarefa

O relatório vai para o erro padrão, o canal de diagnósticos, para não se misturar com a saída padrão da tarefa. Antes dos exemplos abaixo, escolha nomes de arquivos que possam ser criados ou substituídos: > e 2> sobrescrevem arquivos existentes quando a proteção contra sobrescrita não está ativa.

time ./job.sh >job-output.txt

Com o job.sh deste artigo, job-output.txt recebe apenas Início da tarefa. A mensagem Fim da tarefa e o relatório de tempo permanecem no erro padrão, normalmente o terminal. No bloco seguinte, o redirecionamento do grupo envia ambos para time-and-errors.txt; não separa somente o relatório.

{ time ./job.sh >job-output.txt; } 2>time-and-errors.txt

Abra os dois arquivos para conferir a separação: um contém a saída normal e o outro reúne o diagnóstico do script e a medição. Para guardar somente o relatório sem capturar junto o erro padrão da tarefa, prefira -o do GNU Time.

Cuidados ao comparar tempos

• A primeira execução e as seguintes podem diferir por cache do sistema de arquivos, compilação em tempo de execução (JIT) ou reutilização de conexões. Separe medições de primeira execução das medições com recursos já preparados.
• Mantenha comparáveis a carga em segundo plano, a frequência da CPU e a disputa por recursos em máquinas virtuais. Registre a versão do programa, as entradas, o número de tarefas paralelas e o destino da saída.
• Em tarefas muito curtas, o custo de iniciar processos e medir pode ter peso significativo. Não trate pequenas diferenças como conclusivas sem repetir o teste.
• Repita várias vezes e compare a mediana ou a distribuição.
• O tempo de execução pode variar dependendo de o destino da saída ser um terminal ou um arquivo.
• Verifique também se a diferença de velocidade realmente altera o resultado da tarefa ou a taxa de erro.

A referência de comandos Linux reúne outras ferramentas para montar e verificar as tarefas medidas. Para interpretar os números, defina primeiro qual trabalho e quais processos entram na comparação.

Comparar time do Bash e GNU Time

Perguntas frequentes

O tempo de CPU pode superar o tempo decorrido?

Sim. Se o tempo de CPU usado em múltiplos processos ou núcleos de CPU se acumular, o tempo de CPU do usuário pode ser maior que o tempo efetivamente decorrido.

Por que time -v não funciona no Bash?

No Bash padrão, time é interpretado como palavra reservada e não oferece a opção GNU -v. Confirme a implementação com /usr/bin/time --version e, se for GNU Time, execute /usr/bin/time -v ./job.sh com o script preparado. Se o caminho não existir, será necessário localizar ou instalar o programa externo.

O comando time altera o status de saída de um comando?

O time do Bash preserva o status do comando ou pipeline medido. Sem pipefail, um pipeline normalmente usa o status do último comando; com essa opção, usa o da falha mais à direita, ou zero se todos tiveram sucesso. Assim, um relatório de tempo não prova sucesso de todas as etapas. O programa GNU Time também pode falhar antes de executar a tarefa; verifique os diagnósticos e consulte $? imediatamente depois da medição, antes que outro comando o substitua.

Documentação oficial

• Manual do GNU Bash: Pipelines e a palavra reservada time
• Manual do GNU Time: formatos, recursos e arquivos de relatório
• Manual do Bash: variável TIMEFORMAT