Inspect, export, and review a trace

Use Altifigence CLI 0.1.9 on Linux to inspect one .altrace trace, save its timeline, export it as VCD or Chrome trace events, and keep the results in a review package that you list, show, and read back. Each command runs the alti-trace engine that ships beside alti.

Prepare a trace file

alti trace commands read .altrace files. A file holds the four bytes ALTR, two version bytes, two zero bytes, the header length as 8 little-endian bytes, a JSON header, and the payload that the header describes. The script below writes a small trace with one core and five events: three MAC_COMPUTE, one DMA_READ, and one API_CALL named step_1. Each event line is 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

Require the last command to print 376: 16 prefix bytes, a 136-byte header that declares "encoding":"bincode" and "byte_length":224, and the 224-byte payload.

376

Inspect the trace

Run alti trace inspect with the trace path. A relative path is resolved against --project. The default output is JSON, and .artifact.inspect holds the trace summary.

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

Require exit status 0. Add --format text for a short report.

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

The full JSON has the schema altifigence.trace.operation.result.v1. Its .artifact.artifact_id is the saved result identifier, in the form trace:altifigence.trace.inspect.v1: followed by the content_sha256 of the summary. inspect reads traces whose payload encoding is bincode, flatbuf, flatbuf_v2, or flat.

Save a timeline and exports

alti trace timeline writes the trace's timeline data to <OUTPUT>. alti trace export takes the format first, vcd or chrome, then the trace and the output path. Each command writes the output file and prints a result JSON that describes it.

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

The timeline stores 24 bytes per event followed by the API_CALL names, so this trace gives byte_length 140 and records_written 5. Export the same trace in both formats.

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

Require exit status 0 for each command. run.vcd starts with a $version line, and run.json is a JSON array with one object per event.

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

$version alti_core vcd_writer 0.1 $end
5

Keep results in a review package

Every successful inspect, timeline, and export run also saves its result under $PROJECT/.altifigence/artifacts/trace-review. The artifact_id those commands print is the identifier that alti trace review materialize takes: the trace artifact first, then each --reference artifact. A package can name up to 16 references.

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

Require exit status 0. package_id is trace-review: followed by 64 lowercase hexadecimal characters. list prints at most 5 package summaries, newest first. show prints one summary with package_sha256 and byte_length. readback checks the stored package against the saved artifacts and prints the full package.

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

The first line is 1 when the project holds no other review package.

Recover from common failures

alti-trace prints error: <message> and exits 2. alti returns the same exit status and adds a status line on stderr that includes exit=2.

A missing trace path prints:

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

List the project directory and pass the trace path relative to --project.

ls "$PROJECT"

A file that is not a trace prints the message below. Pass a file that starts with ALTR, such as 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

An identifier that was not saved in this project makes materialize print the message below. Copy .artifact.artifact_id from an inspect, timeline, or export run with the same --project.

error: owned trace artifact not found

An identifier of the wrong shape, a repeated identifier, or more than 16 references prints the message below. A trace or reference identifier starts with trace:altifigence.trace., and a package identifier is trace-review: followed by 64 lowercase hexadecimal characters. Copy each identifier unchanged from the command that printed it and name each one once.

error: invalid trace review request

If group or other users can access the store directories, every trace command that saves or reads results prints the message below. Make the store private to you.

error: trace review store unavailable

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

CLI engine commands