トレースをゴールデンベースラインと比較する

正常と分かっているトレースからゴールデンdiffのベースラインを作成し、後のトレースをテキストまたはJSONでそれと照合し、変更が意図したものである場合はベースラインを更新します。

Linux上のAltifigence CLI 0.1.9を使用して、正常と分かっている.altraceトレースからベースラインを記録し、後のトレースをそれと照合します。すべてのステップが許容範囲内であれば、チェックは0で終了し、いずれかのステップがずれた場合は1で終了します。

二つのトレースを準備する

golden-diffは、ヘッダーが"encoding":"bincode"を宣言する.altraceトレースを読み取ります。以下のスクリプトは、一つのコアと五つのイベントを持つ正常なトレースrun.altraceと、同じトレースにMAC_COMPUTEイベントを一つ追加したchanged.altraceを書き込みます。各イベント行は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

二つのwcコマンドがファイルサイズを出力することを確認してください。

376
416

ベースラインを作成する

alti verification golden-diff emit-profileは一つのトレースを読み取り、ベースラインを標準出力に書き込むので、ファイルにリダイレクトしてください。ステップは各API_CALLで始まり、最初のAPI_CALLより前のイベントはステップ0に属します。--tolerance-pctは許容するずれをパーセントですべての行に記録し、既定値は10です。

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

終了ステータスが0であることを確認してください。ファイルは#で始まるコメント行二行で始まり、その後にステップごとに一つの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}

各行には、観測されたイベント数がexpect_mac、expect_dma_read、expect_dma_write、expect_barrierとして保存されます。cycle_budgetは、そのステップが占めるサイクル数をtolerance_pctで指定した割合だけ増やして切り上げた値です。ステップ0は150サイクル、ステップ1は210サイクルを占めます。ファイルの読み取り時には、空行と#で始まる行はスキップされます。

トレースをベースラインと照合する

alti verification golden-diff checkは、最初にベースライン、次にトレースを取ります。テキスト出力では、═文字で作られた二本のバナー行の間にgolden-diff:サマリーがあり、その後にステップごとに一行が続きます。以下の抜粋ではバナー行を省略しています。

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

終了ステータスが0であることを確認してください。このセクションのコマンドは、altiのグローバルな--jsonフラグを付けずに実行してください。そうすると、stdoutにレポートそのものが出力されます。--format jsonはレポートを出力し、--format json-v1は来歴付きのバージョン管理された結果を出力します。どちらもテキスト形式と同じ終了ステータスを使用します。

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

失敗したチェックを読み取る

changed.altraceのステップ1には三つのMAC_COMPUTEイベントがあり、310サイクルを占めます。一方、ベースラインは二つのイベントと232サイクルの予算を想定しています。

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

終了ステータスが1であることを確認してください。altiはstderrにexit=1を含むステータス行も出力します。ステップの下には、失敗したメトリクスだけが一覧表示されます。JSONレポートで確認するには、passが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}

ベースラインに記載されているのにトレースにないステップは、step N missing from observed traceと出力されます。トレースにあってベースラインに行がないステップは、unexpected_observed_stepsにカウントされます。どちらの場合も、チェックは1で終了します。

失敗に対処する

ずれが意図した動作である場合は、変更したトレースを新しいベースラインにして、もう一度チェックしてください。

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

トレースではないファイルを指定すると、emit-profileとcheckは以下のメッセージを出して1で終了します。run.altraceのように、ALTRで始まるファイルを指定してください。

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

ヘッダーが別のペイロードエンコードを宣言するトレースを指定すると、checkは次の形式のメッセージを出して1で終了します。run.altraceのように、ヘッダーが"encoding":"bincode"を宣言するトレースを指定してください。

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

行のないベースラインを指定すると、checkは以下のメッセージを出して1で終了します。emit-profileをもう一度実行して、ステップごとに一行のベースラインを書き込んでください。

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

empty reference file: empty.jsonl

負の値または数値以外の--tolerance-pctを指定すると、エンジンが起動する前に2で終了し、エラーに次のテキストが含まれます。5など、0以上の数を指定してください。

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 エンジンコマンド