Meça o comportamento de CPU, memória e IRQ.

O Jitter Tools 1.3.0 fornece três ferramentas independentes de linha de comando para Linux. O CPUJitter observa intervalos sem execução em uma CPU. O MEMjitter mede operações de memória declaradas. O IRQjitter observa eventos de IRQ e softirq do kernel por meio de tracefs. Use cada uma separadamente para responder a uma pergunta de medição específica.

./cpujitter --version
./memjitter --version
./irqjitter --version

Os exemplos abaixo são executados a partir de uma distribuição binária descompactada. Após a compilação do código-fonte, os mesmos executáveis estão em ./bin/. Se estiverem instalados em PATH, omita o prefixo ./. Os números de CPU são exemplos, não uma recomendação de posicionamento para produção. Substitua-os por IDs de CPU Linux permitidos e on-line no seu host.

grep -E "Cpus_allowed_list|Mems_allowed_list" /proc/self/status
cat /sys/devices/system/cpu/online

./cpujitter -c 4 --duration 10

./memjitter -c 4 --duration 10

sudo ./irqjitter -c 1 --duration 10

Execute estes exemplos um de cada vez. Os testes de CPU e memória são cargas de trabalho ativas. O IRQjitter é passivo no sentido de não gerar tráfego de teste, mas o rastreamento e a coleta ainda têm sobrecarga. CPU/MEM não exigem root, SMT desativado, isolamento de CPU, uma CPU exclusiva nem HFTKernel. A coleta de IRQ exige acesso a uma montagem tracefs existente e permissão para criar sua própria instância; sudo é uma forma de fornecer essas permissões.

Referência do código-fonte: S1, S2, S3, S7.

O arquivo 1.3.0 fornecido contém somente código-fonte. Ele não contém executáveis ELF prontos para uso. Sua qualificação registrada não comprova uma compilação Rust concluída nem uma execução real de IRQ. O ponto de entrada aceito para o código-fonte é test.sh; ele compila e testa antes de publicar os binários.

cd jitter-tools-1.3.0
./test.sh

O Cargo é executado off-line, com um conjunto fixo de dependências e sem dependências de registro. As dependências de teste do Python podem ser provisionadas em .test-env/ dentro do projeto. Use --offline quando o ambiente já estiver preparado e os downloads de índices de pacotes precisarem ser desativados.

./test.sh --offline --acceptance

Após a aprovação de todos os controles obrigatórios, o fluxo de trabalho publica bin/cpujitter, bin/memjitter, bin/irqjitter, bin/build-ok.json e um arquivo de distribuição estática com versão. As referências públicas ao arquivo usam o nome canônico jitter-tools-1.3.0.tgz. O conjunto da versão inclui BUILD.json, ELF.json, somas de verificação, avisos e documentação. Não trate uma compilação do código-fonte parcialmente concluída como uma distribuição estática qualificada.

./test.sh
./cpujitter --build-info
./memjitter --build-info
./irqjitter --build-info

O test.sh da distribuição binária exige sh, readelf, sha256sum e grep. Ele não é o executor de compilação do código-fonte. Os executáveis estáticos GNU não precisam de Rust, Python, um interpretador ELF nem bibliotecas compartilhadas adjacentes em tempo de execução. Ainda precisam de um kernel Linux compatível com a arquitetura, das chamadas de sistema necessárias e de /proc e /sys; o IRQjitter também precisa de tracefs. As verificações ELF são evidências do empacotamento, não uma garantia de precisão de medição ou de suporte em todas as versões do kernel.

Referência do código-fonte: S1, S2.

CPU/MEM também aceitam --cpu e --interval. O IRQjitter 1.3.0 usa somente -c e -n para esses controles. As três ferramentas aceitam valores curtos anexados, como -c4 -n0.1. Use segundos decimais simples, por exemplo 0.1, não 100ms, 1e-1 ou .1. Opções repetidas são rejeitadas.

./cpujitter -c4 -n0.1 --duration 5

./cpujitter -c 4 --raw --json --samples 1000 > cpu-raw.jsonl 2> cpu-raw.stderr.log

Os dados vão para stdout e os diagnósticos para stderr. Redirecionar stdout não seleciona o modo JSON nem o modo sem processamento. Use uma duração finita ou Ctrl+C para parar. Um SIGINT/SIGTERM tratado emite registros finais quando o canal de saída permanece utilizável e a limpeza é bem-sucedida. Uma chamada de sistema bloqueada, SIGKILL, um host com falha ou um pipe fechado impedem qualquer garantia de parada imediata ou saída final completa.

Referência do código-fonte: S2, S3, S9.

A métrica cpu_iteration_elapsed_ns é o tempo decorrido calibrado entre leituras consecutivas do contador de hardware dentro de um lote de captura. Ela inclui a ramificação do laço, o armazenamento de marcas de tempo e a sobrecarga de leitura do contador. Não é a contagem de ciclos do núcleo da CPU, uma medição da entrega de interrupções de dispositivos nem uma classificação direta da causa de uma pausa.

ordered é o modo padrão de leitura do contador; relaxed é uma alternativa explícita com contexto distinto. A calibração usa sete segmentos de pelo menos 50 ms em relação a CLOCK_MONOTONIC_RAW, com escala fixa durante a execução. Nenhum valor de referência nem custo do contador é subtraído. Em x86, são necessários suporte declarado a TSC invariável e acesso utilizável ao contador; contadores incompatíveis são rejeitados em vez de substituídos silenciosamente.

./cpujitter -c 4 -n 1 --duration 30
./cpujitter -c 4 -n 1 --duration 30 --counter-read relaxed

./cpujitter -c 4 -n 1 --duration 30 \
  --threshold cpu_iteration_elapsed_ns=5000

./cpujitter -c 4 --duration 30 --json > cpu.jsonl 2> cpu.stderr.log

Um lote tem uma marca de tempo inicial e observações concluídas. A captura é separada das âncoras do relógio, da validação, da agregação e da saída. Um orçamento cooperativo do contador verifica aproximadamente 20 ms de trabalho de captura a cada 256 registros; ele não corta um atraso observado grande. ACTIVE% descreve a parte de captura coberta, não a utilização total da CPU. Pausas que ocorrem fora da captura não são observadas para esta métrica.

Os nanossegundos são calculados com aritmética inteira verificada e arredondamento para o inteiro mais próximo: (delta_ticks * 1000000000 + hz / 2) / hz. As marcas de tempo dos eventos para atribuição a janelas usam o mapeamento delimitado do contador para MONOTONIC. O valor e seu intervalo mapeado de início/fim têm finalidades diferentes e não precisam ser numericamente idênticos. A precisão física desconhecida permanece como null no fluxo.

Referência do código-fonte: S2, S3, S9.

Leituras e leituras/modificações/gravações em memória residente

Os padrões são resident, read, sequential, um mapeamento de 16777216 bytes (16 MiB), um passo do tamanho de página do sistema, deslocamento 0 e semente 1. A preparação toca cada página base, aquece o plano de acesso e verifica a residência inicial com mincore. Sem um bloqueio explícito, essa captura do estado não garante residência contínua.

./memjitter -c 4 --bytes 16777216 --duration 30
./memjitter -c 4 --operation rmw --pattern random --seed 1 --duration 30

read cronometra uma carga volátil de byte. rmw cronometra uma carga de byte, um incremento com estouro modular e uma gravação; não é atômico nem mede a conclusão globalmente visível da gravação. O intervalo cronometrado inclui a sobrecarga de marcas de tempo e barreiras. O resultado não é a latency pura da DRAM.

Seguimento dependente de ponteiros

./memjitter -c 4 --operation chase --bytes 16777216 \
  --seed 1 --duration 30

--operation chase seleciona pointer-chase automaticamente, a menos que um padrão seja explícito. Um padrão explícito também deve ser pointer-chase. Outros padrões de memória residente são sequential, random com reposição e permutation. A seleção de endereços e a manutenção dos registros ficam fora de cada operação medida. Um mapeamento de 16 MiB com passos de uma página em um host com páginas de 4096 bytes tem 4096 posições amostradas, não 16 MiB de dados lidos a cada passagem.

Gravações de first-touch

./memjitter -c 4 --mode first-touch --reset remap \
  --bytes 16777216 --duration 30

./memjitter -c 4 --mode first-touch --reset madvise \
  --pattern permutation --seed 1 --duration 30

First-touch permite sequential ou permutation, sem reposição dentro de uma época. write é a única operação e não precisa ser especificada. Após cada remapeamento/descarte bem-sucedido, mincore deve confirmar que não há páginas residentes antes de uma nova época começar. O trabalho de redefinição é tempo de serviço excluído. A primeira gravação de um byte não é necessariamente uma falha de página separada nem uma alocação de página física, especialmente quando THP cobre vários deslocamentos. Remap e madvise são experimentos diferentes.

Chamadas à API de alocação

./memjitter -c 4 --mode alloc --bytes 65536 --duration 30
./memjitter -c 4 --mode alloc --operation mmap --samples 65 --json

Alloc cria no máximo um mapeamento próprio por vez e o desmapeia antes da próxima chamada. Somente intervalos mmap bem-sucedidos entram no histograma. mmap estabelece um mapeamento virtual, não a materialização física de todas as páginas. A camada C ABI/libc e o intervalo de marcas de tempo continuam fazendo parte do valor. Este modo não implementa o antigo alloc-cycle, a latency de malloc/calloc nem a geração automática de pressão de memória.

Opções de distribuição e modo

./memjitter -c 4 --mode first-touch --duration 30 \
  --threshold mem_first_touch_ns=20000

Alloc rejeita opções de padrão, passo, deslocamento, semente e redefinição, mesmo quando seus valores se parecem com os padrões. Nenhum modo de memória aceita --counter-read do CPUJitter. Mantenha a mesma operação, padrão, bytes, passo, deslocamento, semente, redefinição e modo de saída ao comparar resultados.

Referência do código-fonte: S2, S4, S5.

Os padrões são --lock none, --thp system, política NUMA herdada e nenhuma solicitação explícita de HugeTLB. A ferramenta não reconfigura o sistema, amplia limites de bloqueio, altera a reserva de páginas enormes nem tenta novamente com uma política menos restritiva. Uma solicitação explícita incompatível falha e informa o motivo.

./memjitter -c 4 --bytes 65536 --lock resident --duration 10

./memjitter -c 4 --mode first-touch --lock onfault \
  --reset remap --bytes 65536 --duration 10

./memjitter -c 4 --thp never --duration 10
./memjitter -c 4 --thp prefer --duration 10

./memjitter -c 4 --numa-node 0 --duration 10

./memjitter -c 4 --bytes 2097152 \
  --hugetlb-bytes 2097152 --duration 10

O bloqueio impede a troca para swap do mapeamento enquanto mantido; ele não coloca os dados permanentemente no cache da CPU. Uma chamada aceita de orientação THP não comprova o uso de páginas enormes. A leitura da política NUMA configurada é diferente da observação do posicionamento físico das páginas. Os IDs NUMA são 0..4095 e devem ser permitidos pelo host.

Um tamanho HugeTLB explícito deve ser uma potência de dois maior que a página base do sistema operacional, de no máximo 1 GiB, e dividir o tamanho do mapeamento. Ele é incompatível com bloqueio explícito ou orientações THP diferentes de system. A preparação de memória residente exige sucesso de MADV_POPULATE_WRITE nesse intervalo. A reserva existente, as cotas, as permissões e a operação necessária do kernel devem dar suporte à solicitação; não há recurso alternativo a páginas comuns.

A política solicitada, as operações bem-sucedidas e o estado observado do mapeamento são registrados separadamente. As observações iniciais aparecem em meta; as observações finais do mapeamento são gravadas em stderr antes do desmapeamento. Informações indisponíveis ou não atribuíveis permanecem como null. As capturas de arquivos proc e as verificações de políticas acrescentam trabalho de serviço, portanto compare execuções com políticas equivalentes.

Referência do código-fonte: S2, S6.

O IRQjitter usa uma thread leitora no espaço de usuário e sua própria instância tracefs. Os tracepoints de IRQ necessários são irq_handler_entry, irq_handler_exit, softirq_raise, softirq_entry e softirq_exit. A instância deve aceitar o relógio de rastreamento mono. Ele não monta tracefs, altera suas permissões com chmod, muda a afinidade de IRQ/RSS, para irqbalance nem ativa um backend alternativo.

grep " tracefs " /proc/mounts

sudo ./irqjitter -c 1 --tracefs /sys/kernel/tracing --duration 15

CPU do coletor versus CPUs observadas

sudo ./irqjitter -c 1 --target-cpus 4-7 --duration 30

Sem --target-cpus, são observados os eventos compatíveis de todas as CPUs on-line, incluindo a CPU do coletor. Uma lista de CPUs como 2,4-7 restringe a coleta, não apenas a apresentação. A atividade de IRQ que se desloca para fora do conjunto selecionado fica fora da cobertura. A conexão a quente de CPU é monitorada dentro do conjunto inicial de CPUs possíveis, e as alterações são informadas com dados de cobertura.

Três métricas de tempo distintas

Uma fonte de IRQ é identificada pela métrica, pela CPU real, pelo número e pelo nome da fonte. As contagens descrevem observações concluídas de manipuladores, não interrupções físicas nem pacotes. Pares idênticos de número/nome de fonte não comprovam uma identidade persistente do dispositivo após reconfiguração. Um valor decorrido de zero pode refletir a resolução das marcas de tempo textuais da trilha, geralmente na ordem de microssegundos, em vez de tempo físico zero.

Visão geral, detalhes e eventos sem processamento

sudo ./irqjitter -c 1 -n 1 --duration 30
sudo ./irqjitter -c 1 -n 1 --details --duration 30
sudo ./irqjitter -c 1 -n 1 --json --duration 30 > irq.jsonl 2> irq.stderr.log

sudo ./irqjitter -c 1 --target-cpus 4 --raw --json \
  --duration 2 > irq-raw.jsonl 2> irq-raw.stderr.log

--details é válido somente para janelas compactas e não pode ser combinado com --json nem --raw. JSON já preserva os registros de janelas por CPU/fonte. Esta versão não tem modo timerlat nem backend eBPF. A softirq TIMER real continua observável.

Observações opcionais de trabalho/orçamento de NAPI

sudo ./irqjitter -c 1 --napi --duration 15
sudo ./irqjitter -c 1 --napi --details --duration 15

--napi exige um tracepoint napi:napi_poll compatível. A métrica é napi_poll_work, com unidade work, não nanossegundos. Ela informa o valor de trabalho retornado e o orçamento. at_budget exige orçamento positivo com trabalho igual ao orçamento; over_budget exige trabalho maior que um orçamento positivo. Nenhum dos dois comprova, por si só, um acúmulo de pacotes pendentes. Não são fornecidos a duração de NAPI, a latency de IRQ a NAPI nem um ID inferido de fila de hardware.

Controles de janelas e recursos

sudo ./irqjitter -c 1 --target-cpus 4-7 -n 1 \
  --threshold 10000 --duration 30

Amostras concluídas com atraso são informadas como atrasadas e não são movidas para uma janela posterior nem usadas para reescrever saídas antigas. Uma saída lenta pode atrasar a leitura das trilhas e causar perda nos buffers do kernel. O coletor verifica os controles e as estatísticas dos buffers, mas nem leituras vazias nem a ausência de avisos de perda comprovam cobertura completa. A instrumentação de rastreamento também é executada nas CPUs dos eventos, não apenas na CPU do coletor.

Referência do código-fonte: S2, S7, S8.

Colunas compactas de CPU/MEM

TIME(s) CPU COUNT MIN AVG P99<= P99.9<= MAX ACTIVE% LOSS QUALITY PART

Um limiar de tempo adiciona um sufixo como >5000=N, em que N é a contagem estritamente acima do limite. Uma população vazia tem COUNT=0 e estatísticas NA, não latency zero. O --details de IRQ adiciona METRIC, SOURCE, UNIT e os campos específicos de NAPI BUDGET_MAX, AT_BUDGET e OVER_BUDGET; os valores não aplicáveis são NA.

Colunas da visão geral de IRQ

TIME(s) IRQ_N IRQ_P99<= IRQ_MAX SOFT_N SOFT_P99<= SOFT_MAX WAIT_N WAIT_P99<= WAIT_MAX PAIR_GAPS LATE BUFFER OTHER PART

IRQ, SOFT e WAIT são populações separadas. Cada uma combina histogramas de fontes compatíveis das CPUs observadas para essa métrica e janela; os percentis são recalculados a partir das contagens agrupadas dos intervalos, não pela média dos percentis das fontes.

Por exemplo, softirq_entry_without_observed_raise incrementa os diagnósticos de pareamento. Ele não comprova estouro do buffer circular de rastreamento, e uma duração válida de entrada/saída posterior ainda pode ser mantida. As estatísticas dos buffers e os marcadores textuais de perda podem se sobrepor; não os some para inventar uma contagem total de perdas.

Resumos ao final da execução

A saída compacta imprime # SUMMARY, linhas # TOTAL e um status de encerramento após a última janela, incluindo a janela parcial final. CPU/MEM e os detalhes de IRQ resumem cada série; a visão geral de IRQ produz totais de tempo agrupados separados e totais opcionais de trabalho NAPI. O resumo da visão geral de IRQ inclui MAX_CPU e MAX_SOURCE, para que o maior evento observado mantenha sua fonte.

Os totais usam contagens e somas exatas de janelas totalmente informadas, média ponderada, extremos e intervalos de histograma mesclados. Não são médias de médias nem de percentis das janelas. scope=reported_windows exclui amostras não informadas e atrasadas. Uma fonte associada a um máximo é uma identidade de observação, não uma causa raiz comprovada.

JSON Lines para automação

Use --json para preservar metadados, janelas por série, motivos de qualidade, registros de perdas/intervalos sem cobertura e o registro terminal de encerramento. Use --raw --json para amostras individuais. O texto de resumo compacto não é acrescentado ao JSON. Valores inteiros grandes, como nanossegundos, contagens e somas, são strings decimais; interprete-os como inteiros, não como números de ponto flutuante. Um valor null é desconhecido, não zero.

jq 'select(.type == "meta")' cpu.jsonl
jq 'select(.type == "end") | {execution, exit_code, quality, cleanup}' cpu.jsonl
jq 'select(.type == "window") | {series, stats, coverage}' cpu.jsonl

O registro de encerramento separa execution, a qualidade e cleanup.confirmed. observations_aggregated é importante para o modo de janelas; um observations_emitted igual a zero não significa que nenhum dado foi coletado se os valores foram agregados em janelas. Preserve o arquivo completo e stderr, em vez de apenas linhas de janelas selecionadas.

Referência do código-fonte: S8, S9.

Estes são os códigos documentados da ferramenta, não uma garantia sobre cada shell, camada de tempo limite ou sinal fatal. Preserve status diferentes de zero; evite acrescentar || true para fazer um resultado parecer bem-sucedido. Um pipe fechado por head pode impedir os registros finais. --samples ou --duration é a forma aceita de limitar uma captura.

out="jitter-run-$(date -u +%Y%m%dT%H%M%SZ)"
mkdir "$out"
./cpujitter --build-info > "$out/build-info.json"

if ./cpujitter -c 4 -n 1 --duration 30 --json \
    > "$out/cpu.jsonl" 2> "$out/cpu.stderr.log"; then
    rc=0
else
    rc=$?
fi
printf "%s\n" "$rc" > "$out/exit-code.txt"
printf "Saved %s, exit code %s\n" "$out" "$rc"

case "$rc" in
  0) echo "Completed; inspect the end record." ;;
  3) echo "Partial/unqualified; inspect quality and cleanup before comparing." ;;
  *) echo "Run did not complete normally; inspect diagnostics." >&2 ;;
esac

Compare execuções equivalentes

Para comparar o kernel padrão com o HFTKernel, use a mesma compilação do executável, função de CPU, modo de memória, operação, padrão, tamanho, semente, política de redefinição, políticas explícitas de memória, modo de leitura do contador, lote, destino de saída, tamanho de janela e duração. Preserve os metadados do kernel, da topologia e do escalonador de cada execução. Altere a variável pretendida em vez de mudar a definição da medição ao mesmo tempo.

Execute cada experimento separadamente. Esta versão permite iniciar duas ferramentas ativas na mesma CPU, mas então as execuções interferem entre si e não são referências independentes. Mantenha o rastreamento de diagnóstico separado da medição A/B principal quando o objetivo for evitar introduzir uma carga de rastreamento diferente em apenas um dos lados.

Compare contagens, distribuições, máximos, excedências de limiares, cobertura e qualidade em conjunto. Não calcule a média de valores p99 entre execuções ou janelas. Um total compacto de toda a execução agrupa os histogramas informados dentro dessa execução; uma análise exata de populações entre execuções exige preservar dados subjacentes compatíveis. A CLI 3.x de CPU/MEM e suas populações de medição não são intercambiáveis com os perfis de testes 2.x anteriores já publicados no site do HFTKernel.

Referência do código-fonte: S1, S3, S6, S9.

O encerramento ordenado de IRQ interrompe o registro, drena os dados dentro de limites definidos, desativa os eventos próprios, fecha os descritores, remove somente sua própria instância e restaura a afinidade. Uma falha tratada continua sendo uma falha mesmo que a limpeza posterior libere os recursos. SIGKILL e falhas do host não permitem garantir a remoção completa da instância.

Referência do código-fonte: S2, S3, S6, S7, S8, S9.

Este guia é derivado do código-fonte, dos analisadores de CLI e dos contratos de medição fornecidos com Jitter Tools 1.3.0. Ele não certifica a precisão das medições de tempo em execução nem a compatibilidade com todas as distribuições. Os caminhos de arquivos de código-fonte abaixo são relativos ao arquivo de código-fonte.

Arquivo de código-fonte: jitter-tools-1.3.0.tgz
SHA-256: 39f803db80f8e598af67fa93171b0c0ead0c6350d2911bc9368b639cdee746ec