Inspecter, exporter et vérifier une trace — Altifigence Documentation

Inspectez une trace .altrace, enregistrez sa chronologie et ses exports VCD ou Chrome, et conservez les résultats dans un paquet de revue que vous pouvez rouvrir.

Utilisez Altifigence CLI 0.1.9 sous Linux pour inspecter une trace .altrace, enregistrer sa chronologie, l’exporter en événements de trace VCD ou Chrome, et conserver les résultats dans un paquet de revue que vous listez, affichez et relisez. Chaque commande exécute le moteur alti-trace livré avec alti.

Préparer un fichier de trace

Les commandes alti trace lisent des fichiers .altrace. Un fichier contient les quatre octets ALTR, deux octets de version, deux octets nuls, la longueur de l’en-tête sur 8 octets en little-endian, un en-tête JSON et la charge utile que l’en-tête décrit. Le script ci-dessous écrit une petite trace avec un cœur et cinq événements : trois MAC_COMPUTE, un DMA_READ et un API_CALL nommé step_1. Chaque ligne d’événement a la forme 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

Vérifiez que la dernière commande affiche 376 : 16 octets de préfixe, un en-tête de 136 octets qui déclare "encoding":"bincode" et "byte_length":224, et la charge utile de 224 octets.

Inspecter la trace

Exécutez alti trace inspect avec le chemin de la trace. Un chemin relatif est résolu par rapport à --project. La sortie par défaut est du JSON, et .artifact.inspect contient le résumé de la 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
  }
}

Vérifiez que le code de sortie est 0. Ajoutez --format text pour un rapport court.

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

Le JSON complet a le schéma altifigence.trace.operation.result.v1. Son .artifact.artifact_id est l’identifiant du résultat enregistré, sous la forme trace:altifigence.trace.inspect.v1: suivi du content_sha256 du résumé. inspect lit les traces dont l’encodage de la charge utile est bincode, flatbuf, flatbuf_v2 ou flat.

Enregistrer une chronologie et des exports

alti trace timeline écrit les données de la chronologie de la trace dans <OUTPUT>. alti trace export prend d’abord le format, vcd ou chrome, puis la trace et le chemin de sortie. Chaque commande écrit le fichier de sortie et affiche un JSON de résultat qui le décrit.

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 chronologie stocke 24 octets par événement suivis des noms API_CALL, de sorte que cette trace donne byte_length 140 et records_written 5. Exportez la même trace dans les deux 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"}

Vérifiez que le code de sortie est 0 pour chaque commande. run.vcd commence par une ligne $version, et run.json est un tableau JSON avec un objet par événement.

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

$version alti_core vcd_writer 0.1 $end
5

Conserver les résultats dans un paquet de revue

Chaque exécution réussie de inspect, timeline et export enregistre aussi son résultat sous $PROJECT/.altifigence/artifacts/trace-review. L’artifact_id que ces commandes affichent est l’identifiant que alti trace review materialize prend : d’abord l’artefact de trace, puis chaque artefact --reference. Un paquet peut nommer jusqu’à 16 références.

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

Vérifiez que le code de sortie est 0. package_id est trace-review: suivi de 64 caractères hexadécimaux en minuscules. list affiche au plus 5 résumés de paquets, le plus récent en premier. show affiche un résumé avec package_sha256 et byte_length. readback vérifie le paquet enregistré par rapport aux artefacts enregistrés et affiche le paquet complet.

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 première ligne est 1 lorsque le projet ne contient aucun autre paquet de revue.

Reprendre après des échecs courants

alti-trace affiche error: <message> et se termine avec 2. alti renvoie le même code de sortie et ajoute sur stderr une ligne d’état qui contient exit=2.

Un chemin de trace manquant affiche :

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

Listez le répertoire du projet et transmettez le chemin de la trace relatif à --project.

ls "$PROJECT"

Un fichier qui n’est pas une trace affiche le message ci-dessous. Transmettez un fichier qui commence par ALTR, par exemple 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 identifiant qui n’a pas été enregistré dans ce projet fait afficher à materialize le message ci-dessous. Copiez .artifact.artifact_id depuis une exécution de inspect, timeline ou export avec le même --project.

error: owned trace artifact not found

Un identifiant de forme incorrecte, un identifiant répété ou plus de 16 références affiche le message ci-dessous. Un identifiant de trace ou de référence commence par trace:altifigence.trace., et un identifiant de paquet est trace-review: suivi de 64 caractères hexadécimaux en minuscules. Copiez chaque identifiant tel quel depuis la commande qui l’a affiché et ne nommez chacun qu’une seule fois.

error: invalid trace review request

Si le groupe ou d’autres utilisateurs peuvent accéder aux répertoires du magasin, chaque commande trace qui enregistre ou lit des résultats affiche le message ci-dessous. Rendez le magasin privé pour votre utilisateur.

error: trace review store unavailable

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

Commandes CLI des moteurs