Skip to content

Chrome DevTools for coding agents

feat: Report memory kept alive by contexts in get_heapsnapshot_summary (#2570)

Dominik Inführ4103808ea50e
diff --git a/docs/tool-reference.md b/docs/tool-reference.md
index 0662a8e7..9b180fca 100644
--- a/docs/tool-reference.md
+++ b/docs/tool-reference.md
@@ -592,7 +592,7 @@ in the DevTools Elements panel (if any).
### `get_heapsnapshot_summary`
-**Description:** Loads a memory heapsnapshot and returns snapshot summary stats, including native contexts and their sizes. (requires flag: --memoryDebugging=true)
+**Description:** Loads a memory heapsnapshot and returns snapshot summary stats, including native contexts and their sizes, and retained by context summary. (requires flag: --memoryDebugging=true)
**Parameters:**
diff --git a/src/McpContext.ts b/src/McpContext.ts
index 52031c03..5578e6d4 100644
--- a/src/McpContext.ts
+++ b/src/McpContext.ts
@@ -756,6 +756,14 @@ export class McpContext implements Context {
return await this.#heapSnapshotManager.getNativeContextSizes(filePath);
}
+ async getHeapSnapshotRetainedByContextSummary(
+ filePath: string,
+ ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainedByContextSummary> {
+ return await this.#heapSnapshotManager.getRetainedByContextSummary(
+ filePath,
+ );
+ }
+
async getHeapSnapshotNodesById(
filePath: string,
id: number,
diff --git a/src/McpResponse.ts b/src/McpResponse.ts
index af9fbbc7..7d03192a 100644
--- a/src/McpResponse.ts
+++ b/src/McpResponse.ts
@@ -90,6 +90,7 @@ export class McpResponse implements Response {
stats?: DevTools.HeapSnapshotModel.HeapSnapshotModel.Statistics;
staticData?: DevTools.HeapSnapshotModel.HeapSnapshotModel.StaticData | null;
nativeContextSizes?: DevTools.HeapSnapshotModel.HeapSnapshotModel.NativeContextSizes;
+ retainedByContextSummary?: DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainedByContextSummary;
nodes?: DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange;
retainingPaths?: DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainingPaths;
dominators?: DevTools.HeapSnapshotModel.HeapSnapshotModel.DominatorChain;
@@ -342,6 +343,7 @@ export class McpResponse implements Response {
stats: DevTools.HeapSnapshotModel.HeapSnapshotModel.Statistics,
staticData: DevTools.HeapSnapshotModel.HeapSnapshotModel.StaticData | null,
nativeContextSizes: DevTools.HeapSnapshotModel.HeapSnapshotModel.NativeContextSizes,
+ retainedByContextSummary: DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainedByContextSummary,
) {
this.#heapSnapshotOptions = {
...this.#heapSnapshotOptions,
@@ -349,6 +351,7 @@ export class McpResponse implements Response {
stats,
staticData,
nativeContextSizes,
+ retainedByContextSummary,
};
}
@@ -786,6 +789,7 @@ export class McpResponse implements Response {
stats?: object;
staticData?: object;
nativeContextSizes?: object;
+ retainedByContextSummary?: object;
aggregateStats?: {
objectCount: number;
totalSelfSize: number;
@@ -1106,6 +1110,19 @@ Call ${handleDialog.name} to handle it before continuing.`);
structuredContent.heapSnapshot = structuredContent.heapSnapshot || {};
structuredContent.heapSnapshot.nativeContextSizes = nativeContextSizes;
}
+ const retainedByContextSummary =
+ this.#heapSnapshotOptions.retainedByContextSummary;
+ if (retainedByContextSummary) {
+ response.push('### Retained by Context Summary');
+ response.push(
+ HeapSnapshotFormatter.formatRetainedByContextSummary(
+ retainedByContextSummary,
+ ),
+ );
+ structuredContent.heapSnapshot = structuredContent.heapSnapshot || {};
+ structuredContent.heapSnapshot.retainedByContextSummary =
+ retainedByContextSummary;
+ }
const aggregateData = this.#heapSnapshotOptions.aggregateData;
if (aggregateData) {
const sortedEntries = HeapSnapshotFormatter.sort(
diff --git a/src/bin/chrome-devtools-cli-options.ts b/src/bin/chrome-devtools-cli-options.ts
index b98a6abe..d2b4e258 100644
--- a/src/bin/chrome-devtools-cli-options.ts
+++ b/src/bin/chrome-devtools-cli-options.ts
@@ -623,7 +623,7 @@ export const commands: Commands = {
},
get_heapsnapshot_summary: {
description:
- 'Loads a memory heapsnapshot and returns snapshot summary stats, including native contexts and their sizes. (requires flag: --memoryDebugging=true)',
+ 'Loads a memory heapsnapshot and returns snapshot summary stats, including native contexts and their sizes, and retained by context summary. (requires flag: --memoryDebugging=true)',
category: 'Memory',
args: {
filePath: {
diff --git a/src/formatters/HeapSnapshotFormatter.ts b/src/formatters/HeapSnapshotFormatter.ts
index f32e0a3f..adebb501 100644
--- a/src/formatters/HeapSnapshotFormatter.ts
+++ b/src/formatters/HeapSnapshotFormatter.ts
@@ -159,6 +159,21 @@ export class HeapSnapshotFormatter {
return lines.join('\n');
}
+ static formatRetainedByContextSummary(
+ summary: DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainedByContextSummary,
+ ): string {
+ const lines: string[] = [];
+ lines.push(`Context count: ${summary.contextCount}`);
+ lines.push(
+ `Retained by context size: ${formatBytesToKb(summary.retainedByContextSize)} (${summary.retainedByContextCount} objects)`,
+ );
+ lines.push(
+ `Not retained by context size: ${formatBytesToKb(summary.notRetainedByContextSize)} (${summary.notRetainedByContextCount} objects)`,
+ );
+ lines.push(`Total size: ${formatBytesToKb(summary.totalSize)}`);
+ return lines.join('\n');
+ }
+
#getSortedAggregates(): AggregatedInfoWithId[] {
return Object.values(this.#aggregates).sort((a, b) => b.maxRet - a.maxRet);
}
diff --git a/src/processors/HeapSnapshotManager.ts b/src/processors/HeapSnapshotManager.ts
index 7b848f2c..02f0a20d 100644
--- a/src/processors/HeapSnapshotManager.ts
+++ b/src/processors/HeapSnapshotManager.ts
@@ -154,6 +154,13 @@ export class HeapSnapshotManager {
return await snapshot.getNativeContextSizes();
}
+ async getRetainedByContextSummary(
+ filePath: string,
+ ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainedByContextSummary> {
+ const snapshot = await this.getSnapshot(filePath);
+ return await snapshot.getRetainedByContextSummary();
+ }
+
async getOrCreateIdForClassKey(
filePath: string,
classKey: string,
diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.ts
index 8d557259..c756ca56 100644
--- a/src/tools/ToolDefinition.ts
+++ b/src/tools/ToolDefinition.ts
@@ -124,6 +124,7 @@ export interface Response {
stats: DevTools.HeapSnapshotModel.HeapSnapshotModel.Statistics,
staticData: DevTools.HeapSnapshotModel.HeapSnapshotModel.StaticData | null,
nativeContextSizes: DevTools.HeapSnapshotModel.HeapSnapshotModel.NativeContextSizes,
+ retainedByContextSummary: DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainedByContextSummary,
): void;
setHeapSnapshotNodes(
nodes: DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange,
@@ -265,6 +266,9 @@ export type Context = Readonly<{
getHeapSnapshotNativeContextSizes(
filePath: string,
): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.NativeContextSizes>;
+ getHeapSnapshotRetainedByContextSummary(
+ filePath: string,
+ ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainedByContextSummary>;
getHeapSnapshotNodesById(
filePath: string,
id: number,
diff --git a/src/tools/memory.ts b/src/tools/memory.ts
index 855ab7af..17516b46 100644
--- a/src/tools/memory.ts
+++ b/src/tools/memory.ts
@@ -51,7 +51,7 @@ export const takeHeapSnapshot = definePageTool({
export const getHeapSnapshotSummary = defineTool({
name: 'get_heapsnapshot_summary',
description:
- 'Loads a memory heapsnapshot and returns snapshot summary stats, including native contexts and their sizes.',
+ 'Loads a memory heapsnapshot and returns snapshot summary stats, including native contexts and their sizes, and retained by context summary.',
annotations: {
category: ToolCategory.MEMORY,
readOnlyHint: true,
@@ -70,8 +70,17 @@ export const getHeapSnapshotSummary = defineTool({
const nativeContextSizes = await context.getHeapSnapshotNativeContextSizes(
request.params.filePath,
);
+ const retainedByContextSummary =
+ await context.getHeapSnapshotRetainedByContextSummary(
+ request.params.filePath,
+ );
- response.setHeapSnapshotStats(stats, staticData, nativeContextSizes);
+ response.setHeapSnapshotStats(
+ stats,
+ staticData,
+ nativeContextSizes,
+ retainedByContextSummary,
+ );
},
});
diff --git a/tests/formatters/HeapSnapshotFormatter.test.ts b/tests/formatters/HeapSnapshotFormatter.test.ts
index fd1ea566..625212b1 100644
--- a/tests/formatters/HeapSnapshotFormatter.test.ts
+++ b/tests/formatters/HeapSnapshotFormatter.test.ts
@@ -334,4 +334,28 @@ describe('HeapSnapshotFormatter', () => {
assert.strictEqual(result, expected);
});
});
+
+ describe('formatRetainedByContextSummary', () => {
+ it('formats retained by context summary correctly', () => {
+ const mockSummary = {
+ contextCount: 2,
+ retainedByContextSize: 5000,
+ retainedByContextCount: 10,
+ notRetainedByContextSize: 1000,
+ notRetainedByContextCount: 5,
+ totalSize: 6000,
+ };
+
+ const result =
+ HeapSnapshotFormatter.formatRetainedByContextSummary(mockSummary);
+ const expected = [
+ 'Context count: 2',
+ `Retained by context size: ${formatBytesToKb(5000)} (10 objects)`,
+ `Not retained by context size: ${formatBytesToKb(1000)} (5 objects)`,
+ `Total size: ${formatBytesToKb(6000)}`,
+ ].join('\n');
+
+ assert.strictEqual(result, expected);
+ });
+ });
});
diff --git a/tests/tools/memory.test.js.snapshot b/tests/tools/memory.test.js.snapshot
index 2b496bd8..34169e01 100644
--- a/tests/tools/memory.test.js.snapshot
+++ b/tests/tools/memory.test.js.snapshot
@@ -443,4 +443,9 @@ nodeId,nodeName,selfSize,retainedSize,attributedSize
7199,system / NativeContext,1.2 kB,84.4 kB,84.4 kB
Shared Size: 22.9 kB
Unattributed Size: 44.8 kB
+### Retained by Context Summary
+Context count: 116
+Retained by context size: 3.5 kB (148 objects)
+Not retained by context size: 798 kB (11792 objects)
+Total size: 802 kB
`;