Comparer une trace avec une baseline golden

Utilisez Altifigence CLI 0.1.9 sous Linux pour enregistrer une baseline à partir d’une trace .altrace connue comme correcte et vérifier les traces ultérieures par rapport à elle. Une vérification se termine avec 0 lorsque chaque étape est dans la tolérance et avec 1 lorsqu’une étape dérive.

Préparer deux traces

golden-diff lit des traces .altrace dont l’en-tête déclare "encoding":"bincode". Le script ci-dessous écrit run.altrace, une trace connue comme correcte avec un cœur et cinq événements, et changed.altrace, la même trace avec un événement MAC_COMPUTE de plus. Chaque ligne d’événement a la forme 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

Vérifiez que les deux commandes wc affichent les tailles des fichiers.

376
416

Créer la baseline

alti verification golden-diff emit-profile lit une trace et écrit la baseline sur stdout ; redirigez-la donc vers un fichier. Une étape commence à chaque API_CALL, et les événements avant le premier API_CALL appartiennent à l’étape 0. --tolerance-pct appose sur chaque ligne la dérive autorisée en pourcentage, et la valeur par défaut est 10.

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

Vérifiez que le code de sortie est 0. Le fichier commence par deux lignes de commentaire #, puis contient une ligne JSON par étape.

{"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}

Chaque ligne stocke les nombres d’événements observés sous les noms expect_mac, expect_dma_read, expect_dma_write et expect_barrier. cycle_budget correspond aux cycles couverts par l’étape, majorés de tolerance_pct et arrondis à l’entier supérieur : l’étape 0 couvre 150 cycles et l’étape 1 couvre 210. Les lignes vides et les lignes qui commencent par # sont ignorées à la lecture du fichier.

Vérifier une trace par rapport à la baseline

alti verification golden-diff check prend d’abord la baseline, puis la trace. La sortie texte contient un résumé golden-diff: entre deux lignes de bannière composées de caractères ═, puis une ligne par étape. Les extraits ci-dessous omettent les lignes de bannière.

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

Vérifiez que le code de sortie est 0. Exécutez les commandes de cette section sans l’option globale --json de alti, afin que stdout contienne le rapport lui-même. --format json affiche le rapport, et --format json-v1 affiche le résultat versionné avec la provenance. Les deux utilisent le même code de sortie que le format texte.

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

Lire une vérification en échec

L’étape 1 de changed.altrace contient trois événements MAC_COMPUTE et couvre 310 cycles, alors que la baseline attend deux événements et un budget de 232 cycles.

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

Vérifiez que le code de sortie est 1. alti affiche aussi sur stderr une ligne d’état qui contient exit=1. Seules les métriques en échec sont listées sous une étape. Pour les lire dans le rapport JSON, sélectionnez les métriques dont pass vaut false.

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}

Une étape que la baseline liste mais que la trace n’a pas affiche step N missing from observed trace. Une étape de la trace qui n’a pas de ligne dans la baseline est comptée dans unexpected_observed_steps. Les deux font se terminer la vérification avec 1.

Reprendre après des échecs

Lorsque la dérive correspond au comportement voulu, faites de la trace modifiée la nouvelle baseline et vérifiez de nouveau.

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

Un fichier qui n’est pas une trace fait se terminer emit-profile et check avec 1 et les messages ci-dessous. Transmettez un fichier qui commence par ALTR, par exemple 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

Une trace dont l’en-tête déclare un autre encodage de charge utile fait se terminer check avec 1 et un message de cette forme. Transmettez une trace dont l’en-tête déclare "encoding":"bincode", par exemple run.altrace.

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

Une baseline sans lignes fait se terminer check avec 1 et le message ci-dessous. Relancez emit-profile pour écrire une baseline avec une ligne par étape.

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

empty reference file: empty.jsonl

Un --tolerance-pct négatif ou non numérique se termine avec 2 avant le démarrage du moteur, avec ce texte dans l’erreur. Transmettez un nombre égal ou supérieur à 0, par exemple 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"

Commandes CLI des moteurs