Sous-commande CLI bencher run
bencher run
est la sous-commande CLI la plus utilisée.
Elle est utilisée pour exécuter des benchmarks et en rapporter les résultats.
De ce fait, c’est l’une des sous-commandes les plus compliquées.
Cette page expliquera les options, flags, et arguments qui peuvent être passés à bencher run
.
Commande de Benchmark
Le premier argument de bencher run
est la commande de benchmark optionnelle. C’est la commande qui sera exécutée, invoquant votre harnais de benchmark. Elle peut également être définie en utilisant la variable d’environnement BENCHER_CMD
. Par défaut, cette commande est exécutée dans un shell, qui peut être configuré avec les options --shell
et --flag
. Son output est analysé par un adaptateur de harnais de benchmark, qui peut être défini en utilisant l’option --adapter
option. Toutefois, si le harnais de benchmark effectue une sortie vers un fichier, l’option --file
doit également être utilisée pour spécifier le chemin du fichier de sortie. Alternativement, pour suivre la taille du fichier de sortie (c’est-à-dire la taille binaire) au lieu de son contenu, utilisez l’option --file-size
pour spécifier le chemin du fichier de sortie.
Si vous préférez ne pas exécuter la commande dans un shell, vous pouvez utiliser l’indicateur --exec
ou simplement fournir des arguments supplémentaires à votre commande comme arguments supplémentaires à bencher run
.
Formulaire Shell :
Formulaire Exec :
La commande de benchmark peut être exécutée plusieurs fois en utilisant l’option --iter
, et ces résultats peuvent être consolidés en un seul résultat en utilisant l’option --fold
. Si l’une des itérations échoue, alors la commande entière est considérée comme ayant échoué, à moins que le drapeau --allow-failure
ne soit défini.
Si la commande de benchmark n’est pas spécifiée mais que l’option --file
l’est, alors bencher run
lira simplement à partir du chemin du fichier de sortie à la place. De même, si la commande de benchmark n’est pas spécifiée mais que l’option --file-size
l’est, alors bencher run
lira simplement la taille du fichier au chemin donné à la place. Si ni la commande de benchmark, ni l’option --file
, ni l’option --file-size
ne sont spécifiées, alors bencher run
lira depuis stdin
à la place. Cela vous permet de sauvegarder la sortie d’une autre commande dans un fichier ou de la rediriger vers bencher run
.
Options
--project <PROJECT>
Soit l’option --project
soit la variable d’environnement BENCHER_PROJECT
doit être définie sur le slug ou UUID d’un projet déjà existant.
Si les deux sont définis, l’option --project
a la priorité sur la variable d’environnement BENCHER_PROJECT
.
--token <TOKEN>
Soit l’option --token
soit la variable d’environnement BENCHER_API_TOKEN
doit être définie sur un token API valide.
Si les deux sont définis, l’option --token
a la priorité sur la variable d’environnement BENCHER_API_TOKEN
.
--branch <BRANCH>
--start-point <BRANCH>
--start-point-hash <HASH>
--start-point-max-versions <COUNT>
--start-point-clone-thresholds
--start-point-reset
Voir sélection de branche pour un aperçu complet.
--hash <HASH>
Optionnel : Un hash de commit SHA-1 de 40 caractères. Si deux rapports ont la même branche et hash, ils seront considérés comme provenant du même commit. Donc, ils auront le même numéro de version de branche.
Si non fourni, le CLI Bencher essaie de trouver le hash git actuel. Il commence par rechercher un dépôt git dans le répertoire de travail actuel. Si cela ne réussit pas, il continue vers son répertoire parent et réessaie jusqu’au répertoire racine. Si un dépôt git est trouvé, alors le hash git de la tête de la branche actuelle est utilisé.
--no-hash
Optionnel : Ne tentez pas de trouver un hash de commit git
.
Cette option est en conflit avec --hash
et annule son comportement par défaut qui consiste à rechercher un dépôt git
.
--testbed <TESTBED>
Optionnel : Soit l’option --testbed
soit la variable d’environnement BENCHER_TESTBED
peut être définie sur le slug ou UUID d’un banc d’essai déjà existant.
Si les deux sont définis, l’option --testbed
a la priorité sur la variable d’environnement BENCHER_TESTBED
.
Si aucun n’est défini, alors localhost
est utilisé comme banc d’essai par défaut.
--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
Voir seuils et alertes pour un aperçu complet.
--adapter <ADAPTER>
--average <AVERAGE>
--file <FILE>
--file-size <FILE>
Voir adaptateur de harnais benchmark pour un aperçu complet.
--iter <ITER>
Optionnel : Nombre d’itérations d’exécution. La valeur par défaut est 1
.
--fold <FOLD>
Optionnel : Replier plusieurs résultats en un seul résultat.
Nécessite : --iter
doit être défini.
Valeurs possibles :
min
: Valeur minimalemax
: Valeur maximalemean
: Moyenne des valeursmedian
: Médiane des valeurs
--backdate <DATETIME_SECONDS>
Optionnel : Antidater le rapport (secondes depuis l’époque). NOTE : Cela n’affectera pas l’ordre des rapports passés ! C’est utile lors de l’initialisation des données historiques dans un projet lors de l’importation en ordre chronologique.
--allow-failure
Optionnel : Autorise l’échec du test de benchmark.
--format <FORMAT>
Optionnel : Format pour le rapport final.
Le format par défaut est human
.
Valeurs possibles :
human
: Format lisible par l’humainjson
: Format JSONhtml
: Format HTML
--quiet
Optionnel : Mode silencieux, n’affiche que le Rapport final.
Utilisez l’option --format
pour changer le format de sortie.
--github-actions <GITHUB_TOKEN>
Optionnel : Définir le jeton d’authentification de l’API GitHub (par exemple --github-actions ${{ secrets.GITHUB_TOKEN }}
).
Lorsque cette option est définie et que bencher run
est utilisé dans GitHub Actions dans le cadre d’une demande de tirage,
alors les résultats seront ajoutés à la demande de tirage en tant que commentaire.
Sinon, les résultats seront ajoutés au commit en tant que commentaire de vérification GitHub.
La façon la plus pratique de le faire est la variable d’environnement GITHUB_TOKEN
de GitHub Actions.
🐰 Si vous exécutez à l’intérieur d’un conteneur Docker dans GitHub Action, vous devrez passer les variables d’environnement suivantes et monter le chemin spécifié par
GITHUB_EVENT_PATH
:
GITHUB_ACTIONS
GITHUB_EVENT_NAME
GITHUB_EVENT_PATH
--ci-only-thresholds
Optionnel : Publier les résultats sur CI uniquement si un Seuil existe pour la Branche, l’Environnement de test et la Mesure.
S’il n’existe aucun Seuil, alors rien ne sera publié.
Requis : --github-actions
--ci-only-on-alert
Optionnel : ne commencer à publier les résultats vers CI que si une alerte est générée.
Si une alerte est générée, alors tous les résultats de suivi seront également publiés même s’ils ne contiennent aucune alerte.
Requiert : --github-actions
--ci-id <ID>
Optionnel : ID personnalisé pour publier des résultats sur CI.
Par défaut, Bencher segmentera automatiquement les résultats par la combinaison de : Projet, Branche, Banc d’essai et Adaptateur.
Définir un ID personnalisé est utile lorsque Bencher est exécuté plusieurs fois dans le même flux de travail CI pour la même combinaison de Projet, Branche, Banc d’essai et Adaptateur.
Nécessite : --github-actions
--ci-number <NUMBER>
Optionnel : Numéro de problème pour publier les résultats sur CI.
Bencher fera de son mieux pour détecter le numéro de problème CI nécessaire pour publier les résultats.
Cependant, ce n’est pas toujours disponible dans des configurations complexes, comme l’utilisation de workflow_run
dans GitHub Actions.
Requiert : --github-actions
--shell <SHELL>
Optionnel : Chemin de la commande shell.
Par défaut, /bin/sh
sur les environnements de type Unix et cmd
sur Windows.
--flag <FLAG>
Optionnel : Drapeau de commande Shell.
Par défaut, -c
sur les environnements de type Unix et /C
sur Windows.
--exec
Optionnel: Exécutez la commande en tant qu’exécutable et non en tant que commande shell.
Par défaut si le nombre d’arguments pour bencher run
est supérieur à un.
--host <URL>
Optionnel : URL de l’hôte backend. Par défaut, Bench Cloud : https://api.bencher.dev
--attempts <ATTEMPTS>
Optionnel : Nombre maximal de tentatives de nouvelle requête.
Par défaut, 10
tentatives.
--retry-after <RETRY_AFTER_SECONDS>
Optionnel : Secondes initiales à attendre entre les tentatives (retrait exponentiel).
Par défaut, 1
seconde.
--dry-run
Optionnel : Effectuer une simulation. Cela ne stockera aucune donnée dans le backend. Ni un rapport, ni une branche (comme détaillé dans la sélection de branche), ni un banc d’essai ne seront créés.
--help
Facultatif : Afficher l’aide.
🐰 Bravo! Vous avez appris les bases de
bencher run
! 🎉