Einen Trace mit einer Golden-Baseline vergleichen

Verwenden Sie Altifigence CLI 0.1.9 unter Linux, um eine Baseline aus einem bekannt guten .altrace-Trace aufzuzeichnen und spätere Traces dagegen zu prüfen. Eine Prüfung endet mit 0, wenn jeder Schritt innerhalb der Toleranz liegt, und mit 1, wenn ein Schritt abweicht.

Zwei Traces vorbereiten

golden-diff liest .altrace-Traces, deren Header "encoding":"bincode" deklariert. Das folgende Skript schreibt run.altrace, einen bekannt guten Trace mit einem Kern und fünf Ereignissen, und changed.altrace, denselben Trace mit einem weiteren MAC_COMPUTE-Ereignis. Jede Ereigniszeile hat die Form core start duration type [api_name].

PROJECT="$(cd "$HOME/alti-projects/demo-project" && pwd -P)"
cd "$PROJECT"

le() { local n=$1 v=$2; while [ "$n" -gt 0 ]; do printf "\\x$(printf %02x $((v & 255)))"; v=$((v >> 8)); n=$((n - 1)); done; }
str() { le 8 "${#1}"; printf '%s' "$1"; }
write_trace() {
  local out="$1" payload line core start dur type api total=0 header
  local -a lines
  mapfile -t lines
  payload="$(mktemp)"
  {
    for line in "${lines[@]}"; do
      read -r core start dur type api <<<"$line"
      (( start + dur > total )) && total=$((start + dur))
    done
    le 8 "$total"
    le 8 "${#lines[@]}"
    for line in "${lines[@]}"; do
      read -r core start dur type api <<<"$line"
      le 4 "$core"; le 8 "$start"; le 8 "$dur"; str "$type"
      if [ -n "$api" ]; then printf '\x01'; str "$api"; else printf '\x00'; fi
    done
  } >"$payload"
  header="{\"altifigence_trace_version\":\"1.0\",\"trace\":{\"cycles\":$total,\"cores\":1,\"clock_mhz\":1000},\"payload\":{\"encoding\":\"bincode\",\"byte_length\":$(wc -c <"$payload")}}"
  { printf 'ALTR\x01\x01\x00\x00'; le 8 "${#header}"; printf '%s' "$header"; cat "$payload"; } >"$out"
  rm -f "$payload"
}

write_trace run.altrace <<'EVENTS'
0 0 100 MAC_COMPUTE
0 100 50 DMA_READ
0 150 5 API_CALL step_1
0 160 100 MAC_COMPUTE
0 260 100 MAC_COMPUTE
EVENTS

write_trace changed.altrace <<'EVENTS'
0 0 100 MAC_COMPUTE
0 100 50 DMA_READ
0 150 5 API_CALL step_1
0 160 100 MAC_COMPUTE
0 260 100 MAC_COMPUTE
0 360 100 MAC_COMPUTE
EVENTS

wc -c < run.altrace
wc -c < changed.altrace

Prüfen Sie, dass die beiden wc-Befehle die Dateigrößen ausgeben.

376
416

Die Baseline erstellen

alti verification golden-diff emit-profile liest einen Trace und schreibt die Baseline nach stdout, leiten Sie sie daher in eine Datei um. Ein Schritt beginnt bei jedem API_CALL, und Ereignisse vor dem ersten API_CALL gehören zu Schritt 0. --tolerance-pct versieht jede Zeile mit der erlaubten Abweichung in Prozent, der Standardwert ist 10.

alti verification golden-diff emit-profile --project "$PROJECT" run.altrace > "$PROJECT/reference.jsonl"
grep -v '^#' "$PROJECT/reference.jsonl"

Prüfen Sie, dass der Exit-Status 0 ist. Die Datei beginnt mit zwei #-Kommentarzeilen und enthält dann eine JSON-Zeile pro Schritt.

{"step":0,"api_name":null,"expect_mac":1,"expect_dma_read":1,"expect_dma_write":0,"expect_barrier":0,"cycle_budget":165,"tolerance_pct":10.0,"abs_tolerance":null}
{"step":1,"api_name":"step_1","expect_mac":2,"expect_dma_read":0,"expect_dma_write":0,"expect_barrier":0,"cycle_budget":232,"tolerance_pct":10.0,"abs_tolerance":null}

Jede Zeile speichert die beobachteten Ereignisanzahlen als expect_mac, expect_dma_read, expect_dma_write und expect_barrier. cycle_budget sind die Zyklen, die der Schritt umfasst, erhöht um tolerance_pct und aufgerundet: Schritt 0 umfasst 150 Zyklen und Schritt 1 umfasst 210. Leerzeilen und Zeilen, die mit # beginnen, werden beim Lesen der Datei übersprungen.

Einen Trace gegen die Baseline prüfen

alti verification golden-diff check erwartet zuerst die Baseline und danach den Trace. Die Textausgabe enthält eine Zusammenfassung golden-diff: zwischen zwei Bannerzeilen aus ═-Zeichen und dann eine Zeile pro Schritt. Die folgenden Auszüge lassen die Bannerzeilen weg.

alti verification golden-diff check --project "$PROJECT" reference.jsonl run.altrace; echo "exit=$?"

  golden-diff: all 2 steps within tolerance
step   0 pass
step   1 pass
exit=0

Prüfen Sie, dass der Exit-Status 0 ist. Führen Sie die Befehle in diesem Abschnitt ohne das globale Flag --json von alti aus, damit stdout den Bericht selbst enthält. --format json gibt den Bericht aus, und --format json-v1 gibt das versionierte Ergebnis mit Herkunftsangaben aus. Beide verwenden denselben Exit-Status wie das Textformat.

alti verification golden-diff check --project "$PROJECT" reference.jsonl run.altrace --format json \
  | jq '{summary, step_count, pass_count, total_metrics, exact_matches, tolerance_passes, metric_mismatches, unexpected_observed_steps}'

{
  "summary": "golden-diff: all 2 steps within tolerance",
  "step_count": 2,
  "pass_count": 2,
  "total_metrics": 10,
  "exact_matches": 8,
  "tolerance_passes": 2,
  "metric_mismatches": 0,
  "unexpected_observed_steps": 0
}

alti verification golden-diff check --project "$PROJECT" reference.jsonl run.altrace --format json-v1 \
  | jq '{schema, operation_id, artifact_schema: .artifact.artifact_schema, engine: .provenance.engine}'

{
  "schema": "altifigence.golden-diff.operation-result.v1",
  "operation_id": "altifigence.verification.golden-diff.v1",
  "artifact_schema": "altifigence.golden-diff.report.v1",
  "engine": "alti-verification"
}

Eine fehlgeschlagene Prüfung lesen

Schritt 1 von changed.altrace enthält drei MAC_COMPUTE-Ereignisse und umfasst 310 Zyklen, während die Baseline zwei Ereignisse und ein Budget von 232 Zyklen erwartet.

alti verification golden-diff check --project "$PROJECT" reference.jsonl changed.altrace; echo "exit=$?"

  golden-diff: 1 / 2 steps PASS — 1 regressed
step   0 pass
step   1 drift on [mac, cycles]
    └─ mac       observed=3 · expected=2 · tol ±10.0%
    └─ cycles    observed=310 · expected=232 · tol ±10.0%
exit=1

Prüfen Sie, dass der Exit-Status 1 ist. alti gibt außerdem auf stderr eine Statuszeile aus, die exit=1 enthält. Unter einem Schritt werden nur die fehlgeschlagenen Metriken aufgeführt. Um sie aus dem JSON-Bericht zu lesen, wählen Sie die Metriken aus, deren pass false ist.

alti verification golden-diff check --project "$PROJECT" reference.jsonl changed.altrace --format json \
  | jq -c '.steps[] | select(.is_pass | not) | .metrics[] | select(.pass | not) | {name, observed, expected}'

{"name":"mac","observed":3,"expected":2}
{"name":"cycles","observed":310,"expected":232}

Ein Schritt, den die Baseline aufführt, der im Trace aber fehlt, gibt step N missing from observed trace aus. Ein Schritt im Trace, der keine Baseline-Zeile hat, wird in unexpected_observed_steps gezählt. Beides lässt die Prüfung mit 1 enden.

Nach Fehlschlägen fortfahren

Wenn die Abweichung das beabsichtigte Verhalten ist, machen Sie den geänderten Trace zur neuen Baseline und prüfen Sie erneut.

alti verification golden-diff emit-profile --project "$PROJECT" changed.altrace > "$PROJECT/reference.jsonl"
alti verification golden-diff check --project "$PROJECT" reference.jsonl changed.altrace; echo "exit=$?"

  golden-diff: all 2 steps within tolerance
step   0 pass
step   1 pass
exit=0

Bei einer Datei, die kein Trace ist, enden emit-profile und check mit 1 und den folgenden Meldungen. Übergeben Sie eine Datei, die mit ALTR beginnt, etwa run.altrace.

printf 'this is not a trace\n' > "$PROJECT/notes.txt"
alti verification golden-diff emit-profile --project "$PROJECT" notes.txt
alti verification golden-diff check --project "$PROJECT" reference.jsonl notes.txt

parse error in 'notes.txt': Invalid magic number — expected 'ALTR', got '[116, 104, 105, 115]'
trace parse error for 'notes.txt': invalid .altrace magic

Bei einem Trace, dessen Header eine andere Nutzdatenkodierung deklariert, endet check mit 1 und einer Meldung dieser Form. Übergeben Sie einen Trace, dessen Header "encoding":"bincode" deklariert, etwa run.altrace.

trace parse error for 'other.altrace': unsupported .altrace payload encoding 'flatbuf'

Bei einer Baseline ohne Zeilen endet check mit 1 und der folgenden Meldung. Führen Sie emit-profile erneut aus, um eine Baseline mit einer Zeile pro Schritt zu schreiben.

: > "$PROJECT/empty.jsonl"
alti verification golden-diff check --project "$PROJECT" empty.jsonl run.altrace

empty reference file: empty.jsonl

Ein negatives oder nicht numerisches --tolerance-pct endet mit 2, bevor die Engine startet, mit diesem Text im Fehler. Übergeben Sie eine Zahl von 0 oder mehr, etwa 5.

tolerance-pct must be a finite non-negative number

alti verification golden-diff emit-profile --project "$PROJECT" run.altrace --tolerance-pct 5 > "$PROJECT/reference.jsonl"

CLI-Engine-Befehle