ट्रेस की गोल्डन बेसलाइन से तुलना करें

Linux पर Altifigence CLI 0.1.9 से ज्ञात-सही .altrace ट्रेस से बेसलाइन दर्ज करें और बाद के ट्रेस को उससे जाँचें। जब हर चरण सहनसीमा के भीतर हो तब चेक 0 के साथ समाप्त होता है, और किसी भी चरण में विचलन होने पर 1 के साथ।

दो ट्रेस तैयार करें

golden-diff उन .altrace ट्रेस को पढ़ता है जिनका हेडर "encoding":"bincode" घोषित करता है। नीचे की स्क्रिप्ट run.altrace लिखती है, जो एक कोर और पाँच इवेंट वाला ज्ञात-सही ट्रेस है, और changed.altrace लिखती है, जो वही ट्रेस है जिसमें एक और MAC_COMPUTE इवेंट है। हर इवेंट पंक्ति 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 हो। इस खंड के कमांड 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 पर समाप्त करवाती है। ऐसी फ़ाइल दें जो ALTR से शुरू होती हो, जैसे 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

जिस ट्रेस का हेडर कोई दूसरा पेलोड एन्कोडिंग घोषित करता है, वह check को इस रूप के संदेश के साथ 1 पर समाप्त करवाता है। ऐसा ट्रेस दें जिसका हेडर "encoding":"bincode" घोषित करता हो, जैसे run.altrace।

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 पर समाप्त होता है। 0 या उससे अधिक की संख्या दें, जैसे 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 इंजन कमांड