bencher run CLI-Unterbefehl

bencher run ist das beliebteste CLI-Unterkommando. Es wird verwendet, um Benchmarks auszuführen und die Ergebnisse zu berichten. Daher ist es eines der kompliziertesten Unterkommandos. Diese Seite wird die Optionen, Flags und Argumente erklären, die bencher run übergeben werden können.

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

Benchmark-Befehl

Das erste Argument von bencher run ist der optionale Benchmark-Befehl. Dies ist der Befehl, der ausgeführt wird und Ihr Benchmark-Harness aufruft. Er kann auch über die Umgebungsvariable BENCHER_CMD gesetzt werden. Standardmäßig wird dieser Befehl in einer Shell ausgeführt, die mit den Optionen --shell und --flag konfiguriert werden kann. Seine Ausgabe wird von einem Benchmark-Harness-Adapter geparst, der mit der Option --adapter gesetzt werden kann. Wenn das Benchmark-Harness jedoch in eine Datei schreibt, muss außerdem die Option --file verwendet werden, um den Pfad der Ausgabedatei anzugeben. Alternativ, um die Größe der Ausgabedatei (z. B. Binärgröße) statt ihres Inhalts zu erfassen, verwenden Sie die Option --file-size, um den Pfad der Ausgabedatei anzugeben.

Wenn Sie nicht möchten, dass der Befehl in einer Shell ausgeführt wird, können Sie das Flag --exec verwenden oder zusätzliche Argumente für Ihren Befehl einfach als zusätzliche Argumente an bencher run übergeben.

Shell-Form:

bencher run "bencher mock"

Exec-Form:

bencher run bencher mock

Der Benchmark-Befehl kann mehrfach mit der Option --iter ausgeführt werden, und diese Ergebnisse können mit der Option --fold zu einem einzigen Ergebnis zusammengefasst werden. Wenn eine der Iterationen fehlschlägt, gilt der gesamte Befehl als fehlgeschlagen, es sei denn, das Flag --allow-failure ist gesetzt.

Wenn der Benchmark-Befehl nicht angegeben ist, aber die Option --file, dann wird bencher run stattdessen einfach aus dem angegebenen Ausgabedateipfad lesen. Ähnlich, wenn der Benchmark-Befehl nicht angegeben ist, aber die Option --file-size, dann liest bencher run stattdessen nur die Größe der Datei am angegebenen Pfad. Beide Optionen --file und --file-size können mehrfach angegeben werden, um aus mehreren Dateien zu lesen.

🐰 Tipps zur Verwendung der -⁠-file Option

Die -⁠-file-Option kann verwendet werden, um Benchmark-Ergebnisse aus einer Datei zu lesen. Sie können die -⁠-file-Option mehrfach angeben, um aus mehreren Dateien zu lesen. Wenn Sie die -⁠-file-Option mehrfach angeben, wird jede Datei als separate iteration des Benchmark-Befehls betrachtet. Beim Anzeigen werden diese Ergebnisse in separaten Tabellen dargestellt.

Wenn Sie diese Ergebnisse zu einer einzigen iteration zusammenfassen möchten, können Sie die Option -⁠-iter auf 1 setzen und die Option -⁠-fold auf eine der Aggregatfunktionen min, max oder median setzen. Dadurch werden die Ergebnisse zu einer einzigen iteration zusammengefasst und in einer einzigen Tabelle angezeigt. Setzen Sie die Option -⁠-fold nicht auf mean.

Wenn weder der Benchmark-Befehl noch die Option --file noch die Option --file-size angegeben sind, dann liest bencher run stattdessen von stdin. Das ermöglicht es Ihnen, die Ausgabe eines anderen Befehls in eine Datei zu speichern oder sie in bencher run zu pipen.

Options

--project <PROJECT>

Optional: Entweder die Option --project oder die Umgebungsvariable BENCHER_PROJECT kann auf den Slug oder die UUID für ein Project gesetzt werden. Ein Projekt-API-Schlüssel kann nicht verwendet werden, um ein neues Project zu erstellen oder ein bestehendes Project zu beanspruchen, daher muss --project/BENCHER_PROJECT auf ein bestehendes Project gesetzt sein. Wenn der angegebene Wert ein Slug ist und das Project noch nicht existiert, wird es für Sie erstellt, sofern ein Benutzer-API-Schlüssel (die Option --key), die veraltete Option --token oder gar keine Anmeldedaten verwendet werden. Wenn der angegebene Wert jedoch eine UUID ist, muss das Project bereits existieren. Wenn beide angegeben sind, hat die Option --project Vorrang vor der Umgebungsvariable BENCHER_PROJECT. Wenn keiner angegeben ist, wird ein Projekt-Slug für Sie generiert, basierend auf:

1. Dem Namen des übergeordneten Verzeichnisses des git-Repositories, falls verfügbar.
2. Dem 7-stelligen hexadezimalen Kurz-Hash des initialen Commits des git-Repositories, falls verfügbar.
3. Einem 13-stelligen alphanumerischen Fingerabdruck der lokalen Maschine, für unterstützte Betriebssysteme.

Zum Beispiel könnte ein erzeugter Projekt-Slug so aussehen: project-abc4567-wxyz123456789

Wenn ein neues Project für Sie erstellt wird, egal ob der Slug angegeben oder generiert wurde, muss das Project zu einer Organization gehören. Wenn der Benutzer mit einem Benutzer-API-Schlüssel (der Option --key) oder der veralteten Option --token authentifiziert ist, wird das Project unter der persönlichen Organization dieses Benutzers hinzugefügt. Wenn der Benutzer nicht authentifiziert ist, wird das Project unter einer neuen unclaimed Organization erstellt. Diese Organization kann dann per claimed über den Link Claim this project in der Ausgabe von bencher run beansprucht werden oder indem man den Project-Slug bei Authentifizierung in einem späteren Aufruf von bencher run verwendet.

🐰 WICHTIG: Wenn die Umgebungsvariable CI auf true gesetzt ist, müssen Sie entweder das Project angeben oder das --ci-on-the-fly flag setzen.

--ci-on-the-fly

Optional: Erlaubt die Erstellung von Projekten unterwegs in CI-Umgebungen. Erforderlich, wenn die CI Umgebungsvariable auf true gesetzt ist. Sowohl GitHub Actions als auch GitLab CI/CD setzen diese Variable standardmäßig.

Konflikte mit der Option --project.

--key <KEY>

Optional: Entweder die Option --key oder die Umgebungsvariable BENCHER_API_KEY kann auf einen gültigen API-Schlüssel gesetzt werden. Wenn beide angegeben sind, hat die Option --key Vorrang vor der Umgebungsvariable BENCHER_API_KEY. Es gibt zwei Arten von API-Schlüsseln:

• Ein Benutzer-API-Schlüssel (bencher_user_*) ist auf einen Benutzer beschränkt und authentifiziert sich als dieser Benutzer. Klicken Sie hier, um einen Benutzer-API-Schlüssel zu erstellen.
• Ein Projekt-API-Schlüssel (bencher_run_*) ist auf ein einzelnes Projekt beschränkt und kann nur für bencher run und andere nicht-destruktive Befehle verwendet werden. Ein Projekt-API-Schlüssel kann nicht verwendet werden, um ein neues Project zu erstellen oder ein bestehendes Project zu beanspruchen, daher muss die --project Option auf ein bestehendes Project gesetzt sein.

Wenn weder die Option --key noch die veraltete --token Option angegeben ist, muss das Project unclaimed sein. Steht in Konflikt mit der veralteten --token Option.

--token <TOKEN>

🐰 VERALTET: API-Tokens sind zugunsten von API-Schlüsseln veraltet. Neue API-Tokens können nicht mehr erstellt werden; bestehende API-Tokens funktionieren weiterhin. Verwenden Sie stattdessen die --key Option.

Optional: Entweder die Option --token oder die Umgebungsvariable BENCHER_API_TOKEN kann auf ein gültiges API-Token gesetzt werden. Wenn beide angegeben sind, hat die Option --token Vorrang vor der Umgebungsvariable BENCHER_API_TOKEN. Wenn weder die Option --token noch die --key Option angegeben ist, muss das Projekt unclaimed sein. Das heißt, wenn Sie bereits ein Projekt claimed haben, müssen Sie einen gültigen API-Schlüssel oder ein gültiges API-Token bereitstellen. Steht in Konflikt mit der --key Option.

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

Siehe Images für dedizierte Hardware für eine vollständige Übersicht.

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

Siehe Branches für eine vollständige Übersicht.

--testbed <TESTBED>

--spec <SPEC>

--spec-reset

Siehe Testumgebungen & Specs für eine vollständige Übersicht.

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

Siehe Schwellenwerte und Benachrichtigungen für einen vollständigen Überblick.

--adapter <ADAPTER>

--average <AVERAGE>

--file <FILE>

--build-time

--file-size <FILE>

Siehe Benchmark-Harness-Adapter für einen vollständigen Überblick.

--iter <COUNT>

Optional: Anzahl der Laufiterationen. Der Standardwert ist 1.

--fold <AGGREGATE_FUNCTION>

Optional: Mehrere Ergebnisse in ein einziges Ergebnis zusammenfalten.
Erforderlich: --iter muss gesetzt sein.
Mögliche Werte:

• min: Minimalwert
• max: Maximalwert
• mean: Mittelwert der Werte
• median: Median der Werte

--backdate <SECONDS>

Optional: Das Berichtsdatum zurückdatieren (Sekunden seit der Epoche). HINWEIS: Dies wird nicht die Reihenfolge der früheren Berichte beeinflussen! Dies ist nützlich, wenn man historische Daten chronologisch in ein Projekt integriert.

--allow-failure

Optional: Benchmark-Testfehler zulassen.

--format <FORMAT>

Optional: Format für den abschließenden Bericht. Der Standardwert ist human.

Mögliche Werte:

• human: Mensch-lesbares Format
• json: JSON-Format
• html: HTML-Format

--quiet

Optional: Ruhemodus, gibt nur den endgültigen Bericht aus. Verwenden Sie die Option --format, um das Ausgabeformat zu ändern.

--github-actions <GITHUB_TOKEN>

Optional: Setzen Sie das GitHub API-Authentifizierungstoken. Die bequemste Methode hierfür ist die Verwendung der GitHub Actions GITHUB_TOKEN Umgebungsvariable (d.h. --github-actions ${{ secrets.GITHUB_TOKEN }}).

Die Ergebnisse werden dem Head-Commit als GitHub-Prüfung mit folgendem Namen hinzugefügt:

1. Bencher Report (<ID>), wenn die Option --ci-id gesetzt ist
2. Bencher Report (<PROJEKTNAME>) für bestehende Projekte
3. Bencher Report für --ci-on-the-fly-Projekte (solange die Prüfung läuft)

Dies erfordert, dass das Token den checks Bereich mit write Berechtigungen hat. Wenn die GitHub-Prüfung nicht erstellt werden kann, protokolliert bencher run eine Warnung und fährt fort.

Wenn bencher run als Teil einer Pull-Anfrage verwendet wird, dann werden die Ergebnisse auch als Kommentar zur Pull-Anfrage hinzugefügt. Alle Jobs eines Projekts in der Pull-Anfrage teilen sich diesen einen Kommentar, mit einer Berichtszeile für jeden Job. Dies erfordert, dass das Token den pull-requests Bereich mit write Berechtigungen hat. Die Ergebnisse werden außerdem immer zur Zusammenfassung des Jobs hinzugefügt. Mit dem Flag --detach veröffentlicht der abgelöste Lauf keinen Kommentar und schreibt keine Zusammenfassung des Jobs, und die Verbindung mit --job schließt die GitHub-Prüfung ab, die er gestartet hat (siehe die Option --ci-callback-token).

Bei zwei oder mehr Zeilen zeigt der Kommentar eine Übersichtstabelle mit jedem Bericht, seinem Testbed, seinem Adapter und seinem Status (Pending, die Anzahl der Alerts, No Alerts oder Failed). Die Zeilen stehen in der Reihenfolge, in der die Berichte gestartet wurden, nummeriert ab 1, so wie die Console die Berichte eines Laufs auflistet. Die Beschriftung jeder Zeile ist ihre Nummer, gefolgt vom Wert der Option --ci-id in Klammern, wenn sie gesetzt ist (z.B.: 2 (microbench)). Die Beschriftung verlinkt auf den Bericht, das Testbed auf seine Seite in der Console und der Adapter auf seinen Teil der Adapter-Dokumentation. Wenn die Jobs mehr als einen Branch verwenden, erhält die Übersichtstabelle eine Spalte für den Branch. Danach enthält eine Tabelle die Alerts aller Berichte, mit einer Spalte für den Bericht. Dann folgen die Ergebnisse jedes Berichts in einem einklappbaren Block (z.B.: Report 2 (microbench): 14 benchmarks, 2 alerts), der geöffnet ist, wenn der Bericht Alerts hat. Jeder Job behält seine eigene GitHub-Prüfung und seine eigene Zusammenfassung des Jobs, sodass sich die Namen der GitHub-Prüfungen und die erforderlichen Statusprüfungen nicht ändern. Ein Job, dessen Commit nicht mehr der Head-Commit der Pull-Anfrage ist, lässt den Kommentar unverändert. Wenn das Token die Pull-Anfrage nicht lesen kann, protokolliert der Job eine Warnung und schreibt den Kommentar, ohne den Head-Commit zu prüfen.

Ein GitHub-Kommentar hat eine Größenbeschränkung, daher verwendet der Kommentar die erste dieser Formen, die passt:

1. Alle oben genannten Teile
2. Ohne die einklappbaren Blöcke, mit einem Hinweis, dass der Kommentar gekürzt ist
3. Jede Übersichtszeile und die Gesamtzahl der Alerts, ohne die Zeilen der Alerts
4. Als letzter Ausweg die ersten Übersichtszeilen, dann and N more reports für den Rest

Mit einer Zeile ist der Kommentar derselbe wie zuvor, und wenn er zu groß ist, verlinkt er auf den vollständigen Bericht.

Um die anderen Jobs zu finden, listet bencher run die GitHub-Prüfungen des Head-Commits auf, was der obige checks Bereich mit write Berechtigungen bereits erlaubt. Wenn ein Job seine GitHub-Prüfung nicht erstellen oder abschließen kann, nicht feststellen kann, welcher GitHub App sie gehört, oder die GitHub-Prüfungen nicht auflisten kann, dann veröffentlicht er einen Kommentar nur mit seinen eigenen Ergebnissen. Kommentare für das Projekt aus einer früheren Version von bencher run werden ersetzt: Der erste Job, der den gemeinsamen Kommentar schreibt, aktualisiert den ältesten davon und löscht die übrigen. Beim Schreiben des gemeinsamen Kommentars aktualisiert oder löscht ein Job nur Kommentare, die von der GitHub App gepostet wurden, der seine GitHub-Prüfung gehört, mit dem GITHUB_TOKEN also vom Bot github-actions.

🐰 Wenn Sie innerhalb eines Docker-Containers in einer GitHub-Aktion laufen, müssen Sie die folgenden Umgebungsvariablen übergeben und den Pfad einbinden, der durch GITHUB_EVENT_PATH angegeben wird:

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

--ci-only-thresholds

Optional: Veröffentlicht Ergebnisse nur in CI, wenn ein Schwellenwert existiert für den Branch, das Testbett und die Messung. Wenn keine Schwellenwerte existieren, wird kein Pull-Request-Kommentar veröffentlicht. Alle Jobs eines Projekts in einem Pull Request teilen sich einen Kommentar, daher wird der Kommentar veröffentlicht, wenn für einen seiner Berichte ein Schwellenwert existiert. Dies gilt nur für Pull-Request-Kommentare. Die GitHub-Prüfung wird immer erstellt. Erfordert: --github-actions

--ci-only-on-alert

Optional: Beginnen Sie mit dem Veröffentlichen von Ergebnissen in CI, nur wenn ein Alert generiert wird. Wenn ein Alert generiert wird, werden alle nachfolgenden Ergebnisse ebenfalls veröffentlicht, selbst wenn sie keine Alerts enthalten. Alle Jobs eines Projekts in einem Pull Request teilen sich einen Kommentar, daher wird der Kommentar erstellt, sobald einer seiner Berichte einen Alert hat, und danach aktualisiert ihn jeder Job. Dies gilt nur für Pull-Request-Kommentare. Die GitHub-Prüfung wird immer erstellt. Erforderlich: --github-actions

--ci-id <ID>

Optional: Benutzerdefinierte ID zum Posten von Ergebnissen an CI. Alle Jobs eines Projekts in einem Pull Request teilen sich einen Kommentar, mit einer Berichtszeile für jeden Job. Mit einer ID ist die Beschriftung der Zeile ihre Nummer und die ID (z.B.: 2 (microbench)). Solange der Bericht des Jobs noch nicht existiert, zeigt seine Zeile nur die ID und keine Nummer (z.B.: (microbench)), als Pending, solange der Job läuft, und steht nach den nummerierten Zeilen. Ohne ID ist die Beschriftung nur die Nummer, und die Zeile erscheint, sobald der Bericht des Jobs existiert. Standardmäßig teilen sich Jobs eine Zeile, wenn sie die gleiche Kombination von: Branch, Testbed und Adapter haben, zusammen mit --build-time und --file-size, falls gesetzt. Das Festlegen einer benutzerdefinierten ID ist nützlich, wenn Bencher auf dem gleichen Commit mehrmals für die gleiche Projekt-, Branch-, Testbed- und Adapter-Kombination ausgeführt wird, damit jeder Lauf seine eigene Zeile erhält. Zum Beispiel teilen sich ein push-Lauf und ein pull_request-Lauf auf demselben Branch den Head-Commit, geben Sie daher jedem Lauf eine eigene ID, oder verwenden Sie --github-actions nicht für den push-Lauf. Andernfalls teilen sich die Läufe eine Zeile, die nur einen von ihnen zeigt, und ein älterer Lauf schreibt nichts, sobald ein neuerer Lauf die Zeile belegt. Die ID wird außerdem anstelle des Projektnamens im Namen der GitHub-Prüfung verwendet (d.h. Bencher Report (<ID>)), sodass jeder Aufruf einen stabilen Namen erhält, der als separate erforderliche Statusprüfung verwendet werden kann. Erforderlich: --github-actions

--ci-number <NUMBER>

Optional: Ausgabenummer für das Posten von Ergebnissen an CI. Bencher wird sein Bestes tun, um die für das Posten von Ergebnissen erforderliche CI-Ausgabenummer zu erkennen. Dies ist jedoch nicht immer in komplexen Setups, wie bei der Verwendung von workflow_run in GitHub Actions, verfügbar. Erforderlich: --github-actions

--ci-public-links

Optional: Alle Links sollten auf öffentliche URLs verweisen, die keine Anmeldung erfordern. Erforderlich: --github-actions

--ci-callback-token <TOKEN>

Optional: Legt das Authentifizierungstoken fest, das der Callback eines abgelösten Jobs auf dedizierter Hardware verwendet.

Wenn Sie das Flag --detach und die Option --github-actions verwenden, löst der Bencher API-Server einen repository_dispatch-Workflow aus, wenn der Job beendet ist. Für ein Projekt mit einem verknüpften Repository erstellt Bencher das Token selbst, daher wird diese Option nicht benötigt. Um stattdessen Ihr eigenes Token zu verwenden, setzen Sie diese Option auf ein feingranulares persönliches Zugriffstoken für das Repository mit mindestens der Berechtigung contents: write. Bencher sendet das repository_dispatch-Ereignis dann mit diesem Token, ob das Projekt ein verknüpftes Repository hat oder nicht. Die CLI verlangt diese Option auf GitHub Enterprise Server und mit einem Bencher API-Server, der älter als v0.6.16 ist. Ohne sie wird ein abgelöster Lauf eines claimed Projekts abgelehnt, wenn der Server keine GitHub App hat, das Projekt kein verknüpftes Repository hat oder sein verknüpftes Repository getrennt ist. Siehe Pull Requests auf dedizierter Hardware in GitHub Actions für einen vollständigen Überblick.

🐰 Sie können hier nicht einfach das GITHUB_TOKEN verwenden, da es abläuft, sobald der aktuelle Workflow beendet ist!

--shell <SHELL>

Optional: Pfad zum Shell-Befehl. Standardmäßig /bin/sh auf Unix-ähnlichen Umgebungen und cmd auf Windows.

--flag <FLAG>

Optional: Shell-Befehlsflagge. Standardmäßig -c in Unix-ähnlichen Umgebungen und /C auf Windows.

--exec

Optional: Befehl als ausführbares Programm und nicht als Shell-Befehl ausführen. Standard, wenn die Anzahl der Argumente für bencher run größer als eins ist.

--host <URL>

Optional: URL des Backend-Hosts.
Standardmäßig Bench Cloud: https://api.bencher.dev

--insecure-host

Optional: Erlaubt unsichere Verbindung zum Bencher API-Server.

Dieses Flag ist nützlich, wenn Sie sich mit einer Bencher Self-Hosted-Instanz verbinden, die über ein selbstsigniertes Zertifikat oder ein Zertifikat verfügt, das nicht im Systemzertifikatsspeicher enthalten ist. Es ist nur auf HTTPS-Verbindungen anwendbar, da HTTP-Verbindungen von Natur aus unsicher sind.

WARNUNG: Verwenden Sie --insecure-host nur in einem sicheren Netzwerk mit verifizierten Quellen, da es die SSL-Verifizierung umgeht und Sie Man-in-the-Middle-Angriffen aussetzen könnte.

--native-tls

Optional: TLS-Zertifikate aus dem nativen Zertifikatspeicher der Plattform laden.

Standardmäßig lädt bencher Zertifikate aus dem gebündelten webpki-roots-Crate. Die webpki-roots sind eine zuverlässige Sammlung von Vertrauensankern von Mozilla, und das Einbinden in bencher verbessert die Portabilität und Leistung. Dies gilt insbesondere für macOS, wo das Auslesen des systemeigenen Vertrauensspeichers eine erhebliche Verzögerung mit sich bringt.

In einigen Fällen möchten Sie jedoch möglicherweise den nativen Zertifikatspeicher der Plattform verwenden, insbesondere wenn Sie sich auf einen unternehmensinternen Vertrauensanker verlassen, der in Ihrem Systemzertifikatspeicher enthalten ist, für einen obligatorischen Proxy oder selbstsignierte Bencher Self-Hosted-Verbindungen.

--timeout <SECONDS>

Optional: Anforderungs-Timeout in Sekunden. Standardmäßig auf 15 Sekunden eingestellt.

--attempts <COUNT>

Optional: Maximale Anzahl von erneuten Versuchen bei Anfragen. Standardmäßig auf 35 Versuche eingestellt.

--retry-after <SECONDS>

Optional: Anfangssekunden für das Warten zwischen den Versuchen (exponentielles Backoff). Standardmäßig 1 Sekunde.

--max-retry-after <SECONDS>

Optional: Maximale Sekunden zwischen den Versuchen (begrenzt exponentielles Backoff). Standardmäßig 30 Sekunden.

--dry-run

Optional: Führen Sie einen Probelauf durch. Dies speichert keine Daten im Backend. Weder ein Bericht, ein Branch (wie im Branches beschrieben) noch ein Testbed werden erstellt.

--help

Optional: Hilfe anzeigen.

🐰 Glückwunsch! Sie haben die Grundlagen von bencher run gelernt! 🎉

Weitermachen: Images auf dedizierter Hardware ➡