Inspecionar, exportar e revisar um trace — Altifigence Documentation

Inspecione um trace .altrace, salve sua linha do tempo e as exportações VCD ou Chrome e guarde os resultados como um pacote de revisão que você pode reabrir.

Use o Altifigence CLI 0.1.9 no Linux para inspecionar um trace .altrace, salvar sua linha do tempo, exportá-lo como VCD ou como eventos de trace do Chrome e guardar os resultados em um pacote de revisão que você pode listar, mostrar e ler de volta. Cada comando executa o mecanismo alti-trace que acompanha alti.

Preparar um arquivo de trace

Os comandos alti trace leem arquivos .altrace. Um arquivo contém os quatro bytes ALTR, dois bytes de versão, dois bytes zero, o comprimento do cabeçalho como 8 bytes little-endian, um cabeçalho JSON e a carga útil que o cabeçalho descreve. O script abaixo grava um trace pequeno com um núcleo e cinco eventos: três MAC_COMPUTE, um DMA_READ e um API_CALL chamado step_1. Cada linha de 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

Exija que o último comando imprima 376: 16 bytes de prefixo, um cabeçalho de 136 bytes que declara "encoding":"bincode" e "byte_length":224, e a carga útil de 224 bytes.

Inspecionar o trace

Execute alti trace inspect com o caminho do trace. Um caminho relativo é resolvido em relação a --project. A saída padrão é JSON, e .artifact.inspect contém o resumo do 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
  }
}

Exija o status de saída 0. Adicione --format text para obter um relatório curto.

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

O JSON completo tem o esquema altifigence.trace.operation.result.v1. Seu .artifact.artifact_id é o identificador do resultado salvo, no formato trace:altifigence.trace.inspect.v1: seguido do content_sha256 do resumo. inspect lê traces cuja codificação de carga útil é bincode, flatbuf, flatbuf_v2 ou flat.

Salvar uma linha do tempo e exportações

alti trace timeline grava os dados da linha do tempo do trace em <OUTPUT>. alti trace export recebe primeiro o formato, vcd ou chrome, depois o trace e o caminho de saída. Cada comando grava o arquivo de saída e imprime um JSON de resultado que o descreve.

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

A linha do tempo armazena 24 bytes por evento seguidos dos nomes de API_CALL, portanto este trace resulta em byte_length 140 e records_written 5. Exporte o mesmo trace nos dois 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"}

Exija o status de saída 0 em cada comando. run.vcd começa com uma linha $version, e run.json é um array JSON com um objeto por evento.

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

$version alti_core vcd_writer 0.1 $end
5

Guardar os resultados em um pacote de revisão

Toda execução bem-sucedida de inspect, timeline e export também salva o resultado em $PROJECT/.altifigence/artifacts/trace-review. O artifact_id que esses comandos imprimem é o identificador que alti trace review materialize recebe: primeiro o artefato do trace, depois cada artefato --reference. Um pacote pode nomear até 16 referências.

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

Exija o status de saída 0. package_id é trace-review: seguido de 64 caracteres hexadecimais em minúsculas. list imprime no máximo 5 resumos de pacotes, do mais recente para o mais antigo. show imprime um resumo com package_sha256 e byte_length. readback verifica o pacote armazenado em relação aos artefatos salvos e imprime o pacote 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"}

A primeira linha é 1 quando o projeto não contém nenhum outro pacote de revisão.

Resolver falhas comuns

alti-trace imprime error: <message> e termina com 2. alti retorna o mesmo status de saída e adiciona em stderr uma linha de status que inclui exit=2.

Um caminho de trace inexistente imprime:

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

Liste o diretório do projeto e passe o caminho do trace relativo a --project.

ls "$PROJECT"

Um arquivo que não é um trace imprime a mensagem abaixo. Passe um arquivo que comece com 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

Um identificador que não foi salvo neste projeto faz materialize imprimir a mensagem abaixo. Copie .artifact.artifact_id de uma execução de inspect, timeline ou export com o mesmo --project.

error: owned trace artifact not found

Um identificador com formato incorreto, um identificador repetido ou mais de 16 referências imprime a mensagem abaixo. Um identificador de trace ou de referência começa com trace:altifigence.trace., e um identificador de pacote é trace-review: seguido de 64 caracteres hexadecimais em minúsculas. Copie cada identificador sem alterações do comando que o imprimiu e nomeie cada um uma só vez.

error: invalid trace review request

Se os diretórios do armazenamento forem acessíveis ao grupo ou a outros usuários, todo comando trace que salva ou lê resultados imprime a mensagem abaixo. Torne o armazenamento privado para você.

error: trace review store unavailable

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

Comandos de engine da CLI