feat(desktop): add native memory breakdown to heap captures (#58311)

This commit is contained in:
Luke Parker
2026-10-23 12:48:10 +10:00
committed by GitHub
Unverified
parent f523f77138
commit 5f79a2aaf7
15 changed files with 657 additions and 52 deletions
+1 -1
View File
@@ -132,7 +132,7 @@ opencode debug heap-dump
It discovers the already-running service (never starts or replaces one), calls `POST /api/debug/heap-dump`, waits until the file is complete, and prints its server-local path. Pass `--server <url>` (with `OPENCODE_PASSWORD`) for a server started with `serve`, and `--directory <dir>` to write somewhere other than the server's log directory (the server creates it; a server that predates the option ignores it and the CLI warns). A 404 means the running server predates the endpoint.
For desktop memory, run **Capture heap snapshots** from the desktop command palette (`packages/gui-extensions/src/debug/main.ts`). It writes `~/Downloads/opencode-heap-<time>/` with the desktop's own (local) server, which writes straight into the folder, every app window renderer, and the Electron main process, plus a `manifest.json` (PIDs and `app.getAppMetrics()`) written last. In a dev desktop build you can drive it over CDP (`OPENCODE_DESKTOP_REMOTE_DEBUGGING_PORT`, default 9222): press `Control+Shift+P`, type `heap snapshots`, press Enter.
For desktop memory, run **Capture heap snapshots** from the desktop command palette (`packages/gui-extensions/src/debug/main.ts`). It writes `~/Downloads/opencode-heap-<time>/` with the desktop's own (local) server, which writes straight into the folder, every app window renderer, and the Electron main process. Heap snapshots only hold GC-managed objects, so it also records Chromium's memory-infra dump (`memory-infra.json`, open in Perfetto) and summarizes it per process and allocator in `memory.json` (MiB: `malloc`, `partition_alloc`, `cc/tile_memory`, `gpu`, `v8`, …), next to each window's DOM size and decoded images and the server's `process.memoryUsage()`. `manifest.json` (PIDs, `app.getAppMetrics()` before and after) is written last. Start with `memory.json` when a process is larger than its heap snapshot. In a dev desktop build you can drive it over CDP (`OPENCODE_DESKTOP_REMOTE_DEBUGGING_PORT`, default 9222): press `Control+Shift+P`, type `heap snapshots`, press Enter.
The Unix `SIGUSR1` listener in `packages/cli/src/heap.ts` shares the same writer (`packages/util/src/heap-snapshot.ts`) and is still useful for a process that is not an HTTP server, such as a TUI client:
+11 -1
View File
@@ -2270,7 +2270,17 @@ export interface VcsApi<E = never> {
}
export type DebugHeapDumpInput = { readonly directory?: string | undefined }
export type DebugHeapDumpOutput = { readonly path: string; readonly pid: number }
export type DebugHeapDumpOutput = {
readonly path: string
readonly pid: number
readonly memory: {
readonly rss: number
readonly heapTotal: number
readonly heapUsed: number
readonly external: number
readonly arrayBuffers: number
}
}
export type DebugHeapDumpOperation<E = never> = (input?: DebugHeapDumpInput) => Effect.Effect<DebugHeapDumpOutput, E>
export type DebugLocationListOutput = ReadonlyArray<Location.PublicRef>
@@ -6021,7 +6021,11 @@ export type VcsDiffOutput = { location: LocationPublicRef; data: Array<FileDiffI
export type DebugHeapDumpInput = { readonly directory?: { readonly directory?: string | undefined }["directory"] }
export type DebugHeapDumpOutput = { path: string; pid: number }
export type DebugHeapDumpOutput = {
path: string
pid: number
memory: { rss: number; heapTotal: number; heapUsed: number; external: number; arrayBuffers: number }
}
export type DebugLocationListOutput = Array<LocationPublicRef>
+133 -31
View File
@@ -1,10 +1,12 @@
import { app, type BrowserWindow } from "electron"
import { mkdir, writeFile } from "node:fs/promises"
import { app, contentTracing, screen, type BrowserWindow } from "electron"
import { Schema } from "effect"
import { mkdir, readFile, writeFile } from "node:fs/promises"
import path from "node:path"
import { writeHeapSnapshot } from "node:v8"
import { getHeapSpaceStatistics, getHeapStatistics, writeHeapSnapshot } from "node:v8"
import type { MainSetup } from "../sdk/main"
import { HeapSnapshots } from "./contract"
import type definition from "./index"
import { summarize, traceConfig } from "./memory-infra"
import { captureServer } from "./server-heap"
/** A desktop process the manifest lists: the file written, or why there is none. */
@@ -16,6 +18,38 @@ type Snapshot = { readonly process: "main" | "window"; readonly pid: number; rea
/** The last capture; the next one starts after it settles. */
type Queue = { tail: Promise<unknown> }
/** What a window's page holds, read from inside it. */
const PageStats = Schema.Struct({
elements: Schema.Number,
images: Schema.Struct({ count: Schema.Number, decodedMiB: Schema.Number }),
canvases: Schema.Struct({ count: Schema.Number, MiB: Schema.Number }),
svgUses: Schema.Number,
devicePixelRatio: Schema.Number,
viewport: Schema.Struct({ width: Schema.Number, height: Schema.Number }),
jsHeap: Schema.optional(
Schema.Struct({ usedJSHeapSize: Schema.Number, totalJSHeapSize: Schema.Number, jsHeapSizeLimit: Schema.Number }),
),
})
const decodePageStats = Schema.decodeUnknownPromise(PageStats)
// Runs in the app window. Pixel sizes estimate decoded memory at 4 bytes per pixel.
const pageStatsScript = `(() => {
const mib = (bytes) => Math.round(bytes / 1048576 * 10) / 10
const images = [...document.images]
const canvases = [...document.querySelectorAll("canvas")]
const memory = performance.memory
return {
elements: document.getElementsByTagName("*").length,
images: { count: images.length, decodedMiB: mib(images.reduce((t, i) => t + i.naturalWidth * i.naturalHeight * 4, 0)) },
canvases: { count: canvases.length, MiB: mib(canvases.reduce((t, c) => t + c.width * c.height * 4, 0)) },
svgUses: document.getElementsByTagName("use").length,
devicePixelRatio: window.devicePixelRatio,
viewport: { width: innerWidth, height: innerHeight },
jsHeap: memory && { usedJSHeapSize: memory.usedJSHeapSize, totalJSHeapSize: memory.totalJSHeapSize, jsHeapSizeLimit: memory.jsHeapSizeLimit },
}
})()`
const setup: MainSetup<typeof definition> = (ctx) => {
const queue: Queue = { tail: Promise.resolve() }
@@ -29,15 +63,28 @@ const setup: MainSetup<typeof definition> = (ctx) => {
await mkdir(directory, { recursive: true, mode: 0o700 })
ctx.log.write("info", "capturing heap snapshots", { directory })
// Measurements first: writing a heap snapshot raises the memory of the process it serializes.
const before = {
metrics: app.getAppMetrics(),
mainMemory: process.memoryUsage(),
mainHeap: getHeapStatistics(),
mainHeapSpaces: getHeapSpaceStatistics(),
system: process.getSystemMemoryInfo(),
}
const native = await recordNative(directory)
const windows = ctx.windows.list()
const pages = await Promise.all(windows.map((window) => describeWindow(window)))
// The server is another process, so it serializes its heap while the windows do. Windows go one at a time: a
// snapshot can double a process's memory, and a leaking app may not have room for every window at once. Main goes
// last: writing its own heap blocks the loop that receives the others.
const [serverSnapshot, windows] = await Promise.all([
const [serverSnapshot, windowSnapshots] = await Promise.all([
captureServer(ctx.serverEndpoints.get("sidecar"), directory, ctx.scope.signal),
(async () => {
const list: Snapshot[] = []
for (const window of ctx.windows.list()) list.push(await captureWindow(window, directory))
for (const window of windows) list.push(await captureWindow(window, directory))
return list
})(),
@@ -50,34 +97,43 @@ const setup: MainSetup<typeof definition> = (ctx) => {
(error: Error): Snapshot => ({ process: "main", pid: process.pid, error: error.message }),
)
const snapshots = [serverSnapshot, ...windows, main]
const snapshots = [serverSnapshot, ...windowSnapshots, main]
const gpu = await app.getGPUInfo("basic").catch((error: Error) => ({ error: error.message }))
// One readable answer to "where is the memory", per process, in MiB.
await write(directory, "memory.json", {
unit: "MiB",
native: "summary" in native ? native.summary : native,
server: "error" in serverSnapshot || !serverSnapshot.memory ? undefined : mibs(serverSnapshot.memory),
pages,
note: "native: Chromium's memory-infra dump per process, before the heap snapshots. Some allocators overlap: cc, skia, gpu and web_cache report memory that malloc, discardable or shared_memory also count. pages: what each app window's page held. server: the server's process.memoryUsage().",
})
await write(directory, "gpu.json", gpu)
// Written last, so a script can wait for it.
await writeFile(
path.join(directory, "manifest.json"),
JSON.stringify(
{
created: new Date().toISOString(),
app: {
name: app.getName(),
version: app.getVersion(),
packaged: app.isPackaged,
platform: process.platform,
arch: process.arch,
versions: process.versions,
},
snapshots,
// Per-process memory as the OS sees it: a process that grows while its heap does not leaks native memory.
metrics: app.getAppMetrics(),
metricsMemoryUnit: "KiB",
mainMemory: process.memoryUsage(),
},
null,
2,
),
{ mode: 0o600 },
)
const complete = snapshots.every((snapshot) => !("error" in snapshot))
await write(directory, "manifest.json", {
created: new Date().toISOString(),
app: {
name: app.getName(),
version: app.getVersion(),
packaged: app.isPackaged,
uptimeSeconds: process.uptime(),
platform: process.platform,
arch: process.arch,
versions: process.versions,
},
files: {
"memory.json": "Where the memory is, per process, in MiB. Start here.",
"memory-infra.json": "Chromium's raw memory dump trace. Open it in https://ui.perfetto.dev.",
"gpu.json": "The GPU and driver.",
"*.heapsnapshot": "Heap snapshots. Open them in the Memory panel of Chrome DevTools.",
},
snapshots,
// Per-process memory as the OS sees it: a process that grows while its heap does not leaks native memory.
metricsMemoryUnit: "KiB",
before,
after: { metrics: app.getAppMetrics(), mainMemory: process.memoryUsage() },
})
const complete = snapshots.every((snapshot) => !("error" in snapshot)) && !("error" in native)
ctx.log.write(complete ? "info" : "warn", "heap snapshots captured", { directory, complete })
return { directory, complete }
@@ -94,6 +150,44 @@ const setup: MainSetup<typeof definition> = (ctx) => {
})
}
// Chromium's own breakdown of every process's memory: what a heap snapshot cannot show (images, layout, compositor
// layers, GPU). Fails when something else is tracing, such as DevTools recording a performance profile.
async function recordNative(directory: string) {
const file = path.join(directory, "memory-infra.json")
return (
contentTracing
.startRecording(traceConfig)
// The first detailed dump arrives within a periodic interval of starting.
.then(() => new Promise((resolve) => setTimeout(resolve, 2_500)))
.then(() => contentTracing.stopRecording(file))
.then(async () => ({ file: path.basename(file), summary: summarize(await readFile(file, "utf8")) }))
.catch((error: Error) => ({ error: error.message }))
)
}
async function describeWindow(window: BrowserWindow) {
const contents = window.webContents
// A hung or busy renderer never answers, and the snapshots wait for this step, so give up after a few seconds.
const page = await Promise.race([
contents.executeJavaScript(pageStatsScript).then(decodePageStats),
new Promise<never>((_, reject) =>
setTimeout(() => reject(new Error("The window did not answer within 3 seconds.")), 3_000),
),
]).catch((error: Error) => ({ error: error.message }))
return {
window: window.id,
pid: contents.getOSProcessId(),
title: window.getTitle(),
contentSize: window.getContentSize(),
scaleFactor: screen.getDisplayMatching(window.getBounds()).scaleFactor,
zoomFactor: contents.getZoomFactor(),
page,
}
}
function captureWindow(window: BrowserWindow, directory: string) {
const contents = window.webContents
const pid = contents.getOSProcessId()
@@ -105,4 +199,12 @@ function captureWindow(window: BrowserWindow, directory: string) {
)
}
function write<Value>(directory: string, file: string, value: Value) {
return writeFile(path.join(directory, file), JSON.stringify(value, null, 2), { mode: 0o600 })
}
function mibs(bytes: Readonly<Record<string, number>>) {
return Object.fromEntries(Object.entries(bytes).map(([key, value]) => [key, Math.round((value / 1048576) * 10) / 10]))
}
export default setup
@@ -0,0 +1,89 @@
import { expect, test } from "bun:test"
import { summarize } from "./memory-infra"
const hex = (mib: number) => Math.round(mib * 1024 * 1024).toString(16)
const size = (mib: number) => ({ type: "scalar", units: "bytes", value: hex(mib) })
// Shaped like Electron's trace: totals and allocators arrive in separate events per dump id, the browser splits its
// allocators over two events, and shared `global/…` entries carry no attrs.
const trace = {
traceEvents: [
{ pid: 10, ph: "M", name: "process_name", args: { name: "Renderer" } },
{ pid: 10, ph: "M", name: "process_labels", args: { labels: "OpenCode" } },
{ pid: 20, ph: "M", name: "process_name", args: { name: "Browser" } },
{ pid: 10, ph: "X", name: "unrelated", args: { anything: [1, 2] } },
// An earlier dump that a later one supersedes.
{ pid: 10, ph: "v", id: "0x0", args: { dumps: { process_totals: { private_footprint_bytes: hex(100) } } } },
{ pid: 10, ph: "v", id: "0x0", args: { dumps: { allocators: { malloc: { attrs: { size: size(90) } } } } } },
{ pid: 10, ph: "v", id: "0x1", args: { dumps: { process_totals: { private_footprint_bytes: hex(900) } } } },
{
pid: 10,
ph: "v",
id: "0x1",
args: {
dumps: {
allocators: {
// Effective size wins over size: memory shared with another allocator is counted once.
cc: { attrs: { size: size(500), effective_size: size(400) } },
"cc/tile_memory": { attrs: { effective_size: size(400) } },
partition_alloc: { attrs: { size: size(300) } },
"partition_alloc/partitions/layout": { attrs: { size: size(250) } },
"partition_alloc/partitions/layout/deeper": { attrs: { size: size(250) } },
"partition_alloc/partitions/tiny": { attrs: { size: size(0.5) } },
"shared_memory/ABC": { attrs: { size: size(5) } },
"global/123": {},
},
},
},
},
{ pid: 20, ph: "v", id: "0x1", args: { dumps: { process_totals: { private_footprint_bytes: hex(200) } } } },
{ pid: 20, ph: "v", id: "0x1", args: { dumps: { allocators: { malloc: { attrs: { size: size(50) } } } } } },
{ pid: 20, ph: "v", id: "0x1", args: { dumps: { allocators: { v8: { attrs: { size: size(30) } } } } } },
// The recording stopped while the next dump was arriving: only the renderer reported, so 0x1 stays the answer.
{ pid: 10, ph: "v", id: "0x2", args: { dumps: { process_totals: { private_footprint_bytes: hex(950) } } } },
{ pid: 10, ph: "v", id: "0x2", args: { dumps: { allocators: { malloc: { attrs: { size: size(950) } } } } } },
{ pid: 20, ph: "v", id: "0x2", args: { dumps: { process_totals: { private_footprint_bytes: hex(210) } } } },
],
}
test("summarizes each process's latest complete dump, largest first", () => {
expect(summarize(JSON.stringify(trace))).toEqual([
{
pid: 10,
name: "Renderer",
labels: "OpenCode",
totals: { privateFootprint: 900, resident: undefined },
allocators: { cc: 400, partition_alloc: 300 },
detail: { "cc/tile_memory": 400, "partition_alloc/partitions/layout": 250 },
},
{
pid: 20,
name: "Browser",
labels: undefined,
totals: { privateFootprint: 200, resident: undefined },
allocators: { malloc: 50, v8: 30 },
detail: {},
},
])
})
test("falls back to the latest dump with allocators when no dump reached every process", () => {
const partial = {
traceEvents: [
{ pid: 10, ph: "v", id: "0x0", args: { dumps: { allocators: { malloc: { attrs: { size: size(10) } } } } } },
{ pid: 20, ph: "v", id: "0x0", args: { dumps: { process_totals: { private_footprint_bytes: hex(20) } } } },
],
}
expect(
summarize(JSON.stringify(partial)).map((item) => [item.pid, item.totals.privateFootprint, item.allocators]),
).toEqual([
[20, 20, {}],
[10, undefined, { malloc: 10 }],
])
})
test("a trace without memory dumps summarizes to nothing", () => {
expect(summarize(JSON.stringify({ traceEvents: [{ pid: 1, ph: "M", name: "process_name" }] }))).toEqual([])
})
@@ -0,0 +1,159 @@
import { Option, Schema } from "effect"
/** The trace config that makes Chromium dump every process's memory, broken down by allocator. */
export const traceConfig = {
included_categories: ["disabled-by-default-memory-infra"],
excluded_categories: ["*"],
memory_dump_config: { triggers: [{ mode: "detailed", periodic_interval_ms: 1000 }] },
}
/** One Chromium process in the summary. Sizes are MiB. */
export type ProcessMemory = {
readonly pid: number
/** Chromium's name for the process, e.g. `Browser`, `Renderer`, `GPU Process`. */
readonly name?: string
/** What the process shows, as Chromium labels it. */
readonly labels?: string
/** What the OS charges the process: Chromium's private footprint and resident set. */
readonly totals: { readonly privateFootprint?: number; readonly resident?: number }
/**
* Each allocator's effective size (shared memory counted once, with its owner), largest first: `malloc`, `partition_alloc`, `blink_gc`, `v8`, `skia`, `cc`, `gpu`,
* `discardable`, `web_cache`, `font_caches`… Some overlap: `cc`, `skia`, `gpu` and `web_cache` report memory that
* `malloc`, `discardable` or `shared_memory` also count.
*/
readonly allocators: Readonly<Record<string, number>>
/** Every sub-allocator of at least 1 MiB, up to three levels deep, e.g. `partition_alloc/partitions/layout`. */
readonly detail: Readonly<Record<string, number>>
}
const Size = Schema.Struct({ value: Schema.String })
const Event = Schema.Struct({
pid: Schema.Number,
ph: Schema.String,
id: Schema.optional(Schema.String),
name: Schema.optional(Schema.String),
args: Schema.optional(
Schema.Struct({
name: Schema.optional(Schema.String),
labels: Schema.optional(Schema.String),
dumps: Schema.optional(
Schema.Struct({
process_totals: Schema.optional(
Schema.Struct({
private_footprint_bytes: Schema.optional(Schema.String),
resident_set_bytes: Schema.optional(Schema.String),
}),
),
allocators: Schema.optional(
Schema.Record(
Schema.String,
Schema.Struct({
// Shared `global/…` entries carry only a guid.
attrs: Schema.optional(
Schema.Struct({ size: Schema.optional(Size), effective_size: Schema.optional(Size) }),
),
}),
),
),
}),
),
}),
),
})
// Electron writes `{ traceEvents: [...] }`; events of other shapes are skipped one by one.
const decodeTrace = Schema.decodeUnknownSync(
Schema.fromJsonString(Schema.Struct({ traceEvents: Schema.Array(Schema.Unknown) })),
)
const decodeEvent = Schema.decodeUnknownOption(Event)
/**
* Summarizes a memory-infra trace: for each process, the last detailed dump's totals and allocator sizes.
*
* @param json - The trace file's text, as `contentTracing.stopRecording` wrote it.
* @returns One entry per process that dumped, largest private footprint first.
*/
export function summarize(json: string): ProcessMemory[] {
const events = decodeTrace(json).traceEvents.flatMap((value) => Option.toArray(decodeEvent(value)))
const names = new Map(
events.flatMap((event) =>
event.ph === "M" && event.name === "process_name" ? [[event.pid, event.args?.name]] : [],
),
)
const labels = new Map(
events.flatMap((event) =>
event.ph === "M" && event.name === "process_labels" ? [[event.pid, event.args?.labels]] : [],
),
)
// Each periodic dump shares an id across processes, and a process reports its totals and its allocators in separate
// events (the browser in two). Stopping the recording can cut into the last dump, so use the latest one every
// process reported both for, else the latest with any allocators.
const dumps = events.flatMap((event) =>
event.ph === "v" && event.args?.dumps ? [{ ...event, dumps: event.args.dumps }] : [],
)
const pids = [...new Set(dumps.map((event) => event.pid))]
const complete = [...new Set(dumps.map((event) => event.id))].findLast((id) =>
pids.every((pid) => {
const own = dumps.filter((event) => event.id === id && event.pid === pid)
return own.some((event) => event.dumps.allocators) && own.some((event) => event.dumps.process_totals)
}),
)
const latest = complete ?? dumps.findLast((event) => event.dumps.allocators)?.id
const current = dumps.filter((event) => event.id === latest)
return [...new Set(current.map((event) => event.pid))]
.map((pid): ProcessMemory => {
const own = current.filter((event) => event.pid === pid)
// Effective size counts memory shared between allocators once, with its owner.
const sizes = own.flatMap((event) =>
Object.entries(event.dumps.allocators ?? {}).flatMap(([key, value]) => {
const size = value.attrs?.effective_size ?? value.attrs?.size
return size ? [[key, mib(parseInt(size.value, 16))] as const] : []
}),
)
const totals = own.find((event) => event.dumps.process_totals)?.dumps.process_totals
return {
pid,
name: names.get(pid),
labels: labels.get(pid),
totals: {
privateFootprint: hexMib(totals?.private_footprint_bytes),
resident: hexMib(totals?.resident_set_bytes),
},
allocators: Object.fromEntries(
sizes.filter(([key, size]) => !key.includes("/") && size > 0).sort((a, b) => b[1] - a[1]),
),
detail: Object.fromEntries(
sizes
// `global/<guid>` and `shared_memory/<guid>` name buffers by id, which says nothing on its own.
.filter(
([key, size]) =>
key.includes("/") && key.split("/").length <= 3 && size >= 1 && !/^(global|shared_memory)\//.test(key),
)
.sort((a, b) => b[1] - a[1]),
),
}
})
.sort((a, b) => (b.totals.privateFootprint ?? 0) - (a.totals.privateFootprint ?? 0))
}
function hexMib(value: string | undefined) {
return value === undefined ? undefined : mib(parseInt(value, 16))
}
function mib(bytes: number) {
return Math.round((bytes / 1024 / 1024) * 10) / 10
}
@@ -10,6 +10,7 @@ beforeAll(() => GlobalRegistrator.unregister())
afterAll(() => GlobalRegistrator.register())
test("asks the server to write into the folder, and records where an older server wrote instead", async () => {
const memory = { rss: 5, heapTotal: 4, heapUsed: 3, external: 2, arrayBuffers: 1 }
const directory = path.join(os.tmpdir(), "opencode-heap-capture")
const requests: string[] = []
@@ -24,7 +25,10 @@ test("asks the server to write into the folder, and records where an older serve
// The first answer is a current server's; the second is one that predates `directory` and used its log folder.
const folder = requests.length === 1 ? (url.searchParams.get("directory") ?? "") : path.join(os.tmpdir(), "log")
return Response.json({ path: path.join(folder, "heap-42-1.heapsnapshot"), pid: 42 })
const snapshot = { path: path.join(folder, "heap-42-1.heapsnapshot"), pid: 42 }
// An older server also leaves out its memory.
return Response.json(requests.length === 1 ? { ...snapshot, memory } : snapshot)
},
})
@@ -33,7 +37,7 @@ test("asks the server to write into the folder, and records where an older serve
const old = await captureServer(endpoint, directory, AbortSignal.timeout(10_000))
expect({ current, old, requests }).toEqual({
current: { process: "server", pid: 42, file: "heap-42-1.heapsnapshot" },
current: { process: "server", pid: 42, file: "heap-42-1.heapsnapshot", memory },
old: { process: "server", pid: 42, path: path.join(os.tmpdir(), "log", "heap-42-1.heapsnapshot") },
requests: [
`POST /api/debug/heap-dump ${directory} Basic secret`,
@@ -3,16 +3,21 @@ import { Predicate } from "effect"
import path from "node:path"
import type { ServerEndpoint } from "../sdk/main"
type Memory = Readonly<Record<"rss" | "heapTotal" | "heapUsed" | "external" | "arrayBuffers", number>>
/**
* What the manifest records about the desktop server's snapshot.
* - `file`: the server wrote it into the folder.
* - `path`: the server wrote it elsewhere, because it predates choosing a directory and used its log directory.
* Snapshots are large, so it is not moved or copied.
* - `error`: nothing was captured.
*
* `memory` is the server's `process.memoryUsage()` in bytes just before the snapshot; servers released before it was
* added leave it out.
*/
export type ServerSnapshot =
| { readonly process: "server"; readonly pid: number; readonly file: string }
| { readonly process: "server"; readonly pid: number; readonly path: string }
| { readonly process: "server"; readonly pid: number; readonly file: string; readonly memory?: Memory }
| { readonly process: "server"; readonly pid: number; readonly path: string; readonly memory?: Memory }
| { readonly process: "server"; readonly error: string }
/**
@@ -36,8 +41,8 @@ export async function captureServer(
(snapshot): ServerSnapshot =>
// The server joins the directory and file name, so the same join recognizes a snapshot it wrote there.
path.join(directory, path.basename(snapshot.path)) === snapshot.path
? { process: "server", pid: snapshot.pid, file: path.basename(snapshot.path) }
: { process: "server", pid: snapshot.pid, path: snapshot.path },
? { process: "server", pid: snapshot.pid, file: path.basename(snapshot.path), memory: snapshot.memory }
: { process: "server", pid: snapshot.pid, path: snapshot.path, memory: snapshot.memory },
(error: Error): ServerSnapshot => ({
process: "server",
error: unsupported(error)
+64 -1
View File
@@ -13452,9 +13452,72 @@
},
"pid": {
"type": "integer"
},
"memory": {
"type": "object",
"properties": {
"rss": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"enum": ["Infinity", "-Infinity", "NaN"]
}
]
},
"heapTotal": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"enum": ["Infinity", "-Infinity", "NaN"]
}
]
},
"heapUsed": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"enum": ["Infinity", "-Infinity", "NaN"]
}
]
},
"external": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"enum": ["Infinity", "-Infinity", "NaN"]
}
]
},
"arrayBuffers": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"enum": ["Infinity", "-Infinity", "NaN"]
}
]
}
},
"required": ["rss", "heapTotal", "heapUsed", "external", "arrayBuffers"],
"additionalProperties": false,
"description": "The server process's memory in bytes, read just before the snapshot (Node's process.memoryUsage()). rss covers native memory the snapshot cannot show."
}
},
"required": ["path", "pid"],
"required": ["path", "pid", "memory"],
"additionalProperties": false
}
}
+14 -1
View File
@@ -16,7 +16,20 @@ export const DebugGroup = HttpApiGroup.make("server.debug")
}),
),
}),
success: Schema.Struct({ path: Schema.String, pid: Schema.Int }),
success: Schema.Struct({
path: Schema.String,
pid: Schema.Int,
memory: Schema.Struct({
rss: Schema.Number,
heapTotal: Schema.Number,
heapUsed: Schema.Number,
external: Schema.Number,
arrayBuffers: Schema.Number,
}).annotate({
description:
"The server process's memory in bytes, read just before the snapshot (Node's process.memoryUsage()). rss covers native memory the snapshot cannot show.",
}),
}),
error: [InvalidRequestError, UnknownError],
}).annotateMerge(
OpenApi.annotations({
+14 -1
View File
@@ -50,7 +50,11 @@ it.live(
const responses = yield* Effect.all([api.dump(), api.dump()], { concurrency: "unbounded" })
expect(responses.map((response) => response.status)).toEqual([200, 200])
const results = yield* Effect.promise(() =>
Promise.all(responses.map((response): Promise<{ path: string; pid: number }> => response.json())),
Promise.all(
responses.map(
(response): Promise<{ path: string; pid: number; memory: Record<string, number> }> => response.json(),
),
),
)
expect(new Set(results.map((result) => result.path)).size).toBe(2)
expect((yield* Effect.promise(() => fs.readdir(api.log))).toSorted()).toEqual(
@@ -58,6 +62,15 @@ it.live(
)
for (const result of results) {
expect(result.pid).toBe(process.pid)
// Read before the snapshot: the process's footprint beyond the heap the file holds.
expect(Object.keys(result.memory).toSorted()).toEqual([
"arrayBuffers",
"external",
"heapTotal",
"heapUsed",
"rss",
])
expect(result.memory.rss).toBeGreaterThan(result.memory.heapUsed)
expect(path.dirname(result.path)).toBe(api.log)
expect(path.basename(result.path)).toStartWith(`heap-${process.pid}-`)
if (process.platform !== "win32")
+17 -5
View File
@@ -7,9 +7,10 @@ import path from "node:path"
const lock = Semaphore.makeUnsafe(1)
/**
* Writes a V8 heap snapshot of this process into `directory` and returns once the file is complete.
* Blocks the event loop while the heap serializes. The file can contain secrets, so it is created
* owner-only before the runtime writes into it.
* Writes a V8 heap snapshot of this process into `directory` and returns once the file is complete, with the
* process's memory just before the snapshot: the snapshot holds only the garbage-collected heap, and writing it
* raises the process's memory. Blocks the event loop while the heap serializes. The file can contain secrets, so it
* is created owner-only before the runtime writes into it.
*/
export const write = Effect.fn("HeapSnapshot.write")(
function* (directory: string) {
@@ -21,10 +22,21 @@ export const write = Effect.fn("HeapSnapshot.write")(
const handle = await open(file, "wx", 0o600)
await handle.close()
})
yield* Effect.logInfo("writing heap snapshot", { path: file })
const memory = yield* Effect.sync(() => process.memoryUsage())
yield* Effect.logInfo("writing heap snapshot", { path: file, rss: memory.rss, heapUsed: memory.heapUsed })
yield* Effect.try(() => v8.writeHeapSnapshot(file))
yield* Effect.logInfo("heap snapshot written", { path: file })
return { path: file, pid: process.pid }
return {
path: file,
pid: process.pid,
memory: {
rss: memory.rss,
heapTotal: memory.heapTotal,
heapUsed: memory.heapUsed,
external: memory.external,
arrayBuffers: memory.arrayBuffers,
},
}
},
(effect) => lock.withPermit(effect),
)
+64 -1
View File
@@ -13452,9 +13452,72 @@
},
"pid": {
"type": "integer"
},
"memory": {
"type": "object",
"properties": {
"rss": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"enum": ["Infinity", "-Infinity", "NaN"]
}
]
},
"heapTotal": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"enum": ["Infinity", "-Infinity", "NaN"]
}
]
},
"heapUsed": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"enum": ["Infinity", "-Infinity", "NaN"]
}
]
},
"external": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"enum": ["Infinity", "-Infinity", "NaN"]
}
]
},
"arrayBuffers": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"enum": ["Infinity", "-Infinity", "NaN"]
}
]
}
},
"required": ["rss", "heapTotal", "heapUsed", "external", "arrayBuffers"],
"additionalProperties": false,
"description": "The server process's memory in bytes, read just before the snapshot (Node's process.memoryUsage()). rss covers native memory the snapshot cannot show."
}
},
"required": ["path", "pid"],
"required": ["path", "pid", "memory"],
"additionalProperties": false
}
}
+64 -1
View File
@@ -13452,9 +13452,72 @@
},
"pid": {
"type": "integer"
},
"memory": {
"type": "object",
"properties": {
"rss": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"enum": ["Infinity", "-Infinity", "NaN"]
}
]
},
"heapTotal": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"enum": ["Infinity", "-Infinity", "NaN"]
}
]
},
"heapUsed": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"enum": ["Infinity", "-Infinity", "NaN"]
}
]
},
"external": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"enum": ["Infinity", "-Infinity", "NaN"]
}
]
},
"arrayBuffers": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"enum": ["Infinity", "-Infinity", "NaN"]
}
]
}
},
"required": ["rss", "heapTotal", "heapUsed", "external", "arrayBuffers"],
"additionalProperties": false,
"description": "The server process's memory in bytes, read just before the snapshot (Node's process.memoryUsage()). rss covers native memory the snapshot cannot show."
}
},
"required": ["path", "pid"],
"required": ["path", "pid", "memory"],
"additionalProperties": false
}
}
@@ -144,16 +144,21 @@ opencode debug heap-dump --directory ./snapshots
### In the desktop app
Run **Capture heap snapshots** from the command palette. It writes one folder in your Downloads folder with a snapshot of
each part of the app:
each part of the app, plus a breakdown of the memory a snapshot cannot show:
```text
opencode-heap-2026-10-23T013012345Z/
memory.json where the memory is, per process, in MiB: start here
memory-infra.json Chromium's memory dump trace; open it in https://ui.perfetto.dev
heap-48213-….heapsnapshot the desktop's own server
window-1-48390.heapsnapshot one per app window
main-48102.heapsnapshot the desktop main process
manifest.json processes, PIDs, and per-process memory; written last
gpu.json the GPU and driver
manifest.json processes, PIDs, and memory before and after; written last
```
- A heap snapshot holds only JavaScript objects and the page. Images, layout, compositor layers and GPU memory are in
`memory.json` and `memory-infra.json` instead.
- Remote servers are not captured. Use `opencode debug heap-dump` on that machine instead.
- The server writes its snapshot straight into the folder, so nothing large is moved or copied.
- Browser tabs are not included, because their snapshots contain the content of the pages you visited.