检查、导出和审查跟踪

检查.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字节的载荷。

376

检查跟踪

请使用跟踪路径运行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 引擎命令