トレースを検査、エクスポート、レビューする

.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は同じ終了ステータスを返し、exit=2を含むステータス行をstderrに追加します。

トレースのパスが見つからない場合は、次が出力されます。

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

プロジェクトのディレクトリを一覧表示し、--projectからの相対パスでトレースのパスを指定してください。

ls "$PROJECT"

トレースではないファイルを指定すると、以下のメッセージが出力されます。run.altraceのように、ALTRで始まるファイルを指定してください。

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 エンジンコマンド