Menginspeksi, mengekspor, dan meninjau trace

Inspeksi trace .altrace, simpan timeline serta ekspor VCD atau Chrome-nya, dan simpan hasilnya sebagai paket tinjauan yang dapat Anda buka kembali.

Gunakan Altifigence CLI 0.1.9 di Linux untuk menginspeksi satu trace .altrace, menyimpan timeline-nya, mengekspornya sebagai VCD atau event trace Chrome, dan menyimpan hasilnya dalam paket tinjauan yang dapat Anda lihat daftarnya, tampilkan, dan baca kembali. Setiap perintah menjalankan mesin alti-trace yang dikirim bersama alti.

Menyiapkan file trace

Perintah alti trace membaca file .altrace. File berisi empat byte ALTR, dua byte versi, dua byte nol, panjang header sebagai 8 byte little-endian, header JSON, dan payload yang dijelaskan header. Skrip di bawah menulis trace kecil dengan satu core dan lima event: tiga MAC_COMPUTE, satu DMA_READ, dan satu API_CALL bernama step_1. Setiap baris event adalah 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

Pastikan perintah terakhir mencetak 376: 16 byte awalan, header 136 byte yang mendeklarasikan "encoding":"bincode" dan "byte_length":224, serta payload 224 byte.

Menginspeksi trace

Jalankan alti trace inspect dengan jalur trace. Jalur relatif diselesaikan terhadap --project. Output bawaannya adalah JSON, dan .artifact.inspect memuat ringkasan trace.

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

Pastikan status keluar adalah 0. Tambahkan --format text untuk laporan singkat.

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 lengkap memiliki skema altifigence.trace.operation.result.v1. .artifact.artifact_id-nya adalah pengenal hasil yang tersimpan, dalam bentuk trace:altifigence.trace.inspect.v1: diikuti content_sha256 dari ringkasan. inspect membaca trace yang encoding payload-nya adalah bincode, flatbuf, flatbuf_v2, atau flat.

Menyimpan timeline dan ekspor

alti trace timeline menulis data lini masa trace ke <OUTPUT>. alti trace export menerima format lebih dulu, vcd atau chrome, lalu trace dan jalur output. Setiap perintah menulis file output dan mencetak JSON hasil yang menjelaskannya.

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

Timeline menyimpan 24 byte per event diikuti nama API_CALL, sehingga trace ini menghasilkan byte_length 140 dan records_written 5. Ekspor trace yang sama dalam kedua format.

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

Pastikan status keluar adalah 0 untuk setiap perintah. run.vcd diawali baris $version, dan run.json adalah array JSON dengan satu objek per event.

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

$version alti_core vcd_writer 0.1 $end
5

Menyimpan hasil dalam paket tinjauan

Setiap eksekusi inspect, timeline, dan export yang berhasil juga menyimpan hasilnya di bawah $PROJECT/.altifigence/artifacts/trace-review. artifact_id yang dicetak perintah-perintah itu adalah pengenal yang diterima alti trace review materialize: artefak trace lebih dulu, lalu setiap artefak --reference. Sebuah paket dapat menyebutkan hingga 16 referensi.

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

Pastikan status keluar adalah 0. package_id adalah trace-review: diikuti 64 karakter heksadesimal huruf kecil. list mencetak paling banyak 5 ringkasan paket, yang terbaru lebih dulu. show mencetak satu ringkasan dengan package_sha256 dan byte_length. readback memeriksa paket tersimpan terhadap artefak tersimpan dan mencetak paket lengkap.

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

Baris pertama adalah 1 jika proyek tidak memiliki paket tinjauan lain.

Mengatasi kegagalan umum

alti-trace mencetak error: <message> dan keluar dengan 2. alti mengembalikan status keluar yang sama dan menambahkan baris status di stderr yang menyertakan exit=2.

Jalur trace yang tidak ada mencetak:

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

Tampilkan daftar direktori proyek dan berikan jalur trace relatif terhadap --project.

ls "$PROJECT"

File yang bukan trace mencetak pesan di bawah. Berikan file yang diawali ALTR, seperti 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

Pengenal yang tidak disimpan di proyek ini membuat materialize mencetak pesan di bawah. Salin .artifact.artifact_id dari eksekusi inspect, timeline, atau export dengan --project yang sama.

error: owned trace artifact not found

Pengenal dengan bentuk yang salah, pengenal yang berulang, atau lebih dari 16 referensi mencetak pesan di bawah. Pengenal trace atau referensi diawali trace:altifigence.trace., dan pengenal paket adalah trace-review: diikuti 64 karakter heksadesimal huruf kecil. Salin setiap pengenal tanpa perubahan dari perintah yang mencetaknya dan sebutkan masing-masing sekali.

error: invalid trace review request

Jika grup atau pengguna lain dapat mengakses direktori store, setiap perintah trace yang menyimpan atau membaca hasil mencetak pesan di bawah. Jadikan store hanya dapat diakses oleh Anda.

error: trace review store unavailable

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

Perintah engine CLI