트레이스 검사, 내보내기 및 검토하기

.altrace 트레이스를 검사하고, 타임라인과 VCD 또는 Chrome 내보내기를 저장하고, 결과를 다시 열 수 있는 검토 패키지로 보관합니다.

Linux에서 Altifigence CLI 0.1.9를 사용해 .altrace 트레이스 하나를 검사하고, 타임라인을 저장하고, VCD 또는 Chrome 트레이스 이벤트로 내보내고, 결과는 목록 조회, 표시, 다시 읽기를 할 수 있는 검토 패키지에 보관하세요. 각 명령은 alti와 함께 설치되는 alti-trace 엔진을 실행합니다.

트레이스 파일 준비하기

alti trace 명령은 .altrace 파일을 읽습니다. 파일에는 ALTR 네 바이트, 버전 바이트 두 개, 값이 영인 바이트 두 개, 리틀 엔디언 8바이트로 된 헤더 길이, JSON 헤더, 헤더가 설명하는 페이로드가 들어 있습니다. 아래 스크립트는 코어 하나와 이벤트 다섯 개로 이루어진 작은 트레이스를 씁니다. 이벤트는 MAC_COMPUTE 세 개, DMA_READ 한 개, step_1이라는 이름의 API_CALL 한 개입니다. 각 이벤트 줄의 형식은 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

마지막 명령이 376을 출력하는지 확인하세요. 이 값은 16바이트 접두부, "encoding":"bincode"와 "byte_length":224를 선언하는 136바이트 헤더, 224바이트 페이로드로 구성됩니다.

트레이스 검사하기

트레이스 경로와 함께 alti trace inspect를 실행하세요. 상대 경로는 --project 기준으로 해석됩니다. 기본 출력은 JSON이며, .artifact.inspect에 트레이스 요약이 들어 있습니다.

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

종료 상태가 0인지 확인하세요. 짧은 보고서를 보려면 --format text를 추가하세요.

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

전체 JSON의 스키마는 altifigence.trace.operation.result.v1입니다. .artifact.artifact_id는 저장된 결과 식별자이며, trace:altifigence.trace.inspect.v1: 뒤에 요약의 content_sha256이 이어지는 형식입니다. inspect는 페이로드 인코딩이 bincode, flatbuf, flatbuf_v2 또는 flat인 트레이스를 읽습니다.

타임라인과 내보내기 저장하기

alti trace timeline은 트레이스의 타임라인 데이터를 <OUTPUT>에 씁니다. alti trace export는 형식(vcd 또는 chrome)을 먼저 받고, 그다음 트레이스와 출력 경로를 받습니다. 각 명령은 출력 파일을 쓰고, 그 파일을 설명하는 결과 JSON을 출력합니다.

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

타임라인은 이벤트당 24바이트를 저장하고 그 뒤에 API_CALL 이름을 저장하므로, 이 트레이스에서는 byte_length가 140이고 records_written이 5입니다. 같은 트레이스를 두 형식으로 모두 내보내세요.

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

각 명령의 종료 상태가 0인지 확인하세요. run.vcd는 $version 줄로 시작하고, run.json은 이벤트당 객체 하나로 이루어진 JSON 배열입니다.

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

$version alti_core vcd_writer 0.1 $end
5

검토 패키지에 결과 보관하기

성공한 모든 inspect, timeline, export 실행은 결과를 $PROJECT/.altifigence/artifacts/trace-review 아래에도 저장합니다. 이 명령들이 출력하는 artifact_id는 alti trace review materialize가 받는 식별자입니다. 트레이스 산출물이 먼저 오고, 그다음에 각 --reference 산출물이 옵니다. 패키지는 최대 16개의 참조를 지정할 수 있습니다.

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

종료 상태가 0인지 확인하세요. package_id는 trace-review: 뒤에 소문자 십육진수 문자 64개가 이어지는 값입니다. list는 최대 5개의 패키지 요약을 최신순으로 출력합니다. show는 package_sha256과 byte_length가 포함된 요약 하나를 출력합니다. readback은 저장된 패키지를 저장된 산출물과 대조해 확인하고 전체 패키지를 출력합니다.

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

프로젝트에 다른 검토 패키지가 없으면 첫 줄은 1입니다.

일반적인 실패 해결하기

alti-trace는 error: <message> 줄을 출력하고 2로 종료합니다. alti는 같은 종료 상태를 반환하고, stderr에 exit=2가 포함된 상태 줄을 추가합니다.

존재하지 않는 트레이스 경로는 다음을 출력합니다:

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

프로젝트 디렉터리의 목록을 확인하고 --project 기준 상대 경로로 트레이스 경로를 전달하세요.

ls "$PROJECT"

트레이스가 아닌 파일은 아래 메시지를 출력합니다. run.altrace처럼 ALTR로 시작하는 파일을 전달하세요.

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

이 프로젝트에 저장되지 않은 식별자를 사용하면 materialize가 아래 메시지를 출력합니다. 같은 --project로 실행한 inspect, timeline 또는 export에서 .artifact.artifact_id를 복사하세요.

error: owned trace artifact not found

형식이 잘못된 식별자, 중복된 식별자 또는 16개를 초과하는 참조는 아래 메시지를 출력합니다. 트레이스 또는 참조 식별자는 trace:altifigence.trace.로 시작하고, 패키지 식별자는 trace-review: 뒤에 소문자 십육진수 문자 64개가 이어집니다. 각 식별자는 출력한 명령에서 그대로 복사하고 한 번씩만 지정하세요.

error: invalid trace review request

그룹이나 다른 사용자가 저장소 디렉터리에 접근할 수 있으면 결과를 저장하거나 읽는 모든 trace 명령이 아래 메시지를 출력합니다. 저장소를 본인 전용으로 만드세요.

error: trace review store unavailable

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

CLI 엔진 명령어