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.

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

Commande de benchmark

Le premier argument de bencher run est la commande de benchmark optionnelle. Il s’agit de la commande qui sera exécutée et qui lancera votre harness de benchmark. Elle peut aussi être définie via 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. Sa sortie est analysée par un adaptateur pour le harness de benchmark, qui peut être défini avec l’option --adapter. Cependant, si le harness de benchmark écrit dans 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 (par ex. la taille d’un binaire) plutôt que son contenu, utilisez l’option --file-size pour indiquer le chemin du fichier.

Si vous préférez que la commande ne soit pas exécutée dans un shell, vous pouvez utiliser l’option --exec ou simplement fournir des arguments supplémentaires à votre commande via bencher run.

Forme Shell :

bencher run "bencher mock"

Forme Exec :

bencher run bencher mock

La commande de benchmark peut être exécutée plusieurs fois en utilisant l’option --iter, et ces résultats peuvent être agrégés en un seul résultat avec l’option --fold. Si l’une des itérations échoue, la commande entière est considérée comme ayant échoué, sauf si le drapeau --allow-failure est activé.

Si la commande de benchmark n’est pas spécifiée mais que l’option --file l’est, alors bencher run lira simplement depuis le chemin du fichier de sortie indiqué. De même, si la commande n’est pas spécifiée mais que l’option --file-size l’est, bencher run lira simplement la taille du fichier au chemin donné. Les options --file et --file-size peuvent être spécifiées plusieurs fois pour lire plusieurs fichiers.

🐰 Conseils pour l’utilisation de l’option -⁠-file

L’option -⁠-file peut être utilisée pour lire des résultats de benchmark depuis un fichier. Vous pouvez spécifier l’option -⁠-file plusieurs fois pour lire plusieurs fichiers. Si vous spécifiez l’option -⁠-file plusieurs fois, alors chaque fichier sera considéré comme une itération distincte de la commande de benchmark. Lors de l’affichage, ces résultats seront présentés dans des tableaux séparés.

Si vous souhaitez combiner ces résultats en une seule itération, vous pouvez régler l’option -⁠-iter sur 1 et définir l’option -⁠-fold sur l’une des fonctions d’agrégation min, max ou median. Cela regroupera les résultats en une seule itération et les affichera dans un seul tableau. Ne réglez pas l’option -⁠-fold sur mean.

Si ni la commande de benchmark, ni l’option --file, ni l’option --file-size ne sont spécifiées, bencher run lira depuis stdin. Cela vous permet d’enregistrer la sortie d’une autre commande dans un fichier ou de la transmettre via un pipe à bencher run.

Options

--project <PROJECT>

Optionnel : soit l’option --project, soit la variable d’environnement BENCHER_PROJECT peuvent être définies sur le slug ou l’UUID d’un Projet. Une clé API de projet ne peut pas être utilisée pour créer un nouveau Projet ni pour revendiquer un Projet existant ; elle nécessite donc que --project/BENCHER_PROJECT soit défini sur un Projet existant. Si la valeur spécifiée est un slug et que le Projet n’existe pas encore, il sera créé pour vous lorsqu’une clé API utilisateur (l’option --key), l’option obsolète --token ou aucune information d’identification n’est utilisée. En revanche, si la valeur spécifiée est un UUID, le Projet doit déjà exister. Si les deux sont spécifiés, l’option --project a préséance sur la variable d’environnement BENCHER_PROJECT. Si aucun n’est spécifié, un slug de Projet sera généré pour vous en se basant sur :

1. Le nom du répertoire parent du dépôt git, s’il est disponible.
2. Le hachage court hexadécimal de 7 caractères du commit initial du dépôt git, s’il est disponible.
3. Une empreinte alphanumérique de 13 caractères de la machine locale, pour les systèmes d’exploitation pris en charge.

Par exemple, un slug de Projet généré pourrait ressembler à : project-abc4567-wxyz123456789

Lorsqu’un nouveau Projet est créé pour vous, que le slug soit spécifié ou généré, le Projet doit appartenir à une Organisation. Si l’utilisateur est authentifié avec une clé API utilisateur (l’option --key) ou l’option obsolète --token, le Projet est ajouté sous l’Organisation personnelle de cet utilisateur. Si l’utilisateur n’est pas authentifié, le Projet sera créé sous une nouvelle Organisation unclaimed. Cette Organisation peut ensuite être claimed depuis la page publique Perf du Projet ou en utilisant le slug du Projet tout en étant authentifié lors d’une invocation ultérieure de bencher run.

🐰 IMPORTANT : Si la variable d’environnement CI est définie sur true, alors vous devez soit spécifier le Projet, soit définir l’option --ci-on-the-fly.

--ci-on-the-fly

Optionnel : Autoriser la création de projets à la volée dans les environnements CI. Requis si la variable d’environnement CI est définie sur true. Tant GitHub Actions que GitLab CI/CD définissent cette variable par défaut.

En conflit avec l’option --project.

--key <KEY>

Optionnel : Soit l’option --key, soit la variable d’environnement BENCHER_API_KEY peut être définie avec une clé API valide. Si les deux sont spécifiées, l’option --key a la priorité sur la variable d’environnement BENCHER_API_KEY. Il existe deux types de clés API :

• Une clé API utilisateur (bencher_user_*) est limitée à un utilisateur et s’authentifie en tant que cet utilisateur. Cliquez ici pour créer une clé API utilisateur.
• Une clé API de projet (bencher_run_*) est limitée à un seul projet et ne peut être utilisée que pour bencher run et d’autres commandes non destructives. Une clé API de projet ne peut pas être utilisée pour créer un nouveau Projet ni pour revendiquer un Projet existant ; elle nécessite donc que l’option --project soit définie sur un Projet existant.

Si ni l’option --key ni l’option obsolète --token ne sont spécifiées, le Projet doit être non réclamé. En conflit avec l’option obsolète --token.

--token <TOKEN>

🐰 OBSOLÈTE : Les jetons API sont obsolètes au profit des clés API. De nouveaux jetons API ne peuvent plus être créés ; les jetons API existants continuent de fonctionner. Utilisez plutôt l’option --key.

Optionnel : Soit l’option --token, soit la variable d’environnement BENCHER_API_TOKEN peut être configurée avec un jeton API valide. Si les deux sont spécifiés, l’option --token prévaut sur la variable d’environnement BENCHER_API_TOKEN. Si ni l’option --token ni l’option --key ne sont spécifiées, le Projet doit être non réclamé. C’est-à-dire que si vous avez déjà réclamé un Projet, vous devez fournir une clé API ou un jeton API valide. En conflit avec l’option --key.

--image <IMAGE>

--entrypoint <ENTRYPOINT>

--env <KEY=VALUE>

--job-timeout <SECONDS>

--job-poll-interval <SECONDS>

--detach

Voir images pour matériel dédié pour un aperçu complet.

--branch <BRANCH>

--hash <HASH>

--start-point <BRANCH>

--start-point-hash <HASH>

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

--start-point-clone-thresholds

--start-point-reset

Voir branches pour un aperçu complet.

--testbed <TESTBED>

--spec <SPEC>

--spec-reset

Voir bancs d’essai & specs pour un aperçu complet.

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

Voir seuils et alertes pour un aperçu complet.

--adapter <ADAPTER>

--average <AVERAGE>

--file <FILE>

--build-time

--file-size <FILE>

Voir adaptateur de harnais benchmark pour un aperçu complet.

--iter <COUNT>

Optionnel : Nombre d’itérations d’exécution. La valeur par défaut est 1.

--fold <AGGREGATE_FUNCTION>

Optionnel : Replier plusieurs résultats en un seul résultat.
Nécessite : --iter doit être défini.
Valeurs possibles :

• min : Valeur minimale
• max : Valeur maximale
• mean : Moyenne des valeurs
• median : Médiane des valeurs

--backdate <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’humain
• json : Format JSON
• html : 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éfinissez le jeton d’authentification de l’API GitHub. La manière la plus pratique de le faire est d’utiliser la variable d’environnement GITHUB_TOKEN des GitHub Actions (c’est-à-dire --github-actions ${{ secrets.GITHUB_TOKEN }}). Lorsque cette option est définie et que bencher run est utilisé dans les GitHub Actions, les résultats seront alors ajoutés au commit de tête en tant que vérification GitHub nommée Bencher Report (ou Bencher Report (<ID>) si --ci-id est défini). La vérification GitHub échouera si une Alerte est générée, elle peut donc être utilisée comme vérification de statut requise dans la protection de branche. Cela nécessite que le jeton ait le scope checks avec les permissions write. Si la vérification GitHub ne peut pas être créée, bencher run enregistrera alors un avertissement et continuera. Lorsque bencher run est utilisé dans le cadre d’une pull request, les résultats seront également ajoutés à la pull request en tant que commentaire. Cela nécessite que le jeton ait le scope pull-requests avec les permissions write. Les résultats seront également toujours ajoutés au résumé du travail.

🐰 Si vous exécutez à l’intérieur d’un conteneur Docker dans une action GitHub, vous devrez transmettre les variables d’environnement suivantes et monter le chemin spécifié par GITHUB_EVENT_PATH :

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

--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 aucun commentaire de pull request ne sera publié. Cela ne s’applique qu’aux commentaires de pull request. La vérification GitHub est toujours créée. 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. Cela ne s’applique qu’aux commentaires de pull request. La vérification GitHub est toujours créée. 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.
L’ID est également ajouté au nom de la vérification GitHub (c’est-à-dire Bencher Report (<ID>)),
de sorte que chaque invocation obtient un nom stable qui peut être utilisé comme vérification de statut requise distincte.
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

--ci-public-links

Optionnel : Tous les liens doivent pointer vers des URLs publiques ne nécessitant pas de connexion. 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

--insecure-host

Optionnel : Autoriser la connexion non sécurisée au serveur API Bencher.

Ce flag est utile lorsque vous vous connectez à une instance Bencher auto-hébergée avec un certificat auto-signé ou un certificat qui n’est pas inclus dans le magasin de certificats du système. Il est uniquement applicable aux connexions HTTPS, car les connexions HTTP sont intrinsèquement non sécurisées.

AVERTISSEMENT : Utilisez --insecure-host uniquement dans un réseau sécurisé avec des sources vérifiées, car il contourne la vérification SSL et pourrait vous exposer à des attaques de type homme du milieu.

--native-tls

Optionnel : Charger des certificats TLS à partir du magasin de certificats natif de la plateforme.

Par défaut, bencher charge les certificats à partir de la caisse webpki-roots intégrée. Les webpki-roots sont un ensemble fiable de racines de confiance de Mozilla, et les inclure dans bencher améliore la portabilité et les performances. C’est particulièrement vrai sur macOS, où la lecture du magasin de confiance système entraîne un délai important.

Cependant, dans certains cas, vous pouvez vouloir utiliser le magasin de certificats natif de la plateforme, surtout si vous dépendez d’une racine de confiance d’entreprise incluse dans votre magasin de certificats système pour un proxy obligatoire ou des connexions auto-signées Bencher Self-Hosted.

--timeout <SECONDS>

Optionnel : Délai d’expiration de la requête en secondes. Par défaut, 15 secondes.

--attempts <COUNT>

Optionnel : Nombre maximal de tentatives de nouvelle requête. Par défaut, 35 tentatives.

--retry-after <SECONDS>

Optionnel : Secondes initiales à attendre entre les tentatives (retrait exponentiel). Par défaut, 1 seconde.

--max-retry-after <SECONDS>

Optionnel : Secondes maximales à attendre entre les tentatives (plafonne le retrait exponentiel). Par défaut, 30 secondes.

--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 les branches), ni un banc d’essai ne seront créés.

--help

Facultatif : Afficher l’aide.

🐰 Bravo! Vous avez appris les bases de bencher run ! 🎉

Continuer: Images sur matériel dédié ➡