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.
Optionen
--project <PROJECT>
Entweder die Option --project
oder die Umgebungsvariable BENCHER_PROJECT
muss auf den Slug oder UUID eines bereits existierenden Projekts gesetzt werden.
Wenn beide definiert sind, hat die Option --project
Vorrang vor der Umgebungsvariable BENCHER_PROJECT
.
--token <TOKEN>
Entweder die Option --token
oder die Umgebungsvariable BENCHER_API_TOKEN
muss auf ein gültiges API-Token gesetzt werden.
Wenn beide definiert sind, hat die Option --token
Vorrang vor der Umgebungsvariable BENCHER_API_TOKEN
.
--branch <BRANCH>
--branch-start-point <BRANCH>
--branch-start-point-hash <HASH>
--branch-reset
Siehe Branch-Auswahl für einen vollständigen Überblick.
--hash <HASH>
Optional: Ein 40-stelliger SHA-1-Commit-Hash. Wenn zwei Berichte den gleichen Branch und Hash haben, werden sie als vom selben Commit angesehen. Daher werden sie die gleiche Branch-Version Nummer haben.
Wenn nicht angegeben, versucht die Bencher CLI, den aktuellen Git-Hash zu finden. Es beginnt mit der Suche nach einem Git-Repository im aktuellen Arbeitsverzeichnis. Wenn dies nicht erfolgreich ist, wechselt es zu seinem übergeordneten Verzeichnis und wiederholt den Vorgang bis zum Stammverzeichnis. Wenn ein Git-Repository gefunden wird, dann wird der Git-Hash des HEAD der aktuellen Branch verwendet.
--no-hash
Optional: Versucht nicht, einen git
-Commit-Hash zu finden.
Diese Option steht in Konflikt mit --hash
und setzt dessen Standardverhalten, nach einem git
-Repository zu suchen, außer Kraft.
--testbed <TESTBED>
Optional: Entweder die Option --testbed
oder die Umgebungsvariable BENCHER_TESTBED
kann auf den Slug oder UUID einer bereits existierenden Testplattform gesetzt werden.
Wenn beide definiert sind, hat die Option --testbed
Vorrang vor der Umgebungsvariable BENCHER_TESTBED
.
Wenn keine definiert sind, dann wird localhost
als Standard-Testplattform verwendet.
--adapter <ADAPTER>
--average <AVERAGE>
--file <FILE>
--file-size <FILE>
Siehe Benchmark-Harness-Adapter für einen vollständigen Überblick.
--iter <ITER>
Optional: Anzahl der Laufiterationen. Der Standardwert ist 1
.
--fold <FOLD>
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 <DATETIME_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.
--err
Optional: Fehler bei der Erzeugung eines Alarms. Siehe Schwellenwerte und Alarme für einen vollständigen Überblick.
--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 (d.h. --github-actions ${{ secrets.GITHUB_TOKEN }}
).
Wenn diese Option gesetzt ist und bencher run
wird in GitHub Actions als Teil eines Pull Requests verwendet,
dann werden die Ergebnisse dem Pull Request als Kommentar hinzugefügt.
Der bequemste Weg, dies zu tun, ist die GitHub Actions GITHUB_TOKEN
Umgebungsvariable.
🐰 Wenn Sie innerhalb eines Docker-Containers in GitHub Action arbeiten, müssen Sie die folgenden Umgebungsvariablen übergeben und den Pfad einbinden, der von
GITHUB_EVENT_PATH
angegeben wird:
GITHUB_ACTIONS
GITHUB_EVENT_NAME
GITHUB_EVENT_PATH
--ci-only-thresholds
Optional: Ergebnisse nur an CI posten, wenn ein Threshold für die Art der Metrik, den Branch und die Testplattform existiert.
Wenn keine Schwellenwerte existieren, wird nichts gepostet.
Erforderlich: --github-actions
--ci-only-on-alert
Optional: Ergebnisse nur an CI posten, wenn ein Alarm erzeugt wird.
Wenn ein Alarm erzeugt wird, werden auch nachfolgende Ergebnisse, auch wenn sie keine Alarme enthalten, gepostet.
Erforderlich: --github-actions
--ci-id
Optional: Benutzerdefinierte ID für das Posten von Ergebnissen an CI.
Standardmäßig segmentiert Bencher Ergebnisse automatisch nach der Kombination aus: Projekt, Branch, Testplattform und Adapter.
Das Setzen einer benutzerdefinierten ID ist nützlich, wenn Bencher mehrere Male im selben CI-Workflow für die gleiche Kombination aus Projekt, Branch, Testplattform und Adapter ausgeführt wird.
Erforderlich: --github-actions
--ci-number
Optional: Ausgabenummer für das Posten von Ergebnissen an CI.
Bencher wird sein Bestes tun, um die für das Posten von Ergebnissen benötigte CI-Ausgabennummer zu ermitteln.
Dies ist jedoch in komplexen Setups, wie bei der Verwendung von workflow_run
in GitHub Actions, nicht immer verfügbar.
Erforderlich: --github-actions
--shell <SHELL>
Optional: Shell-Befehlspfad. Standardmäßig ist dies /bin/sh
in Unix-ähnlichen Umgebungen und cmd
in Windows.
--flag <FLAG>
Optional: Shell-Befehlsflag. Standardmäßig ist dies -c
in Unix-ähnlichen Umgebungen und /C
in 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: Backend-Host-URL. Standardmäßig ist dies https://api.bencher.dev.
--attempts <ATTEMPTS>
Optional: Max. Anzahl der Wiederholungsversuche der Anfrage. Standardmäßig ist dies 10
.
--retry-after <RETRY_AFTER_SECONDS>
Optional: Anfrage nach der angegebenen Anzahl von Sekunden erneut versuchen (exponentielles Backoff). Standardmäßig ist dies 1
.
--dry-run
Optional: Trockenlauf durchführen. Dies speichert keine Daten im Backend. Weder ein Bericht noch ein Branch, wie in der Branch-Auswahl detailliert beschrieben, werden erstellt.
-h
--help
Optional: Hilfe anzeigen.
🐰 Glückwunsch! Sie haben die Grundlagen von
bencher run
gelernt! 🎉