트레이스를 골든 베이스라인과 비교하기
정상으로 확인된 트레이스에서 golden-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은 트레이스 하나를 읽고 베이스라인을 stdout에 쓰므로 파일로 리디렉션하세요. 단계는 각 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인지 확인하세요. stdout에 보고서 자체가 담기도록 이 섹션의 명령은 alti의 전역 --json 플래그 없이 실행하세요. --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는 exit=1이 포함된 상태 줄도 stderr에 출력합니다. 단계 아래에는 실패한 지표만 나열됩니다. 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.txtparse 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.altraceempty reference file: empty.jsonl--tolerance-pct가 음수이거나 숫자가 아니면 엔진이 시작되기 전에 명령이 2로 종료되며, 오류에 이 텍스트가 표시됩니다. 5처럼 0 이상의 숫자를 전달하세요.
tolerance-pct must be a finite non-negative numberalti verification golden-diff emit-profile --project "$PROJECT" run.altrace --tolerance-pct 5 > "$PROJECT/reference.jsonl"