Einen Trace untersuchen, exportieren und prüfen

Verwenden Sie Altifigence CLI 0.1.9 unter Linux, um einen .altrace-Trace zu untersuchen, seine Timeline zu speichern, ihn als VCD oder Chrome-Trace-Ereignisse zu exportieren und die Ergebnisse in einem Review-Paket aufzubewahren, das Sie auflisten, anzeigen und zurücklesen. Jeder Befehl führt die Engine alti-trace aus, die neben alti ausgeliefert wird.

Eine Trace-Datei vorbereiten

Die Befehle alti trace lesen .altrace-Dateien. Eine Datei enthält die vier Bytes ALTR, zwei Versionsbytes, zwei Nullbytes, die Länge des Headers als 8 Little-Endian-Bytes, einen JSON-Header und die Nutzdaten, die der Header beschreibt. Das folgende Skript schreibt einen kleinen Trace mit einem Kern und fünf Ereignissen: dreimal MAC_COMPUTE, einmal DMA_READ und einmal API_CALL mit dem Namen step_1. Jede Ereigniszeile hat die Form 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

Prüfen Sie, dass der letzte Befehl 376 ausgibt: 16 Präfix-Bytes, ein Header mit 136 Bytes, der "encoding":"bincode" und "byte_length":224 deklariert, und die Nutzdaten mit 224 Bytes.

376

Den Trace untersuchen

Führen Sie alti trace inspect mit dem Pfad des Traces aus. Ein relativer Pfad wird gegen --project aufgelöst. Die Ausgabe ist standardmäßig JSON, und .artifact.inspect enthält die Zusammenfassung des Traces.

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

Prüfen Sie, dass der Exit-Status 0 ist. Fügen Sie --format text für einen kurzen Bericht hinzu.

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

Das vollständige JSON hat das Schema altifigence.trace.operation.result.v1. Dessen .artifact.artifact_id ist die Kennung des gespeicherten Ergebnisses in der Form trace:altifigence.trace.inspect.v1:, gefolgt vom content_sha256 der Zusammenfassung. inspect liest Traces, deren Nutzdatenkodierung bincode, flatbuf, flatbuf_v2 oder flat ist.

Eine Timeline und Exporte speichern

alti trace timeline schreibt die Timeline-Daten des Trace nach <OUTPUT>. alti trace export erwartet zuerst das Format, vcd oder chrome, dann den Trace und den Ausgabepfad. Jeder Befehl schreibt die Ausgabedatei und gibt ein Ergebnis-JSON aus, das sie beschreibt.

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

Die Timeline speichert 24 Bytes pro Ereignis, gefolgt von den API_CALL-Namen, daher ergibt dieser Trace byte_length 140 und records_written 5. Exportieren Sie denselben Trace in beiden Formaten.

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

Prüfen Sie bei jedem Befehl, dass der Exit-Status 0 ist. run.vcd beginnt mit einer $version-Zeile, und run.json ist ein JSON-Array mit einem Objekt pro Ereignis.

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

$version alti_core vcd_writer 0.1 $end
5

Ergebnisse in einem Review-Paket aufbewahren

Jeder erfolgreiche Lauf von inspect, timeline und export speichert sein Ergebnis außerdem unter $PROJECT/.altifigence/artifacts/trace-review. Die artifact_id, die diese Befehle ausgeben, ist die Kennung, die alti trace review materialize erwartet: zuerst das Trace-Artefakt, dann jedes --reference-Artefakt. Ein Paket kann bis zu 16 Referenzen nennen.

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

Prüfen Sie, dass der Exit-Status 0 ist. package_id ist trace-review:, gefolgt von 64 hexadezimalen Zeichen in Kleinbuchstaben. list gibt höchstens 5 Paketzusammenfassungen aus, die neueste zuerst. show gibt eine Zusammenfassung mit package_sha256 und byte_length aus. readback prüft das gespeicherte Paket anhand der gespeicherten Artefakte und gibt das vollständige Paket aus.

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

Die erste Zeile ist 1, wenn das Projekt kein anderes Review-Paket enthält.

Nach häufigen Fehlern fortfahren

alti-trace gibt error: <message> aus und endet mit 2. alti gibt denselben Exit-Status zurück und fügt auf stderr eine Statuszeile hinzu, die exit=2 enthält.

Bei einem fehlenden Trace-Pfad wird Folgendes ausgegeben:

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

Listen Sie das Projektverzeichnis auf und übergeben Sie den Trace-Pfad relativ zu --project.

ls "$PROJECT"

Bei einer Datei, die kein Trace ist, wird die folgende Meldung ausgegeben. Übergeben Sie eine Datei, die mit ALTR beginnt, etwa 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

Bei einer Kennung, die in diesem Projekt nicht gespeichert wurde, gibt materialize die folgende Meldung aus. Kopieren Sie .artifact.artifact_id aus einem Lauf von inspect, timeline oder export mit demselben --project.

error: owned trace artifact not found

Bei einer Kennung mit falscher Form, einer wiederholten Kennung oder mehr als 16 Referenzen wird die folgende Meldung ausgegeben. Eine Trace- oder Referenzkennung beginnt mit trace:altifigence.trace., und eine Paketkennung ist trace-review:, gefolgt von 64 hexadezimalen Zeichen in Kleinbuchstaben. Kopieren Sie jede Kennung unverändert aus dem Befehl, der sie ausgegeben hat, und nennen Sie jede nur einmal.

error: invalid trace review request

Bei Speicherverzeichnissen, auf die die Gruppe oder andere Benutzer zugreifen können, wird die folgende Meldung für jeden trace-Befehl ausgegeben, der Ergebnisse speichert oder liest. Machen Sie den Speicher privat für Ihren Benutzer.

error: trace review store unavailable

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

CLI-Engine-Befehle