Inspeccionar, exportar y revisar una traza — Altifigence Documentation

Inspeccione una traza .altrace, guarde su línea de tiempo y las exportaciones VCD o Chrome, y conserve los resultados como un paquete de revisión que pueda volver a abrir.

Utilice Altifigence CLI 0.1.9 en Linux para inspeccionar una traza .altrace, guardar su línea de tiempo, exportarla como VCD o como eventos de traza de Chrome, y conservar los resultados en un paquete de revisión que pueda enumerar, mostrar y volver a leer. Cada comando ejecuta el motor alti-trace que se distribuye junto con alti.

Preparar un archivo de traza

Los comandos alti trace leen archivos .altrace. Un archivo contiene los cuatro bytes ALTR, dos bytes de versión, dos bytes cero, la longitud del encabezado como 8 bytes little-endian, un encabezado JSON y la carga útil que describe el encabezado. El script siguiente escribe una traza pequeña con un núcleo y cinco eventos: tres MAC_COMPUTE, un DMA_READ y un API_CALL llamado step_1. Cada línea de evento es 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

Compruebe que el último comando imprima 376: 16 bytes de prefijo, un encabezado de 136 bytes que declara "encoding":"bincode" y "byte_length":224, y la carga útil de 224 bytes.

Inspeccionar la traza

Ejecute alti trace inspect con la ruta de la traza. Una ruta relativa se resuelve con respecto a --project. La salida predeterminada es JSON, y .artifact.inspect contiene el resumen de la traza.

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

Compruebe que el estado de salida sea 0. Añada --format text para obtener un informe breve.

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

El JSON completo tiene el esquema altifigence.trace.operation.result.v1. Su .artifact.artifact_id es el identificador del resultado guardado, con la forma trace:altifigence.trace.inspect.v1: seguida del content_sha256 del resumen. inspect lee trazas cuya codificación de carga útil es bincode, flatbuf, flatbuf_v2 o flat.

Guardar una línea de tiempo y exportaciones

alti trace timeline escribe los datos de la línea de tiempo de la traza en <OUTPUT>. alti trace export toma primero el formato, vcd o chrome, y después la traza y la ruta de salida. Cada comando escribe el archivo de salida e imprime un JSON de resultado que lo describe.

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 línea de tiempo almacena 24 bytes por evento seguidos de los nombres de API_CALL, de modo que esta traza da byte_length 140 y records_written 5. Exporte la misma traza en ambos formatos.

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

Compruebe que el estado de salida de cada comando sea 0. run.vcd empieza con una línea $version, y run.json es una matriz JSON con un objeto por evento.

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

$version alti_core vcd_writer 0.1 $end
5

Conservar los resultados en un paquete de revisión

Cada ejecución correcta de inspect, timeline y export también guarda su resultado bajo $PROJECT/.altifigence/artifacts/trace-review. El artifact_id que imprimen esos comandos es el identificador que toma alti trace review materialize: primero el artefacto de la traza y, después, cada artefacto --reference. Un paquete puede nombrar hasta 16 referencias.

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

Compruebe que el estado de salida sea 0. package_id es trace-review: seguido de 64 caracteres hexadecimales en minúsculas. list imprime como máximo 5 resúmenes de paquetes, empezando por los más recientes. show imprime un resumen con package_sha256 y byte_length. readback comprueba el paquete almacenado con los artefactos guardados e imprime el paquete 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 primera línea es 1 cuando el proyecto no contiene ningún otro paquete de revisión.

Resolver fallos comunes

alti-trace imprime error: <message> y termina con 2. alti devuelve el mismo estado de salida y añade en stderr una línea de estado que incluye exit=2.

Una ruta de traza que no existe imprime:

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

Enumere el directorio del proyecto y pase la ruta de la traza relativa a --project.

ls "$PROJECT"

Un archivo que no es una traza imprime el mensaje siguiente. Pase un archivo que empiece con ALTR, como 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 identificador que no se guardó en este proyecto hace que materialize imprima el mensaje siguiente. Copie .artifact.artifact_id de una ejecución de inspect, timeline o export con el mismo --project.

error: owned trace artifact not found

Un identificador con una forma incorrecta, un identificador repetido o más de 16 referencias imprime el mensaje siguiente. Un identificador de traza o de referencia empieza con trace:altifigence.trace., y un identificador de paquete es trace-review: seguido de 64 caracteres hexadecimales en minúsculas. Copie cada identificador sin cambios del comando que lo imprimió y nombre cada uno una sola vez.

error: invalid trace review request

Si los directorios del almacén son accesibles para el grupo u otros usuarios, cada comando trace que guarda o lee resultados imprime el mensaje siguiente. Haga que el almacén sea privado para usted.

error: trace review store unavailable

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

Comandos de motor de la CLI