Kiểm tra, xuất và xem xét một trace
Kiểm tra một trace .altrace, lưu dòng thời gian cùng các bản xuất VCD hoặc Chrome của nó, và giữ kết quả thành một gói xem xét mà bạn có thể mở lại.
Dùng Altifigence CLI 0.1.9 trên Linux để kiểm tra một trace .altrace, lưu dòng thời gian của nó, xuất nó thành sự kiện trace VCD hoặc Chrome, và giữ kết quả trong một gói xem xét mà bạn có thể liệt kê, hiển thị và đọc lại. Mỗi lệnh chạy engine alti-trace được cung cấp cùng với alti.
Chuẩn bị tệp trace
Các lệnh alti trace đọc tệp .altrace. Một tệp gồm bốn byte ALTR, hai byte phiên bản, hai byte không, độ dài header dưới dạng 8 byte little-endian, một header JSON và payload mà header mô tả. Tập lệnh bên dưới ghi một trace nhỏ với một lõi và năm sự kiện: ba MAC_COMPUTE, một DMA_READ và một API_CALL tên step_1. Mỗi dòng sự kiện là 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.altraceXác nhận lệnh cuối cùng in 376: 16 byte tiền tố, header 136 byte khai báo "encoding":"bincode" và "byte_length":224, cùng payload 224 byte.
376Kiểm tra trace
Chạy alti trace inspect với đường dẫn trace. Đường dẫn tương đối được phân giải theo --project. Đầu ra mặc định là JSON, và .artifact.inspect chứa bản tóm tắt 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
}
}Xác nhận trạng thái thoát là 0. Thêm --format text để có báo cáo ngắn.
alti trace inspect --project "$PROJECT" run.altrace --format textalti-trace: run.altrace
cycles: 360
cores: 1
clock: 1000 MHz
payload: 224 bytes (bincode)
events: 5
- API_CALL: 1
- DMA_READ: 1
- MAC_COMPUTE: 3JSON đầy đủ có lược đồ altifigence.trace.operation.result.v1. .artifact.artifact_id của nó là mã định danh kết quả đã lưu, có dạng trace:altifigence.trace.inspect.v1: theo sau là content_sha256 của bản tóm tắt. inspect đọc các trace có mã hóa payload là bincode, flatbuf, flatbuf_v2 hoặc flat.
Lưu dòng thời gian và các bản xuất
alti trace timeline ghi dữ liệu dòng thời gian của trace vào <OUTPUT>. alti trace export nhận định dạng trước, vcd hoặc chrome, rồi đến trace và đường dẫn đầu ra. Mỗi lệnh ghi tệp đầu ra và in một JSON kết quả mô tả nó.
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"
}
}Dòng thời gian lưu 24 byte cho mỗi sự kiện, tiếp theo là các tên API_CALL, nên trace này cho byte_length 140 và records_written 5. Hãy xuất cùng trace đó theo cả hai định dạng.
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"}Xác nhận trạng thái thoát của từng lệnh là 0. run.vcd bắt đầu bằng một dòng $version, và run.json là mảng JSON với mỗi sự kiện một đối tượng.
head -n 1 "$PROJECT/run.vcd"
jq length "$PROJECT/run.json"$version alti_core vcd_writer 0.1 $end
5Giữ kết quả trong gói xem xét
Mỗi lần chạy inspect, timeline và export thành công cũng lưu kết quả của nó dưới $PROJECT/.altifigence/artifacts/trace-review. artifact_id mà các lệnh đó in ra là mã định danh mà alti trace review materialize nhận: trước hết là sản phẩm đầu ra trace, rồi đến từng sản phẩm đầu ra --reference. Một gói có thể nêu tối đa 16 tham chiếu.
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.v1Xác nhận trạng thái thoát là 0. package_id là trace-review: theo sau là 64 ký tự thập lục phân viết thường. list in tối đa 5 bản tóm tắt gói, mới nhất trước. show in một bản tóm tắt với package_sha256 và byte_length. readback kiểm tra gói đã lưu so với các sản phẩm đầu ra đã lưu và in toàn bộ gói.
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"}Dòng đầu tiên là 1 khi dự án không có gói xem xét nào khác.
Xử lý các lỗi thường gặp
alti-trace in error: <message> và thoát với 2. alti trả về cùng trạng thái thoát và thêm một dòng trạng thái trên stderr có chứa exit=2.
Đường dẫn trace bị thiếu in ra:
error: cannot read missing.altrace: No such file or directory (os error 2)Liệt kê thư mục dự án và truyền đường dẫn trace tương đối so với --project.
ls "$PROJECT"Một tệp không phải trace in ra thông báo bên dưới. Hãy truyền một tệp bắt đầu bằng ALTR, chẳng hạn run.altrace.
printf 'this is not a trace\n' > "$PROJECT/notes.txt"
alti trace inspect --project "$PROJECT" notes.txterror: cannot decode trace 'notes.txt': invalid .altrace magicMột mã định danh chưa được lưu trong dự án này khiến materialize in ra thông báo bên dưới. Hãy sao chép .artifact.artifact_id từ một lần chạy inspect, timeline hoặc export với cùng --project.
error: owned trace artifact not foundMã định danh sai dạng, mã định danh lặp lại hoặc nhiều hơn 16 tham chiếu sẽ in ra thông báo bên dưới. Mã định danh trace hoặc tham chiếu bắt đầu bằng trace:altifigence.trace., còn mã định danh gói là trace-review: theo sau là 64 ký tự thập lục phân viết thường. Hãy sao chép nguyên vẹn từng mã định danh từ lệnh đã in nó và chỉ nêu mỗi mã một lần.
error: invalid trace review requestNếu nhóm hoặc người dùng khác có thể truy cập các thư mục store, mọi lệnh trace lưu hoặc đọc kết quả sẽ in ra thông báo bên dưới. Hãy đặt store ở chế độ riêng tư dành cho bạn.
error: trace review store unavailablechmod -R go-rwx "$PROJECT/.altifigence"