Unverified Commit 2d5a45a5 authored by Luke Sandberg's avatar Luke Sandberg Committed by GitHub

Add allocation and memory data to the trace-server MCP protocol (#98546)

### What?

Makes the trace-server MCP tool usable for memory investigations and
improve usability/performance based on agent feedback ♾️

* Spans now report allocation data (`allocations` / `deallocations` /
`persistentAllocations` / `allocationCount`, each with a `self*`
counterpart excluding children), plus `memorySummary` and
`heaviestSpanId`.

* `search` became recursive, and `depth` / `pageSize` were added so a
caller can pull a subtree or a wide page in one call instead of one
round-trip per level.

---------
Co-authored-by: 's avatarClaude Opus 5 (1M context) <noreply@anthropic.com>
parent 86d92b94
......@@ -732,11 +732,26 @@ internal
.addOption(
new Option(
'--sort <mode>',
'Sort mode: "value" for corrected duration descending, "name" for alphabetical.'
).choices(['value', 'name'])
'Sort mode: "value" for corrected duration descending, "name" for alphabetical, "allocations" for total allocated bytes descending, "persistent-allocations" for persistentAllocations descending.'
).choices(['value', 'name', 'allocations', 'persistent-allocations'])
)
.addOption(
new Option('--search <search>', 'Substring filter on span name/category.')
new Option(
'--search <search>',
'Substring filter on span name/category. Searches the whole subtree below --parent.'
)
)
.addOption(
new Option(
'--max-depth <depth>',
'Levels to descend for --search and --depth (default 32, also the cap).'
).argParser(parseValidPositiveInteger)
)
.addOption(
new Option(
'--depth <depth>',
'Levels of descendants to nest inline under each span (default 1).'
).argParser(parseValidPositiveInteger)
)
.addOption(new Option('--json', 'Output as JSON instead of markdown.'))
.addOption(
......@@ -744,6 +759,12 @@ internal
parseValidPositiveInteger
)
)
.addOption(
new Option(
'--page-size <size>',
'Spans per page (default 20, max 500).'
).argParser(parseValidPositiveInteger)
)
.addHelpText('after', ({ command }) => {
const port = (command.opts() as { port?: number }).port ?? 5748
return `\nExample:\n next internal query-trace --port ${port} --parent <id>`
......
......@@ -777,6 +777,22 @@ export declare function teardownTraceSubscriber(
guardExternal: ExternalObject<RefCell<FlushGuard | undefined | null>>
): void
/** Aggregate view of a span's TurboMalloc memory samples. */
export interface TraceMemorySummary {
/** Number of samples in the span's range, after downsampling. */
count: number
/** Live bytes at the first sample in the range. */
start: number
/** Live bytes at the last sample in the range. */
end: number
/** Smallest live-bytes reading in the range. */
min: number
/** Largest live-bytes reading in the range — the span's peak memory. */
peak: number
/** Highest memory-pressure byte in the range (0 = no pressure). */
maxPressure: number
}
/** Options for `query_trace_spans`. */
export interface TraceQueryOptions {
/**
......@@ -787,14 +803,36 @@ export interface TraceQueryOptions {
/** When `true` (default), aggregate child spans with the same name. */
aggregated?: boolean
/**
* Sort mode: `"value"` for duration descending, `"name"` for alphabetical.
* Sort mode: `"value"` for duration descending, `"name"` for alphabetical,
* `"allocations"` for total allocated bytes descending,
* `"persistent-allocations"` for `persistentAllocations` descending.
* Omit for execution order (no sorting).
*/
sort?: string
/** Optional substring search query applied to span name/category. */
/**
* Optional substring search query applied to span name/category.
*
* Matches anywhere in the parent's subtree. Each result's `id` is the full
* path from `parent` to the match, so it can be passed back as `parent`.
*
* Cost scales with subtree size, so a root search on a large trace walks
* everything. Setting `parent`, or lowering `maxDepth`, bounds it.
*/
search?: string
/**
* Maximum depth to descend below `parent` for `search` and `depth`.
* Default `32`, which is also the cap.
*/
maxDepth?: number
/**
* When greater than `1`, each returned span carries this many levels of
* descendants inline in `children`. Default `1` (no nesting).
*/
depth?: number
/** 1-based page number. Default `1`. */
page?: number
/** Spans per page. Default `20`, capped at `500`. */
pageSize?: number
}
/** The result of a `query_trace_spans` call. */
......@@ -836,18 +874,99 @@ export interface TraceSpanInfo {
totalCorrectedDuration?: number
/** Average corrected duration across spans in the group. */
avgCorrectedDuration?: number
/** Raw span ID for aggregated groups (the index of the first span). */
/**
* Raw span ID of the group's example span, whose `cpuDuration`,
* `correctedDuration` and `memorySamples` are the ones reported here.
* First in execution order — *not* the largest, so it can badly understate
* a group's allocations. Use `heaviestSpanId` for those.
*/
firstSpanId?: string
/**
* Raw span ID of the group member with the largest persistent
* allocations.
*/
heaviestSpanId?: string
/**
* Total bytes allocated by this span and all its children.
*
* For aggregated groups this is the group total, unlike `cpuDuration`,
* `correctedDuration` and `memorySamples`, which describe the example span
* only. Every allocation field below follows this field, not those.
*/
allocations: number
/**
* Total bytes deallocated by this span and all its children.
* Group total for aggregated spans.
*/
deallocations: number
/**
* Sum over each span of `max(0, selfAllocations - selfDeallocations)`,
* for this span and its children. Group total for aggregated spans.
*
* **A ranking signal, not retained memory.** TurboMalloc's per-span
* counters never observe turbo-tasks cell and cache drops, so a
* whole-trace total far above real peak RSS is expected, not a leak. Use
* `memorySummary.peak` for absolute memory.
*
* The per-span floor at zero is also why this is not
* `allocations - deallocations`.
*/
persistentAllocations: number
/**
* Number of allocation operations by this span and all its children.
* Group total for aggregated spans.
*/
allocationCount: number
/**
* Bytes allocated by this span itself, excluding children.
* Group total for aggregated spans.
*/
selfAllocations: number
/**
* Bytes deallocated by this span itself, excluding children.
* Group total for aggregated spans.
*
* Frees are charged to whichever span was on top of the thread's stack at
* free time, which is often not the span that allocated. So small
* `selfAllocations` with large `selfDeallocations` means this span is
* where a child's arena gets dropped — that arena is bounded, not leaking.
* The shape to suspect is a large `selfPersistentAllocations` with no such
* counterpart above it.
*/
selfDeallocations: number
/**
* `max(0, selfAllocations - selfDeallocations)` for this span alone.
* Group total for aggregated spans.
*/
selfPersistentAllocations: number
/**
* Number of allocation operations by this span itself, excluding children.
* Group total for aggregated spans.
*/
selfAllocationCount: number
/**
* TurboMalloc memory-usage samples recorded while this span
* (or its example span, for aggregated groups) was live.
*
* **Process-wide, not per-span.** One global series is sliced by the
* span's time range, so spans that overlap in time report identical values
* no matter what each allocated. Rank concurrent work by the allocation
* fields instead.
*
* Each entry is `[ts_offset_from_span_start_in_ticks, bytes, pressure]`,
* where `pressure` is the memory-pressure byte (0 = no pressure, higher
* = more pressure). `100 ticks = 1 µs`. The offset is always `>= 0` and
* `<= span_duration`. Capped and downsampled by the store.
*/
memorySamples: Array<Array<number>>
/**
* Summary of `memorySamples`; absent when the span's range holds none.
* Unlike the allocation counters these are absolute live-heap readings, so
* `peak` is the figure to quote for memory actually in use.
*/
memorySummary?: TraceMemorySummary
/** Descendants of this span, populated only when `depth > 1`. */
children: Array<TraceSpanInfo>
}
export declare function transform(
......
......@@ -14,7 +14,10 @@ interface QueryTraceOptions {
aggregated: boolean | undefined
sort: string | undefined
search: string | undefined
maxDepth: number | undefined
depth: number | undefined
page: number | undefined
pageSize: number | undefined
json: boolean | undefined
}
......@@ -27,7 +30,10 @@ export async function queryTraceCli(options: QueryTraceOptions): Promise<void> {
if (options.aggregated !== undefined) args.aggregated = options.aggregated
if (options.sort !== undefined) args.sort = options.sort
if (options.search !== undefined) args.search = options.search
if (options.maxDepth !== undefined) args.maxDepth = options.maxDepth
if (options.depth !== undefined) args.depth = options.depth
if (options.page !== undefined) args.page = options.page
if (options.pageSize !== undefined) args.pageSize = options.pageSize
if (options.json) args.outputType = 'json'
const requestBody = JSON.stringify({
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment