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 für bencher run
ist der optionale Benchmark-Befehl.
Dies ist der Befehl, der ausgeführt wird, um Ihr Benchmark-Harness zu starten.
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
festgelegt werden kann.
Wenn das Benchmark-Harness jedoch in eine Datei schreibt, dann muss auch die Option --file
verwendet werden, um den Pfad der Ausgabedatei anzugeben.
Alternative, um die Größe der Ausgabedatei (z. B. Binärgröße) anstelle ihres Inhalts zu verfolgen,
verwenden Sie die Option --file-size
, um den Pfad der Ausgabedatei anzugeben.
Wenn Sie bevorzugen, dass der Befehl nicht in einer Shell ausgeführt wird, können Sie den --exec
Flag verwenden oder einfach zusätzliche Argumente zu Ihrem Befehl als zusätzliche Argumente zu bencher run
hinzufügen.
Shell-Formular:
bencher run "bencher mock"
Ausführungsformular:
bencher run bencher mock
Der Benchmark-Befehl kann mehrmals 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, der Flag --allow-failure
wird gesetzt.
Wenn der Benchmark-Befehl nicht angegeben ist, aber die Option --file
verwendet wird,
dann wird bencher run
stattdessen einfach den Pfad der Ausgabedatei lesen.
Ähnlich, wenn der Benchmark-Befehl nicht angegeben ist, aber die Option --file-size
verwendet wird,
dann wird bencher run
einfach die Größe der Datei am angegebenen Dateipfad lesen.
Wenn weder der Benchmark-Befehl, die Option --file
,
noch die Option --file-size
angegeben sind,
wird bencher run
stattdessen von stdin
lesen.
Dies ermöglicht es Ihnen, die Ausgabe eines anderen Befehls in eine Datei zu speichern oder 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 eines Projekts gesetzt werden.
Wenn der angegebene Wert ein Slug ist und das Projekt noch nicht existiert, wird es für Sie erstellt.
Wenn der angegebene Wert jedoch eine UUID ist, muss das Projekt 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:
- Dem Namen des übergeordneten Verzeichnisses für das
git
-Repository, falls verfügbar. - Einem 7-stelligen hexadezimalen Kurz-Hash für den initialen Commit des
git
-Repositories, falls verfügbar. - Einem 13-stelligen alphanumerischen Fingerabdruck der lokalen Maschine, für unterstützte Betriebssysteme.
Ein generierter Projekt-Slug könnte zum Beispiel so aussehen: project-abc4567-wxyz123456789
Wenn ein neues Projekt für Sie erstellt wird, egal ob der Slug angegeben oder generiert wird,
muss das Projekt zu einer Organisation gehören.
Wenn der Benutzer authentifiziert ist, wird das Projekt unter der persönlichen Organisation dieses Benutzers hinzugefügt.
Wenn der Benutzer nicht authentifiziert ist, wird das Projekt unter einer neuen unclaimed
Organisation erstellt.
Diese Organisation kann dann von der öffentlichen Perf-Seite des Projekts aus beansprucht
werden
oder indem der Projekt-Slug während einer nachfolgenden Ausführung von bencher run
verwendet wird, wenn sie authentifiziert sind.
--token <TOKEN>
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 keiner angegeben ist, muss das Projekt unclaimed
sein. Das heißt, wenn Sie bereits ein Projekt claimed
haben, müssen Sie ein gültiges API-Token bereitstellen. Klicken Sie hier, um ein API-Token zu erstellen.
--branch <BRANCH>
--hash <HASH>
--start-point <BRANCH>
--start-point-hash <HASH>
--start-point-max-versions <COUNT>
--start-point-clone-thresholds
--start-point-reset
Siehe Branch-Auswahl für eine vollständige Übersicht.
--testbed <TESTBED>
Optional: Entweder die Option --testbed
oder die Umgebungsvariable BENCHER_TESTBED
kann auf den Namen, den Slug oder die UUID für ein Testbed gesetzt werden. Wenn der angegebene Wert ein Name oder Slug ist und das Testbed noch nicht existiert, wird es für Sie erstellt. Wenn der angegebene Wert jedoch eine UUID ist, muss das Testbed bereits existieren. Wenn beide angegeben sind, hat die --testbed
Option Vorrang vor der Umgebungsvariable BENCHER_TESTBED
. Wenn keiner angegeben ist, wird Linux
, macOS
oder Windows
verwendet, abhängig vom Host-Betriebssystem. Wenn das bencher
CLI für ein anderes Betriebssystem kompiliert wurde, wird localhost
als Standard-Testbed verwendet.
--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
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
: Minimalwertmax
: Maximalwertmean
: Mittelwert der Wertemedian
: 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 Formatjson
: JSON-Formathtml
: 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 }}
).
Wenn diese Option gesetzt ist und bencher run
in GitHub Actions als Teil einer Pull-Anfrage verwendet wird,
dann werden die Ergebnisse als Kommentar zur Pull-Anfrage hinzugefügt.
Dies erfordert, dass das Token den pull-requests
Bereich mit write
Berechtigungen hat.
Andernfalls werden die Ergebnisse dem Commit als GitHub-Prüfung hinzugefügt.
Dies erfordert, dass das Token den checks
Bereich mit write
Berechtigungen hat.
In jedem Fall werden die Ergebnisse auch zur Zusammenfassung des Jobs hinzugefügt.
🐰 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 nichts veröffentlicht.
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. Erforderlich: --github-actions
--ci-id <ID>
Optional: Benutzerdefinierte ID zum Posten von Ergebnissen an CI.
Standardmäßig segmentiert Bencher die Ergebnisse automatisch anhand der Kombination von: Projekt, Branch, Testbed und Adapter.
Das Festlegen einer benutzerdefinierten ID ist nützlich, wenn Bencher im gleichen CI-Workflow mehrmals für die gleiche Projekt-, Branch-, Testbed- und Adapter-Kombination ausgeführt wird.
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
--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 10
Versuche eingestellt.
--retry-after <SECONDS>
Optional: Anfangssekunden für das Warten zwischen den Versuchen (exponentielles Backoff).
Standardmäßig 1
Sekunde.
--dry-run
Optional: Führen Sie einen Probelauf durch. Dies speichert keine Daten im Backend. Weder ein Bericht, ein Branch (wie im Branch-Auswahl beschrieben) noch ein Testbed werden erstellt.
--help
Optional: Hilfe anzeigen.
🐰 Glückwunsch! Sie haben die Grundlagen von
bencher run
gelernt! 🎉