mirror of
https://github.com/anomalyco/opencode.git
synced 2026-11-16 21:15:57 +03:00
feat(desktop): add native memory breakdown to heap captures (#58311)
This commit is contained in:
committed by
GitHub
Unverified
parent
f523f77138
commit
5f79a2aaf7
@@ -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:
|
||||
|
||||
|
||||
@@ -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>
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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({
|
||||
|
||||
@@ -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")
|
||||
|
||||
@@ -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),
|
||||
)
|
||||
|
||||
@@ -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
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user