███████╗██████╗  █████╗  █████╗ 
██╔════╝██╔══██╗██╔══██╗██╔══██╗
███████╗██████╔╝███████║███████║
╚════██║██╔═══╝ ██╔══██║██╔══██║
███████║██║     ██║  ██║██║  ██║
╚══════╝╚═╝     ╚═╝  ╚═╝╚═╝  ╚═╝

Stack Profile for Agentic Analysis

Make profiling data accessible to AI agents

SPAA is a file format and toolset designed to convert raw profiler output into a structured, queryable format that AI agents can analyze using simple command-line tools.

Get StartedRead the Spec

Install with Cargo

cargo install spaa

The Problem

Raw profiler output is problematic for AI analysis

Raw TracesSPAA
Huge files (100MB+ for less than 1 minute of profiling)Pre-aggregated stacks reduce size 10-100x
Binary or tool-specific formatsNDJSON - each line is self-contained JSON
Requires specialized parsersQueryable with grep, jq, head, tail
Redundant data (same stack thousands of times)Each unique stack appears once with weights
Implicit semanticsExplicit metrics, frame order, and event types

Design Philosophy

Progressive Disclosure

SPAA files are designed so agents can incrementally access exactly what they need — without loading the entire file into context.

head -1

Understand the profiler, metrics, and file structure from just the first line (header).

grep 'type'

Filter for specific record types — stacks, frames, threads, or samples.

jq

Extract exactly what you need with powerful JSON queries and transformations.

Features

Built for modern profiling workflows

Multi-Tool Support

Convert from DTrace, Chrome DevTools, perf, and more. Unified format for all your profiling data.

Memory Profiling

Track allocations, deallocations, and memory leaks with dedicated metrics like live_bytes and alloc_count.

Content-Addressable Stacks

Deterministic stack IDs enable diffing across profile runs for regression detection.

Lossless & Streamable

Preserves full fidelity of profiler data. NDJSON format enables single-pass streaming parsers.

For AI Agents

Install the SPAA Agent Skill

Give your AI coding agent the ability to analyze performance profiles with a single command.

npx skills add andrewimm/spaa
Works with Claude Code
Works with Cursor
Works with skills-compatible agents

Example

See what SPAA looks like

Header Record

{
  "type": "header",
  "format": "spaa",
  "version": "1.0",
  "source_tool": "dtrace",           // Tool that generated the original profile
  "frame_order": "leaf_to_root",     // How frames[] are ordered in stack records
  "events": [{
    "name": "profile-997",           // Referenced by stack.context.event
    "kind": "timer",
    "sampling": {
      "mode": "frequency",
      "primary_metric": "samples",   // Authoritative weight for this event
      "frequency_hz": 997
    }
  }]
}

Stack Record

{
  "type": "stack",
  "id": "0xabc123",                  // Content-addressable ID for cross-file diffing
  "frames": [101, 77, 42],           // References frame.id records (leaf first)
  "context": {
    "event": "profile-997",          // References header.events[].name
    "tid": 1234                      // References thread.tid (if present)
  },
  "weights": [{
    "metric": "samples",             // Must match event's primary_metric
    "value": 847
  }]
}

Frame Record

{
  "type": "frame",
  "id": 101,                         // Referenced by stack.frames[]
  "func": "mycrate::parse::parse_file",
  "dso": 12,                         // References dso.id record
  "ip": "0x401234",                  // Instruction pointer address
  "srcline": "src/parse.rs:214",     // Source location (file:line)
  "kind": "user"                     // user | kernel | native | jit | interpreted
}

Ready to get started?

Install SPAA and start converting your profiling data into an AI-friendly format today.

Installation GuideView on GitHub