Ispezionare, esportare ed esaminare una traccia

Ispeziona una traccia .altrace, salva la sua timeline e le esportazioni VCD o Chrome e conserva i risultati come pacchetto di revisione che puoi riaprire.

Utilizza Altifigence CLI 0.1.9 su Linux per ispezionare una traccia .altrace, salvare la sua timeline, esportarla come VCD o come eventi di traccia Chrome e conservare i risultati in un pacchetto di revisione che puoi elencare, mostrare e rileggere. Ogni comando esegue il motore alti-trace fornito accanto ad alti.

Preparare un file di traccia

I comandi alti trace leggono file .altrace. Un file contiene i quattro byte ALTR, due byte di versione, due byte zero, la lunghezza dell’intestazione come 8 byte little-endian, un’intestazione JSON e il payload che l’intestazione descrive. Lo script qui sotto scrive una piccola traccia con un core e cinque eventi: tre MAC_COMPUTE, un DMA_READ e un API_CALL chiamato step_1. Ogni riga di evento è 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

Verifica che l’ultimo comando stampi 376: 16 byte di prefisso, un’intestazione di 136 byte che dichiara "encoding":"bincode" e "byte_length":224 e il payload di 224 byte.

376

Ispezionare la traccia

Esegui alti trace inspect con il percorso della traccia. Un percorso relativo viene risolto rispetto a --project. L’output predefinito è JSON e .artifact.inspect contiene il riepilogo della traccia.

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

Verifica che il codice di uscita sia 0. Aggiungi --format text per un breve 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

Il JSON completo ha lo schema altifigence.trace.operation.result.v1. Il suo .artifact.artifact_id è l’identificatore del risultato salvato, nella forma trace:altifigence.trace.inspect.v1: seguita dal content_sha256 del riepilogo. inspect legge tracce la cui codifica del payload è bincode, flatbuf, flatbuf_v2 o flat.

Salvare una timeline e le esportazioni

alti trace timeline scrive i dati della sequenza temporale della traccia in <OUTPUT>. alti trace export richiede prima il formato, vcd o chrome, poi la traccia e il percorso di output. Ogni comando scrive il file di output e stampa un JSON di risultato che lo descrive.

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

La timeline memorizza 24 byte per evento seguiti dai nomi degli API_CALL, quindi questa traccia dà byte_length 140 e records_written 5. Esporta la stessa traccia in entrambi i formati.

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

Verifica che il codice di uscita sia 0 per ogni comando. run.vcd inizia con una riga $version e run.json è un array JSON con un oggetto per evento.

head -n 1 "$PROJECT/run.vcd"
jq length "$PROJECT/run.json"
$version alti_core vcd_writer 0.1 $end
5

Conservare i risultati in un pacchetto di revisione

Ogni esecuzione riuscita di inspect, timeline ed export salva anche il proprio risultato sotto $PROJECT/.altifigence/artifacts/trace-review. L’artifact_id stampato da questi comandi è l’identificatore che alti trace review materialize accetta: prima l’artefatto della traccia, poi ogni artefatto --reference. Un pacchetto può nominare fino a 16 riferimenti.

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

Verifica che il codice di uscita sia 0. package_id è trace-review: seguito da 64 caratteri esadecimali in minuscolo. list stampa al massimo 5 riepiloghi di pacchetto, dal più recente. show stampa un riepilogo con package_sha256 e byte_length. readback controlla il pacchetto salvato rispetto agli artefatti salvati e stampa il pacchetto completo.

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

La prima riga è 1 quando il progetto non contiene altri pacchetti di revisione.

Riprendere dopo gli errori più comuni

alti-trace stampa error: <message> e termina con 2. alti restituisce lo stesso codice di uscita e aggiunge su stderr una riga di stato che include exit=2.

Un percorso di traccia mancante stampa:

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

Elenca la cartella del progetto e passa il percorso della traccia relativo a --project.

ls "$PROJECT"

Un file che non è una traccia stampa il messaggio qui sotto. Passa un file che inizia con ALTR, ad esempio 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

Un identificatore non salvato in questo progetto fa stampare a materialize il messaggio qui sotto. Copia .artifact.artifact_id da un’esecuzione di inspect, timeline o export con lo stesso --project.

error: owned trace artifact not found

Un identificatore di forma errata, un identificatore ripetuto o più di 16 riferimenti fanno stampare il messaggio qui sotto. Un identificatore di traccia o di riferimento inizia con trace:altifigence.trace. e un identificatore di pacchetto è trace-review: seguito da 64 caratteri esadecimali in minuscolo. Copia ogni identificatore senza modifiche dal comando che lo ha stampato e nomina ciascuno una sola volta.

error: invalid trace review request

Se il gruppo o altri utenti possono accedere alle cartelle dello store, ogni comando trace che salva o legge risultati stampa il messaggio qui sotto. Rendi lo store accessibile solo a te.

error: trace review store unavailable
chmod -R go-rwx "$PROJECT/.altifigence"

Comandi dei motori CLI