So sánh trace với baseline golden

Dùng Altifigence CLI 0.1.9 trên Linux để ghi một baseline từ một trace .altrace đã biết là đúng và kiểm tra các trace sau đó so với nó. Một lần kiểm tra thoát với 0 khi mọi bước nằm trong dung sai và với 1 khi bất kỳ bước nào bị lệch.

Chuẩn bị hai trace

golden-diff đọc các trace .altrace có header khai báo "encoding":"bincode". Tập lệnh bên dưới ghi run.altrace, một trace đã biết là đúng với một lõi và năm sự kiện, và changed.altrace, cùng trace đó nhưng có thêm một sự kiện MAC_COMPUTE. Mỗi dòng sự kiện là 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

Xác nhận hai lệnh wc in ra kích thước tệp.

376
416

Tạo baseline

alti verification golden-diff emit-profile đọc một trace và ghi baseline ra stdout, vì vậy hãy chuyển hướng nó vào một tệp. Một bước bắt đầu tại mỗi API_CALL, và các sự kiện trước API_CALL đầu tiên thuộc bước 0. --tolerance-pct đóng dấu độ lệch cho phép theo phần trăm lên mọi hàng, và mặc định là 10.

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

Xác nhận trạng thái thoát là 0. Tệp bắt đầu bằng hai dòng chú thích # rồi chứa mỗi bước một hàng JSON.

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

Mỗi hàng lưu số lượng sự kiện quan sát được dưới dạng expect_mac, expect_dma_read, expect_dma_write và expect_barrier. cycle_budget là số chu kỳ mà bước trải qua, được tăng thêm tolerance_pct và làm tròn lên: bước 0 trải qua 150 chu kỳ và bước 1 trải qua 210. Các dòng trống và các dòng bắt đầu bằng # bị bỏ qua khi đọc tệp.

Kiểm tra trace so với baseline

alti verification golden-diff check nhận baseline trước và trace sau. Đầu ra văn bản có phần tóm tắt golden-diff: giữa hai dòng biểu ngữ làm từ ký tự ═, rồi mỗi bước một dòng. Các đoạn trích bên dưới bỏ qua các dòng biểu ngữ.

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

Xác nhận trạng thái thoát là 0. Chạy các lệnh trong phần này không có cờ --json toàn cục của alti, để stdout chứa chính báo cáo. --format json in báo cáo, còn --format json-v1 in kết quả có phiên bản kèm nguồn gốc. Cả hai dùng cùng trạng thái thoát như định dạng văn bản.

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

Đọc một lần kiểm tra thất bại

Bước 1 của changed.altrace có ba sự kiện MAC_COMPUTE và trải qua 310 chu kỳ, trong khi baseline mong đợi hai sự kiện và ngân sách 232 chu kỳ.

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

Xác nhận trạng thái thoát là 1. alti cũng in một dòng trạng thái trên stderr có chứa exit=1. Chỉ các số đo thất bại được liệt kê dưới một bước. Để đọc chúng từ báo cáo JSON, hãy chọn các số đo có pass là 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}

Một bước mà baseline liệt kê nhưng trace thiếu sẽ in step N missing from observed trace. Một bước trong trace không có hàng baseline được tính vào unexpected_observed_steps. Cả hai khiến lần kiểm tra thoát với 1.

Xử lý khi thất bại

Khi độ lệch là hành vi có chủ ý, hãy biến trace đã thay đổi thành baseline mới và kiểm tra lại.

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

Một tệp không phải trace khiến emit-profile và check thoát với 1 kèm các thông báo bên dưới. Hãy truyền một tệp bắt đầu bằng ALTR, chẳng hạn 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

Một trace có header khai báo mã hóa payload khác khiến check thoát với 1 kèm một thông báo có dạng này. Hãy truyền một trace có header khai báo "encoding":"bincode", chẳng hạn run.altrace.

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

Một baseline không có hàng nào khiến check thoát với 1 kèm thông báo bên dưới. Chạy lại emit-profile để ghi baseline với mỗi bước một hàng.

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

empty reference file: empty.jsonl

Giá trị --tolerance-pct âm hoặc không phải số thoát với 2 trước khi engine khởi động, kèm văn bản này trong lỗi. Hãy truyền một số từ 0 trở lên, chẳng hạn 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"

Các lệnh engine của CLI