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. Uma chave de API de projeto não pode ser usada para criar um novo Projeto nem para reivindicar um Projeto existente, portanto requer que --project/BENCHER_PROJECT esteja definida como um Projeto existente. Se o valor especificado for um slug e o Projeto ainda não existir, ele será criado para você quando uma chave de API de usuário (a opção --key), a opção obsoleta --token ou nenhuma credencial for usada. 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 com uma chave de API de usuário (a opção --key) ou a opção obsoleta --token, 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 do link Claim this project na saída do bencher run 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.

--key <KEY>

Opcional: A opção --key ou a variável de ambiente BENCHER_API_KEY pode ser definida com uma chave de API válida. Se ambas forem especificadas, a opção --key tem precedência sobre a variável de ambiente BENCHER_API_KEY. Existem dois tipos de chave de API:

• Uma chave de API de usuário (bencher_user_*) é limitada a um usuário e autentica como esse usuário. Clique aqui para criar uma chave de API de usuário.
• Uma chave de API de projeto (bencher_run_*) é limitada a um único projeto e só pode ser usada para bencher run e outros comandos não destrutivos. Uma chave de API de projeto não pode ser usada para criar um novo Projeto nem para reivindicar um Projeto existente, portanto requer que a opção --project esteja definida como um Projeto existente.

Se nem a opção --key nem a opção obsoleta --token forem especificadas, o Projeto deve estar não reivindicado. Conflita com a opção obsoleta --token.

--token <TOKEN>

🐰 OBSOLETO: Os tokens de API estão obsoletos em favor das chaves de API. Novos tokens de API não podem mais ser criados; os tokens de API existentes continuam funcionando. Use a opção --key em vez disso.

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 nem a opção --token nem a opção --key forem especificadas, o Projeto deve estar não reivindicado. Ou seja, se você já reivindicou um Projeto, deve fornecer uma chave de API ou um token de API válidos. Conflita com a opção --key.

--image <IMAGE>

--entrypoint <ENTRYPOINT>

--env <KEY=VALUE>

--job-timeout <SECONDS>

--job-poll-interval <SECONDS>

--detach

--callback-url <URL>

--callback-header <NAME: VALUE>

--callback-body <JSON>

--job <UUID>

Veja imagens para hardware dedicado para uma visão completa.

--branch <BRANCH>

--hash <HASH>

--start-point <BRANCH>

--start-point-hash <HASH>

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

--start-point-clone-thresholds

--start-point-reset

--start-point-idempotency-key <KEY>

Veja branches para uma visão completa.

--testbed <TESTBED>

--spec <SPEC>

--spec-reset

Veja testbeds & specs para uma visão completa.

--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

--error-on-alert

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 }}).

Os resultados serão adicionados ao commit head como uma Verificação do GitHub chamada:

1. Bencher Report (<ID>) se a opção --ci-id estiver definida
2. Bencher Report (<NOME DO PROJETO>) para Projetos existentes
3. Bencher Report para Projetos --ci-on-the-fly (enquanto estiver em andamento)

Isso requer que o token tenha o escopo de checks com permissões de write. Se a Verificação do GitHub não puder ser criada, o bencher run registrará um aviso e continuará.

Quando bencher run é usado como parte de um pull request, os resultados também serão adicionados ao pull request como um comentário. Todos os trabalhos de um Projeto no pull request compartilham este único comentário, com uma linha de Relatório para cada trabalho. Isso requer que o token tenha o escopo de pull-requests com permissões de write. Os resultados também serão sempre adicionados ao resumo do trabalho. Com a flag --detach, a execução desanexada não publica nenhum comentário nem escreve o resumo do trabalho, e a conexão com --job conclui a Verificação do GitHub que ela iniciou (veja a opção --ci-callback-token).

Com duas ou mais linhas, o comentário mostra uma tabela de resumo de cada Relatório com seu Ambiente de Teste, Adaptador e status (Pending, o número de Alertas, No Alerts ou Failed). As linhas estão na ordem em que os Relatórios começaram, numeradas a partir de 1, como o Console lista os Relatórios de uma execução. O rótulo de cada linha é o seu número, seguido do valor da opção --ci-id entre parênteses, se ela estiver definida (ex: 2 (microbench)). O rótulo leva ao Relatório, o Ambiente de Teste à sua página no Console e o Adaptador à sua parte da documentação de Adaptadores. Quando os trabalhos usam mais de um Branch, a tabela de resumo ganha uma coluna para o Branch. Em seguida, uma tabela reúne os Alertas de todos os Relatórios, com uma coluna para o Relatório. Depois, os resultados de cada Relatório seguem em um bloco recolhível (ex: Report 2 (microbench): 14 benchmarks, 2 alerts), que fica aberto quando o Relatório tem Alertas. Cada trabalho mantém sua própria Verificação do GitHub e seu próprio resumo do trabalho, então os nomes das Verificações do GitHub e as verificações de status obrigatórias não mudam. Um trabalho cujo commit não é mais o commit head do pull request deixa o comentário como está. Se o token não puder ler o pull request, então o trabalho registrará um aviso e escreverá o comentário sem verificar seu commit head.

Um comentário do GitHub tem um limite de tamanho, então o comentário usa a primeira destas formas que couber:

1. Todas as partes acima
2. Sem os blocos recolhíveis, com um aviso de que o comentário está truncado
3. Todas as linhas de resumo e o número total de Alertas, sem as linhas de Alertas
4. Como último recurso, as primeiras linhas de resumo, e depois and N more reports para o restante

Com uma única linha, o comentário é o mesmo de antes e, se for grande demais, leva ao Relatório completo.

Para encontrar os outros trabalhos, o bencher run lista as Verificações do GitHub do commit head, o que o escopo de checks com permissões de write acima já permite. Se um trabalho não conseguir criar ou concluir sua Verificação do GitHub, não conseguir identificar qual GitHub App é dona dela, ou não conseguir listar as Verificações do GitHub, então ele publicará um comentário apenas com seus próprios resultados. Os comentários do Projeto de uma versão anterior do bencher run são substituídos: o primeiro trabalho a escrever o comentário compartilhado atualiza o mais antigo deles e exclui os demais. Ao escrever o comentário compartilhado, um trabalho só atualiza ou exclui comentários publicados pela GitHub App dona da sua Verificação do GitHub, o que com o GITHUB_TOKEN é o bot github-actions.

🐰 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, nenhum comentário no pull request será publicado. Todos os trabalhos de um Projeto em um pull request compartilham um único comentário, então o comentário é publicado se existir um Limite para qualquer um de seus Relatórios. Isso se aplica apenas aos comentários no pull request. A Verificação do GitHub é sempre criada. 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. Todos os trabalhos de um Projeto em um pull request compartilham um único comentário, então o comentário é criado assim que qualquer um de seus Relatórios tiver um Alerta, e depois cada trabalho o atualiza. Isso se aplica apenas aos comentários no pull request. A Verificação do GitHub é sempre criada. Requer: --github-actions

--ci-id <ID>

Opcional: ID personalizado para publicar resultados no CI.
Todos os trabalhos de um Projeto em um pull request compartilham um único comentário, com uma linha de Relatório para cada trabalho.
Com um ID, o rótulo da linha é o seu número e o ID (ex: 2 (microbench)).
Até que o Relatório do trabalho exista, sua linha mostra apenas o ID e nenhum número (ex: (microbench)), como Pending enquanto o trabalho é executado, e vem depois das linhas numeradas.
Sem um ID, o rótulo é apenas o número, e a linha aparece assim que o Relatório do trabalho existe.
Por padrão, os trabalhos compartilham uma linha quando têm a mesma combinação de: Branch, Ambiente de Teste e Adaptador,
junto com --build-time e --file-size, se definidos.
Definir um ID personalizado é útil quando o Bencher está sendo executado várias vezes no mesmo commit para a mesma combinação de Projeto, Branch, Ambiente de Teste e Adaptador,
para que cada execução tenha sua própria linha.
Por exemplo, uma execução de push e uma execução de pull_request no mesmo branch compartilham o commit head,
então dê a cada execução seu próprio ID, ou não use --github-actions na execução de push.
Caso contrário, as execuções compartilham uma linha, que mostra apenas uma delas, e uma execução mais antiga não escreve nada assim que uma execução mais recente ocupa a linha.
O ID também é usado no lugar do nome do Projeto no nome da Verificação do GitHub (ou seja, Bencher Report (<ID>)),
de modo que cada invocação recebe um nome estável que pode ser usado como uma verificação de status obrigatória separada.
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

--ci-public-links

Opcional: Todos os links devem ser URLs públicas que não requerem login. Requer: --github-actions

--ci-callback-token <TOKEN>

Opcional: Define o token de autenticação usado pelo callback de um Job em hardware dedicado desanexado.

Ao usar a flag --detach e a opção --github-actions, o servidor da API do Bencher dispara um workflow de repository_dispatch quando o Job termina. Para um Projeto com um repositório vinculado, o Bencher cria o token, então esta opção não é necessária. Para usar seu próprio token em vez disso, defina esta opção com um token de acesso pessoal de granularidade fina para o repositório com pelo menos a permissão contents: write. O Bencher então envia o evento repository_dispatch com este token, quer o Projeto tenha um repositório vinculado ou não. A CLI exige esta opção no GitHub Enterprise Server e com um servidor da API do Bencher anterior a v0.6.16. Sem ela, uma execução desanexada de um Projeto claimed é recusada se o servidor não tiver um aplicativo GitHub, se o Projeto não tiver um repositório vinculado ou se o seu repositório vinculado estiver desconectado. Veja Pull Requests em hardware dedicado no GitHub Actions para uma visão geral completa.

🐰 Você não pode simplesmente usar o GITHUB_TOKEN aqui, pois ele expira assim que o workflow atual termina!

--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 é 35 tentativas.

--retry-after <SECONDS>

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

--max-retry-after <SECONDS>

Opcional: Segundos máximos para aguardar entre as tentativas (limita o recuo exponencial). O padrão é 30 segundos.

--dry-run

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

--help

Opcional: Imprime a ajuda.

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

Continuar: Imagens em hardware dedicado ➡