檢查、匯出並檢閱追蹤 — Altifigence Documentation

檢查.altrace追蹤，儲存其時間軸以及VCD或Chrome匯出檔，並將結果保留為可重新開啟的檢閱套件。

在Linux上使用Altifigence CLI 0.1.9，檢查一個.altrace追蹤、儲存其時間軸、將其匯出為VCD或Chrome追蹤事件，並將結果保留在檢閱套件中，供您列出、顯示及讀回。每個命令都會執行與alti一併提供的alti-trace引擎。

準備追蹤檔案

alti trace命令會讀取.altrace檔案。檔案包含四個位元組的ALTR、兩個版本位元組、兩個零位元組、以8個小端序位元組表示的標頭長度、JSON標頭，以及標頭所描述的酬載。下方的指令碼會寫出一個小型追蹤，包含一個核心與五個事件：三個MAC_COMPUTE、一個DMA_READ，以及一個名為step_1的API_CALL。每個事件行的格式為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

wc -c < run.altrace

請確認最後一個命令輸出376：16個前置位元組、宣告"encoding":"bincode"與"byte_length":224的136位元組標頭，以及224位元組的酬載。

檢查追蹤

以追蹤路徑執行alti trace inspect。相對路徑會依--project解析。預設輸出為JSON，.artifact.inspect包含追蹤摘要。

alti trace inspect --project "$PROJECT" run.altrace \
  | jq '.artifact.inspect | {payload_encoding, payload_bytes, total_cycles, cores, clock_mhz, event_count, event_types}'

{
  "payload_encoding": "bincode",
  "payload_bytes": 224,
  "total_cycles": 360,
  "cores": 1,
  "clock_mhz": 1000,
  "event_count": 5,
  "event_types": {
    "API_CALL": 1,
    "DMA_READ": 1,
    "MAC_COMPUTE": 3
  }
}

請確認結束狀態為0。加上--format text可取得簡短報告。

alti trace inspect --project "$PROJECT" run.altrace --format text

alti-trace: run.altrace
  cycles: 360
  cores: 1
  clock: 1000 MHz
  payload: 224 bytes (bincode)
  events: 5
  - API_CALL: 1
  - DMA_READ: 1
  - MAC_COMPUTE: 3

完整的JSON具有結構描述altifigence.trace.operation.result.v1。其.artifact.artifact_id是已儲存結果的識別碼，格式為trace:altifigence.trace.inspect.v1:後接摘要的content_sha256。inspect可讀取酬載編碼為bincode、flatbuf、flatbuf_v2或flat的追蹤。

儲存時間軸與匯出檔

alti trace timeline會將追蹤的時間軸資料寫入<OUTPUT>。alti trace export先接受格式vcd或chrome，再接受追蹤與輸出路徑。每個命令都會寫入輸出檔案，並輸出描述該檔案的結果JSON。

alti trace timeline --project "$PROJECT" run.altrace run.timeline \
  | jq '{operation_id, artifact: (.artifact | {artifact_schema, media_type, byte_length, records_written, output_label})}'

{
  "operation_id": "altifigence.trace.timeline.v1",
  "artifact": {
    "artifact_schema": "altifigence.trace.timeline.flatbuffer.v1",
    "media_type": "application/vnd.altifigence.trace-flatbuffer",
    "byte_length": 140,
    "records_written": 5,
    "output_label": "run.timeline"
  }
}

時間軸為每個事件儲存24位元組，後接API_CALL名稱，因此此追蹤的byte_length為140，records_written為5。請以兩種格式匯出相同的追蹤。

alti trace export vcd --project "$PROJECT" run.altrace run.vcd \
  | jq -c '.artifact | {artifact_schema, media_type, records_written, output_label}'
alti trace export chrome --project "$PROJECT" run.altrace run.json \
  | jq -c '.artifact | {artifact_schema, media_type, records_written, output_label}'

{"artifact_schema":"altifigence.trace.export.vcd.v1","media_type":"text/x-vcd","records_written":374,"output_label":"run.vcd"}
{"artifact_schema":"altifigence.trace.export.chrome.v1","media_type":"application/json","records_written":5,"output_label":"run.json"}

請確認每個命令的結束狀態皆為0。run.vcd以$version行開頭，run.json是JSON陣列，每個事件對應一個物件。

head -n 1 "$PROJECT/run.vcd"
jq length "$PROJECT/run.json"

$version alti_core vcd_writer 0.1 $end
5

將結果保留在檢閱套件中

每次成功的inspect、timeline與export執行，也會將其結果儲存在$PROJECT/.altifigence/artifacts/trace-review之下。這些命令輸出的artifact_id，就是alti trace review materialize所接受的識別碼：先是追蹤成品，再是每個--reference成品。一個套件最多可指定16個參照。

INSPECT_ID="$(alti trace inspect --project "$PROJECT" run.altrace | jq -r '.artifact.artifact_id')"
TIMELINE_ID="$(alti trace timeline --project "$PROJECT" run.altrace run.timeline | jq -r '.artifact.artifact_id')"
alti trace review materialize --project "$PROJECT" "$TIMELINE_ID" --reference "$INSPECT_ID" > "$PROJECT/package.json"
jq -r '.schema' "$PROJECT/package.json"
PACKAGE_ID="$(jq -r '.package_id' "$PROJECT/package.json")"

altifigence.trace.review-package-summary.v1

請確認結束狀態為0。package_id是trace-review:後接64個小寫十六進位字元。list最多輸出5個套件摘要，最新的在前。show輸出一份含有package_sha256與byte_length的摘要。readback會對照已儲存的成品檢查已儲存的套件，並輸出完整的套件。

alti trace review list --project "$PROJECT" | jq 'length'
alti trace review show --project "$PROJECT" "$PACKAGE_ID" | jq -r '.schema'
alti trace review readback --project "$PROJECT" "$PACKAGE_ID" \
  | jq -c '{schema, references: (.reference_artifacts | length), operation: .trace_artifact.operation_id}'

1
altifigence.trace.review-package-summary.v1
{"schema":"altifigence.trace.review-package.v1","references":1,"operation":"altifigence.trace.timeline.v1"}

當專案沒有其他檢閱套件時，第一行為1。

處理常見失敗

alti-trace會輸出error: <message>並以2結束。alti會傳回相同的結束狀態，並在stderr加上一行包含exit=2的狀態行。

追蹤路徑不存在時會輸出：

error: cannot read missing.altrace: No such file or directory (os error 2)

請列出專案目錄，並傳入相對於--project的追蹤路徑。

ls "$PROJECT"

不是追蹤的檔案會輸出下列訊息。請傳入以ALTR開頭的檔案，例如run.altrace。

printf 'this is not a trace\n' > "$PROJECT/notes.txt"
alti trace inspect --project "$PROJECT" notes.txt

error: cannot decode trace 'notes.txt': invalid .altrace magic

此專案中未儲存的識別碼，會使materialize輸出下列訊息。請從使用相同--project的inspect、timeline或export執行複製.artifact.artifact_id。

error: owned trace artifact not found

格式錯誤的識別碼、重複的識別碼，或超過16個參照，會輸出下列訊息。追蹤或參照識別碼以trace:altifigence.trace.開頭，套件識別碼則是trace-review:後接64個小寫十六進位字元。請從輸出識別碼的命令原封不動複製每個識別碼，且每個只指定一次。

error: invalid trace review request

群組或其他使用者可存取的儲存目錄，會讓每個儲存或讀取結果的trace命令輸出下列訊息。請將儲存區設為僅限您自己使用。

error: trace review store unavailable

chmod -R go-rwx "$PROJECT/.altifigence"

CLI 引擎指令