Subcomando bencher run CLI

bencher run é o subcomando CLI mais popular. É usado para executar benchmarks e reportar os resultados. Por isso, é um dos subcomandos mais complicados. Esta página vai explicar as opções, flags e argumentos que podem ser passados para bencher run.

bencher run [OPTIONS] [COMMAND] [ARGUMENTS...]

Comando de Benchmark

O primeiro argumento de bencher run é o comando de benchmark opcional. Este é o comando que será executado, invocando seu harness de benchmark. Também pode ser definido usando a variável de ambiente BENCHER_CMD. Por padrão este comando é executado em um shell, que pode ser configurado com as opções --shell e --flag. Sua saída é analisada por um adaptador de harness de benchmark, que pode ser definido usando a opção --adapter. No entanto, se o harness de benchmark gravar a saída em um arquivo, a opção --file também deve ser usada para especificar o caminho do arquivo de saída. Como alternativa, para acompanhar o tamanho do arquivo de saída (por exemplo, o tamanho do binário) em vez do seu conteúdo, use a opção --file-size para especificar o caminho do arquivo de saída.

Se preferir que o comando não seja executado em um shell, você pode usar a flag --exec ou simplesmente fornecer argumentos adicionais ao seu comando como argumentos adicionais para bencher run.

Shell Form:

bencher run "bencher mock"

Exec Form:

bencher run bencher mock

O comando de benchmark pode ser executado várias vezes usando a opção --iter, e esses resultados podem ser combinados em um único resultado usando a opção --fold. Se qualquer uma das iterações falhar, então o comando inteiro será considerado como tendo falhado, a menos que a flag --allow-failure esteja definida.

Se o comando de benchmark não for especificado, mas a opção --file for, então o bencher run apenas lerá do caminho do arquivo de saída. Da mesma forma, se o comando de benchmark não for especificado, mas a opção --file-size for, então o bencher run apenas lerá o tamanho do arquivo no caminho fornecido. As opções --file e --file-size podem ser especificadas múltiplas vezes para ler de vários arquivos.

🐰 Dicas para usar a opção -⁠-file

A opção -⁠-file pode ser usada para ler resultados de benchmark de um arquivo. Você pode especificar a opção -⁠-file várias vezes para ler de vários arquivos. Se você especificar a opção -⁠-file várias vezes, cada arquivo será considerado uma iteração separada do comando de benchmark. Quando exibidos, esses resultados serão mostrados em tabelas separadas.

Se você desejar combinar esses resultados em uma única iteração, então pode definir a opção -⁠-iter para 1 e definir a opção -⁠-fold para uma das funções agregadas min, max ou median. Isso irá consolidar os resultados em uma única iteração e exibi-los em uma única tabela. Do not set the -⁠-fold option to mean.

Se nem o comando de benchmark, nem a opção --file, nem a opção --file-size forem especificados, então o bencher run lerá do stdin. Isso permite que você salve a saída de outro comando em um arquivo ou a passe via pipe para o bencher run.

Options

--project <PROJECT>

Opcional: A opção --project ou a variável de ambiente BENCHER_PROJECT podem ser definidas com o slug ou UUID de um Projeto. Se o valor especificado for um slug e o Projeto ainda não existir, ele será criado para você. Entretanto, se o valor especificado for um UUID, o Projeto já deve existir. Se ambos estiverem especificados, a opção --project tem precedência sobre a variável de ambiente BENCHER_PROJECT. Se nenhum for especificado, um slug de Projeto será gerado para você com base em:

1. O nome do diretório pai do repositório git, se estiver disponível.
2. O hash curto hexadecimal de 7 dígitos do commit inicial do repositório git, se estiver disponível.
3. Uma impressão digital alfanumérica de 13 caracteres da máquina local, para sistemas operacionais suportados.

Por exemplo, um slug de Projeto gerado pode ser parecido com: project-abc4567-wxyz123456789

Quando um novo Projeto é criado para você, seja o slug especificado ou gerado, o Projeto precisa pertencer a uma Organização. Se o usuário estiver autenticado, o Projeto é adicionado à Organização pessoal desse usuário. Se o usuário não estiver autenticado, o Projeto será criado sob uma nova Organização unclaimed. Essa Organização pode então ser claimed a partir da Perf Page pública do Projeto ou usando o slug do Projeto enquanto autenticado em uma invocação subsequente de bencher run.

🐰 IMPORTANTE: Se a variável de ambiente CI estiver definida como true, então você precisa ou especificar o Projeto ou definir a flag --ci-on-the-fly.

--ci-on-the-fly

Opcional: Permite a criação de Projetos On-the-Fly em ambientes de CI. Necessário se a variável de ambiente CI estiver configurada como true. Tanto o GitHub Actions quanto o GitLab CI/CD definem essa variável por padrão.

Conflita com a opção --project.

--token <TOKEN>

Opcional: A opção --token ou a variável de ambiente BENCHER_API_TOKEN podem ser configuradas com um token de API válido. Se ambos forem especificados, a opção --token prevalece sobre a variável de ambiente BENCHER_API_TOKEN. Se nenhum dos dois for especificado, o Projeto deve estar não reivindicado. Ou seja, se você já reivindicou um Projeto, deve fornecer um token de API válido. Clique aqui para criar um token de API.

--branch <BRANCH>

--hash <HASH>

--start-point <BRANCH>

--start-point-hash <HASH>

--start-point-max-versions <COUNT>

--start-point-clone-thresholds

--start-point-reset

Veja seleção de branch para uma visão completa.

--testbed <TESTBED>

Opcional: Ou a opção --testbed ou a variável de ambiente BENCHER_TESTBED pode ser definida como o nome, slug ou UUID para um Testbed. Se o valor especificado for um nome ou slug e o Testbed ainda não existir, ele será criado para você. No entanto, se o valor especificado for um UUID, então o Testbed já deve existir. Se ambos forem especificados, a opção --testbed tem precedência sobre a variável de ambiente BENCHER_TESTBED. Se nenhum for especificado, então Linux, macOS ou Windows é usado, com base no sistema operacional do host. Se o CLI bencher foi compilado para um sistema operacional diferente, então localhost é usado como o Testbed padrão.

--threshold-measure <MEASURE>

--threshold-test <TEST>

--threshold-min-sample-size <SAMPLE_SIZE>

--threshold-max-sample-size <SAMPLE_SIZE>

--threshold-window <WINDOW>

--threshold-lower-boundary <BOUNDARY>

--threshold-upper-boundary <BOUNDARY>

--thresholds-reset

--err

Veja limiares e alertas para uma visão geral completa.

--adapter <ADAPTER>

--average <AVERAGE>

--file <FILE>

--build-time

--file-size <FILE>

Veja adaptador de benchmark para uma visão geral completa.

--iter <COUNT>

Opcional: Número de iterações de execução. O padrão é 1.

--fold <AGGREGATE_FUNCTION>

Opcional: Combine vários resultados em um único resultado.
Requer: --iter definido.
Valores possíveis:

• min: Valor mínimo
• max: Valor máximo
• mean: Média dos valores
• median: Mediana dos valores

--backdate <SECONDS>

Opcional: Retrodata o relatório (segundos desde a época). NOTA: Isso não afetará a ordem dos relatórios passados! Isso é útil ao inicialmente inserir dados históricos em um projeto em ordem cronológica.

--allow-failure

Opcional: Permita falha no teste de benchmark.

--format <FORMAT>

Opcional: Formato para o Relatório final. O padrão é human.

Valores possíveis:

• human: Formato legível para humanos
• json: Formato JSON
• html: Formato HTML

--quiet

Opcional: Modo silencioso, apenas exibe o relatório final. Use a opção --format para alterar o formato de saída.

--github-actions <GITHUB_TOKEN>

Opcional: Defina o token de autenticação da API do GitHub. A maneira mais conveniente de fazer isso é usando a variável de ambiente GITHUB_TOKEN do GitHub Actions (ou seja, --github-actions ${{ secrets.GITHUB_TOKEN }}). Quando esta opção é definida e bencher run é usado no GitHub Actions como parte de um pull request, os resultados serão adicionados ao pull request como um comentário. Isso requer que o token tenha o escopo de pull-requests com permissões de write. Caso contrário, os resultados serão adicionados ao commit como uma Verificação do GitHub. Isso requer que o token tenha o escopo de checks com permissões de write. Em ambos os casos, os resultados também serão adicionados ao resumo do trabalho.

🐰 Se você estiver executando dentro de um contêiner Docker no GitHub Action, precisará passar as seguintes variáveis de ambiente e montar o caminho especificado por GITHUB_EVENT_PATH:

• GITHUB_ACTIONS
• GITHUB_EVENT_NAME
• GITHUB_EVENT_PATH
• GITHUB_SHA
• GITHUB_API_URL (GitHub Enterprise Server apenas)

--ci-only-thresholds

Opcional: Somente publique resultados no CI se um Limite existir para o Branch, Testbed e Medida. Se não existirem Limites, nada será publicado. Requer: --github-actions

--ci-only-on-alert

Opcional: Comece a enviar resultados para CI apenas se um Alerta for gerado. Se um Alerta for gerado, todos os resultados subsequentes também serão enviados, mesmo que não contenham nenhum Alerta. Requer: --github-actions

--ci-id <ID>

Opcional: ID personalizado para publicar resultados no CI.
Por padrão, o Bencher irá automaticamente segmentar os resultados pela combinação de: Projeto, Branch, Ambiente de Teste e Adaptador.
Definir um ID personalizado é útil quando o Bencher está sendo executado várias vezes no mesmo fluxo de trabalho de CI para a mesma combinação de Projeto, Branch, Ambiente de Teste e Adaptador.
Requer: --github-actions

--ci-number <NUMBER>

Opcional: Número da issue para postar resultados no CI. O Bencher fará o possível para detectar o número da issue de CI necessário para postar resultados. No entanto, isso nem sempre está disponível em configurações complexas, como ao usar workflow_run no GitHub Actions. Requer: --github-actions

--shell <SHELL>

Opcional: Caminho para o comando do shell.
O padrão é /bin/sh em ambientes Unix-like e cmd no Windows.

--flag <FLAG>

Opcional: Flag de comando no shell. Padrão é -c em ambientes tipo Unix e /C no Windows.

--exec

Opcional: Execute o comando como um executável, não como um comando de shell. Padrão se o número de argumentos para bencher run for maior que um.

--host <URL>

Opcional: URL do host do backend. Padrão para Bench Cloud: https://api.bencher.dev

--insecure-host

Opcional: Permitir conexão insegura ao servidor da API Bencher.

Essa flag é útil quando você está se conectando a uma instância self-hosted do Bencher com um certificado autoassinado ou um certificado que não está incluído no armazenamento de certificados do sistema. É aplicável apenas para conexões HTTPS, já que conexões HTTP são inerentemente inseguras.

AVISO: Use --insecure-host apenas em uma rede segura com fontes verificadas, pois isso ignora a verificação SSL e pode expor você a ataques de intermediário.

--native-tls

Opcional: Carregar certificados TLS do armazenamento de certificados nativo da plataforma.

Por padrão, o bencher carrega certificados do webpki-roots crate incorporado. Os webpki-roots são um conjunto confiável de raízes de confiança da Mozilla, e incluí-los no bencher melhora a portabilidade e o desempenho. Isso é especialmente verdadeiro no macOS, onde a leitura do armazenamento de confiança do sistema gera um atraso significativo.

No entanto, em alguns casos, você pode querer usar o armazenamento de certificados nativo da plataforma, especialmente se estiver contando com uma raiz de confiança corporativa incluída no armazenamento de certificados do seu sistema para um proxy obrigatório ou conexões autoassinadas do Bencher Self-Hosted.

--timeout <SECONDS>

Opcional: Timeout da requisição em segundos. O padrão é 15 segundos.

--attempts <COUNT>

Opcional: Máximo de tentativas de novas tentativas de solicitação. O padrão é 10 tentativas.

--retry-after <SECONDS>

Opcional: Segundos iniciais para aguardar entre as tentativas (recuo exponencial). O padrão é 1 segundo.

--dry-run

Opcional: Execute uma simulação. Isso não armazenará nenhum dado no backend. Nem um Relatório, um Branch (conforme detalhado em seleção de branch), nem um Testbed será criado.

--help

Opcional: Imprime a ajuda.

🐰 Parabéns! Você aprendeu os fundamentos de bencher run! 🎉

Continuar: Seleção de Branch com bencher run ➡