Skip to content

wado-lang/wado / .claude/skills/profiling-wado-compiler

profiling-wado-compiler

Verified

Profile the native Rust `wado` binary (compile/serve/run) for host-side bottlenecks — wall time per phase with the span trace, CPU with a sampling profiler (samply, or perf where samply cannot run), memory with the span trace's RSS and valgrind DHAT. Use for native CPU or memory profiling, not guest wasm (see wado-performance for that).

FileKindSize
SKILL.mdskill md14.6 KB
scripts/analyze_dhat.tsscript5.2 KB
scripts/analyze_native_profile.tsexecutablescript16.3 KB
scripts/analyze_spans.tsexecutablescript4.0 KB
scripts/record_perf.shexecutablescript1.4 KB

scripts/analyze_native_profile.ts

View on GitHub
#!/usr/bin/env node
/**
 * Aggregate a samply profile of the native `wado` binary into Rust-level
 * bottlenecks.
 *
 * samply's `--save-only` profile is **unsymbolicated** (funcTable.name holds a
 * hex relative-virtual-address). This script:
 *
 *   1. keys every frame by (lib_index, rva) so identical raw addresses in
 *      different libraries are never merged;
 *   2. symbolicates each lib via the host's debuginfo tool:
 *        - macOS: `atos` (main executable's __TEXT base is 0x100000000,
 *          shared dylibs use base 0);
 *        - Linux: `addr2line -fC -e <path>` (PIE base is 0 because RVAs in
 *          the profile are already relative to the lib);
 *   3. weights samples by **threadCPUDelta** (real CPU), not wall-clock
 *      `weight` — otherwise parked tokio/rayon worker threads bury everything;
 *   4. reports a library breakdown, top self functions (all + main-binary
 *      only), and the syscall/alloc CPU attributed to its nearest Rust caller.
 *
 * Runs directly on Node.js >= 23.6 (type stripping is on by default):
 *   ./analyze_native_profile.ts PROFILE.json [--top N] [--binary wado]
 *                             [--main-base 0x100000000] [--symbolicator auto|atos|addr2line]
 *                             [--under REGEX] [--callers REGEX] [--thread REGEX]
 */
import { spawnSync } from "node:child_process";
import { readFileSync } from "node:fs";
import { machine } from "node:os";
import { parseArgs } from "node:util";

const HEXNAME = /^0x([0-9a-fA-F]+)$/;
const HASH_SUFFIX = /::h[0-9a-f]{16}\b/g;
const OFFSET_SUFFIX = /\s*\+\s*\d+\s*$/;
const LINE_SUFFIX = /\s*\([^()]*:\d+\)\s*$/;
// Common Rust v0/legacy mangling fragments atos leaves in place.
const DEMANGLE: [string, string][] = [
  ["$u20$", " "], ["$u7b$", "{"], ["$u7d$", "}"], ["$u5b$", "["],
  ["$u5d$", "]"], ["$LT$", "<"], ["$GT$", ">"], ["$C$", ","],
  ["$RF$", "&"], ["$LP$", "("], ["$RP$", ")"], ["..", "::"],
];

function demangle(name: string): string {
  for (const [a, b] of DEMANGLE) {
    name = name.split(a).join(b);
  }
  return name.split("_<").join("<").trim();
}

/** Collapse a symbol to its function identity (drop line/offset/hash). */
function clean(name: string): string {
  name = name.replace(LINE_SUFFIX, "");
  name = name.replace(OFFSET_SUFFIX, "");
  name = name.replace(HASH_SUFFIX, "");
  return demangle(name);
}

type Key = readonly [number, number];

/** Encode a (lib_index, rva) pair as a Map key. */
function kk(lib: number, rva: number): string {
  return `${lib} ${rva}`;
}

function hex(n: number): string {
  return "0x" + n.toString(16);
}

/** funcTable index -> (lib_index, rva) for one thread. */
function threadFuncKeys(thread: any): Key[] {
  const strings = thread.stringArray;
  const ftab = thread.funcTable;
  const rtab = thread.resourceTable;
  const keys: Key[] = [];
  for (let i = 0; i < ftab.length; i++) {
    const res = ftab.resource[i];
    let lib = -1;
    if (
      res != null && res >= 0 && res < rtab.length && rtab.lib[res] != null
    ) {
      lib = rtab.lib[res];
    }
    const m = HEXNAME.exec(strings[ftab.name[i]]);
    keys.push([lib, m ? parseInt(m[1], 16) : -1]);
  }
  return keys;
}

/**
 * Run a symbolicator and return its stdout lines. `maxBuffer` is unbounded
 * because the default 1 MiB truncates silently, dropping every address past
 * the cut back to a raw `[lib]+0x…` frame.
 */
function runSymbolicator(
  cmd: string, args: string[], input?: string,
): string[] {
  let proc;
  try {
    proc = spawnSync(cmd, args, {
      input, encoding: "utf8", timeout: 180_000, maxBuffer: Infinity,
    });
  } catch (e) {
    console.error(`${cmd} failed: ${e}`);
    return [];
  }
  // A symbolicator that ran and failed reports through `status` / `signal`,
  // leaving `error` unset; parsing its stdout anyway would bury the failure
  // under the raw-address fallback every unresolved frame takes.
  const failure = proc.error ?? (proc.signal
    ? `killed by ${proc.signal}`
    : proc.status ? `exit ${proc.status}` : null);
  if (failure) {
    console.error(`${cmd} failed: ${failure}`);
    return [];
  }
  const lines = (proc.stdout ?? "").split("\n");
  if (lines.length && lines[lines.length - 1] === "") lines.pop();
  return lines;
}

function symbolicateAtos(
  path: string, base: number, rvas: number[], libName: string, arch: string,
): Map<number, string> {
  const addrs = rvas.map((r) => hex(base + r));
  const lines = runSymbolicator(
    "atos", ["-o", path, "-arch", arch, "-l", hex(base), ...addrs],
  );
  while (lines.length < rvas.length) lines.push("");
  const out = new Map<number, string>();
  for (let i = 0; i < rvas.length; i++) {
    const r = rvas[i];
    let s = (lines[i] ?? "").trim();
    if (!s || s.startsWith("0x")) {
      s = `[${libName}]+${hex(r)}`;
    }
    out.set(r, clean(s));
  }
  return out;
}

/**
 * `addr2line -fC -e <path>` over stdin; output is paired (func, file:line).
 *
 * PIE binaries on Linux store RVAs directly in the profile — no base offset
 * to add. `-i` (inlined frames) is intentionally omitted because addr2line
 * does not emit a per-input separator with `-i`, so the output cannot be
 * reliably split back into addresses. The outermost frame is the one that
 * matches the hot self-CPU bucket, which is what we want.
 */
function symbolicateAddr2line(
  path: string, rvas: number[], libName: string,
): Map<number, string> {
  const addrs = rvas.map((r) => hex(r));
  const lines = runSymbolicator(
    "addr2line", ["-fC", "-e", path], addrs.join("\n") + "\n",
  );
  const out = new Map<number, string>();
  for (let idx = 0; idx < rvas.length; idx++) {
    const r = rvas[idx];
    const func = (idx * 2 < lines.length ? lines[idx * 2] : "").trim();
    const fileline = (idx * 2 + 1 < lines.length ? lines[idx * 2 + 1] : "")
      .trim();
    if (!func || func === "??") {
      out.set(r, `[${libName}]+${hex(r)}`);
    } else {
      // Match the atos output shape so downstream filters
      // like `(in wado)` work on both platforms.
      out.set(r, clean(`${func} (in ${libName}) (${fileline})`));
    }
  }
  return out;
}

/** (lib_index, rva) -> cleaned symbol, batched per lib. */
function symbolicate(
  profile: any, binary: string, mainBase: number, arch: string,
  symbolicator: string,
): Map<string, string> {
  const libs = profile.libs;
  const byLib = new Map<number, Set<number>>();
  for (const thread of profile.threads) {
    for (const [lib, rva] of threadFuncKeys(thread)) {
      let set = byLib.get(lib);
      if (!set) byLib.set(lib, (set = new Set()));
      set.add(rva);
    }
  }

  const out = new Map<string, string>();
  for (const [lib, rvaSet] of byLib) {
    const rvas = [...rvaSet].sort((a, b) => a - b);
    if (lib < 0 || lib >= libs.length) {
      for (const r of rvas) out.set(kk(lib, r), "[unknown]");
      continue;
    }
    const meta = libs[lib];
    const path = meta.path ?? meta.name;
    // `[vdso]` and friends name a mapping, not a file: there is nothing for a
    // symbolicator to open, and asking would report a failure on every run.
    if (path.startsWith("[")) {
      for (const r of rvas) out.set(kk(lib, r), `[${meta.name}]+${hex(r)}`);
      continue;
    }
    let sym: Map<number, string>;
    if (symbolicator === "atos") {
      const base = meta.name === binary ? mainBase : 0;
      sym = symbolicateAtos(path, base, rvas, meta.name, arch);
    } else if (symbolicator === "addr2line") {
      sym = symbolicateAddr2line(path, rvas, meta.name);
    } else {
      console.error(`unknown symbolicator: ${symbolicator}`);
      process.exit(1);
    }
    for (const [r, s] of sym) out.set(kk(lib, r), s);
  }
  return out;
}

function detectSymbolicator(explicit: string): string {
  if (explicit !== "auto") return explicit;
  if (process.platform === "darwin") return "atos";
  return "addr2line";
}

function main(): void {
  const { values, positionals } = parseArgs({
    allowPositionals: true,
    options: {
      top: { type: "string", default: "30" },
      binary: { type: "string", default: "wado" },
      "main-base": { type: "string", default: "0x100000000" },
      arch: { type: "string", default: machine() },
      symbolicator: { type: "string", default: "auto" },
      under: { type: "string" },
      callers: { type: "string" },
      thread: { type: "string" },
    },
  });

  if (positionals.length < 1) {
    console.error(
      "usage: analyze_native_profile.ts PROFILE.json [--top N] " +
        "[--binary wado] [--main-base 0x100000000] " +
        "[--symbolicator auto|atos|addr2line] [--under REGEX] [--callers REGEX] [--thread REGEX]",
    );
    process.exit(2);
  }
  const regexArg = (name: string): RegExp | null => {
    const pattern = values[name] as string | undefined;
    if (pattern == null) return null;
    try {
      return new RegExp(pattern);
    } catch (e) {
      console.error(`argument --${name}: invalid pattern: ${(e as Error).message}`);
      process.exit(2);
    }
  };
  const under = regexArg("under");
  const callers = regexArg("callers");
  const threadFilter = regexArg("thread");

  const profilePath = positionals[0];
  const top = parseInt(values.top as string, 10);
  const binary = values.binary as string;
  const mainBase = parseInt(values["main-base"] as string, 16);
  const arch = values.arch as string;
  const symChoice = values.symbolicator as string;
  if (!["auto", "atos", "addr2line"].includes(symChoice)) {
    console.error(
      `argument --symbolicator: invalid choice: '${symChoice}' ` +
        "(choose from 'auto', 'atos', 'addr2line')",
    );
    process.exit(2);
  }

  const symbolicator = detectSymbolicator(symChoice);
  const profile = JSON.parse(readFileSync(profilePath, "utf8"));
  if (threadFilter != null) {
    profile.threads = profile.threads.filter((t: any) => threadFilter.test(t.name));
  }
  const libs = profile.libs;
  const keyname = symbolicate(profile, binary, mainBase, arch, symbolicator);

  const selfBy = new Map<string, number>();
  const inclBy = new Map<string, number>();
  const libSelf = new Map<string, number>();
  const attr = new Map<string, number>(); // syscall/alloc leaf -> nearest Rust caller
  const allocBy = new Map<string, number>(); // allocation cost -> requesting caller
  const calleesBy = new Map<string, number>(); // --under: the matched frame's callee
  const callersBy = new Map<string, number>(); // --callers: the matched frame's callers
  const inBin = `(in ${binary})`;
  let allocTotal = 0.0;
  let total = 0.0;
  let usedWallclock = false;

  // Entry into the allocator: every frame below one is allocation cost.
  const ALLOC_ENTRY =
    /mimalloc|MiMalloc|GlobalAlloc|__rust_(alloc|dealloc|realloc)|alloc::alloc::(alloc|dealloc|realloc)|__libc_(malloc|free|calloc|realloc)/;
  // Plumbing between the request and the entry: the container whose growth
  // allocated names its element type but not the site, so credit the frame
  // above it. mimalloc's own internals carry no DWARF and surface as bare
  // `[bin]+0x…`.
  const ALLOC_PLUMBING =
    /alloc::alloc::|alloc::vec::|alloc::raw_vec::|RawVec|RawTable|hashbrown::|indexmap::|::reserve|finish_grow|\+0x/;

  const add = (m: Map<string, number>, k: string, w: number) =>
    m.set(k, (m.get(k) ?? 0) + w);

  for (const thread of profile.threads) {
    const keys = threadFuncKeys(thread);
    const frFunc = thread.frameTable.func;
    const stFrame = thread.stackTable.frame;
    const stPrefix = thread.stackTable.prefix;
    const samples = thread.samples;
    const stacks = samples.stack;
    let weights = samples.threadCPUDelta;
    if (weights == null) {
      weights = samples.weight;
      usedWallclock = true;
    }

    const key = (stackIdx: number): Key => keys[frFunc[stFrame[stackIdx]]];
    const name = (stackIdx: number): string => {
      const [lib, rva] = key(stackIdx);
      return keyname.get(kk(lib, rva))!;
    };
    const libName = (stackIdx: number): string => {
      const li = key(stackIdx)[0];
      return li >= 0 && li < libs.length ? libs[li].name : "[unknown]";
    };

    for (let i = 0; i < stacks.length; i++) {
      const leaf = stacks[i];
      if (leaf == null) continue;
      const w = weights == null ? 1.0 : (weights[i] || 0);
      total += w;
      add(selfBy, name(leaf), w);
      add(libSelf, libName(leaf), w);
      // inclusive: dedup by name per sample (avoids >100% on recursion)
      const seen = new Set<string>();
      let cur: number | null = leaf;
      while (cur != null) {
        const n = name(cur);
        if (!seen.has(n)) {
          seen.add(n);
          add(inclBy, n, w);
        }
        cur = stPrefix[cur];
      }
      // Every sample crossing an allocator entry, credited above the outermost
      // one — the code that asked for the memory, not the plumbing between.
      {
        let node: number | null = leaf;
        let requester: string | null = null;
        let sawEntry = false;
        while (node != null) {
          const n = name(node);
          if (ALLOC_ENTRY.test(n)) {
            sawEntry = true;
            requester = null; // outermost entry wins
          } else if (sawEntry && requester == null && !ALLOC_PLUMBING.test(n)) {
            requester = n;
          }
          node = stPrefix[node];
        }
        if (sawEntry) {
          add(allocBy, requester ?? "[no caller above allocator]", w);
          allocTotal += w;
        }
      }
      // Under the outermost frame matching `under`, credit the frame it called:
      // which child of a pass the pass's time goes to.
      if (under != null) {
        let callee = "[self]";
        let matched = false;
        for (let node: number | null = leaf, below: string | null = null; node != null; node = stPrefix[node]) {
          const n = name(node);
          if (under.test(n)) {
            matched = true;
            callee = below ?? "[self]";
          }
          below = n;
        }
        if (matched) add(calleesBy, callee, w);
      }
      // Above the outermost frame matching `callers`, credit its three nearest
      // callers: which pass a shared helper's time is spent for.
      if (callers != null) {
        let chain: string[] | null = null;
        for (let node: number | null = leaf; node != null; node = stPrefix[node]) {
          const n = name(node);
          if (callers.test(n)) chain = [];
          else if (chain != null && chain.length < 3) chain.push(n);
        }
        if (chain != null) {
          const label = chain.map((n) => n.replace(` ${inBin}`, "")).join("  <  ");
          add(callersBy, label || "[root]", w);
        }
      }
      // attribute non-main-binary leaf CPU to nearest main-binary caller
      if (libName(leaf) !== binary) {
        cur = leaf;
        let caller: string | null = null;
        while (cur != null) {
          if (libName(cur) === binary) {
            caller = name(cur);
            break;
          }
          cur = stPrefix[cur];
        }
        add(attr, caller ?? "[no Rust ancestor]", w);
      }
    }
  }

  if (total === 0) {
    console.log("No samples found.");
    return;
  }
  if (usedWallclock) {
    console.log(
      "WARNING: no threadCPUDelta; weighting by wall-clock samples " +
        "(idle/parked threads will dominate).\n",
    );
  }

  const pct = (v: number): string =>
    (v / total * 100).toFixed(2).padStart(6) + "%";

  const show = (
    title: string, table: Map<string, number>,
    pred?: (k: string) => boolean,
  ) => {
    console.log(`\n=== ${title} ===`);
    const rows = [...table].filter(([k]) => pred == null || pred(k));
    rows.sort((a, b) => b[1] - a[1]);
    for (const [k, v] of rows.slice(0, top)) {
      console.log(`${pct(v)}  ${k}`);
    }
  };

  console.log(`symbolicator = ${symbolicator}`);
  console.log(`total CPU weight = ${total.toFixed(0)}`);
  console.log("\n=== CPU by library (self) ===");
  const libRows = [...libSelf].sort((a, b) => b[1] - a[1]);
  for (const [k, v] of libRows) {
    console.log(`${pct(v)}  ${k}`);
  }
  show("Top SELF — all", selfBy);
  show(`Top SELF — ${binary} (Rust) only`, selfBy, (n) => n.includes(inBin));
  show(
    `Top INCLUSIVE — ${binary} (Rust) only`, inclBy, (n) => n.includes(inBin),
  );
  show(
    "Syscall/alloc CPU attributed to nearest Rust caller", attr,
    (n) => n.includes(inBin),
  );
  show(
    `Allocation cost by requesting caller (${pct(allocTotal)} of total)`, allocBy,
  );
  if (under != null) show(`Callees of the outermost frame matching /${under.source}/`, calleesBy);
  if (callers != null) show(`Callers of the outermost frame matching /${callers.source}/`, callersBy);
}

main();
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall