Unverified Commit 8e93ea13 authored by Luke Sandberg's avatar Luke Sandberg Committed by GitHub

more agentic MCP feedback

parent 2ad93490
...@@ -818,10 +818,16 @@ internal ...@@ -818,10 +818,16 @@ internal
'MCP port of the running trace server. Defaults to 5748.' 'MCP port of the running trace server. Defaults to 5748.'
).argParser(parseValidPositiveInteger) ).argParser(parseValidPositiveInteger)
) )
.addOption(
new Option(
'--tool <tool>',
'Tool to call: "query_spans" (default) lists spans, "flat_profile" sums time and allocations by name across a subtree, "memory_timeline" shows committed memory and RSS over time with phase markers.'
).choices(['query_spans', 'flat_profile', 'memory_timeline'])
)
.addOption( .addOption(
new Option( new Option(
'--parent <parent>', '--parent <parent>',
'Span ID to enumerate children of. Omit for root level.' 'Span ID to enumerate children of (or, for flat_profile and memory_timeline, to scope to). Omit for root level.'
) )
) )
.addOption( .addOption(
...@@ -833,8 +839,18 @@ internal ...@@ -833,8 +839,18 @@ internal
.addOption( .addOption(
new Option( new Option(
'--sort <mode>', '--sort <mode>',
'Sort mode: "value" for corrected duration descending, "name" for alphabetical, "allocations" for total allocated bytes descending, "persistent-allocations" for persistentAllocations descending.' 'Sort mode. query_spans: "value" for corrected duration descending, "name" for alphabetical, "allocations" for total allocated bytes descending, "persistent-allocations" for persistentAllocations descending. flat_profile: "self" (default), "total", "self-allocations", "self-persistent-allocations" or "count".'
).choices(['value', 'name', 'allocations', 'persistent-allocations']) ).choices([
'value',
'name',
'allocations',
'persistent-allocations',
'self',
'total',
'self-allocations',
'self-persistent-allocations',
'count',
])
) )
.addOption( .addOption(
new Option( new Option(
...@@ -842,19 +858,55 @@ internal ...@@ -842,19 +858,55 @@ internal
'Substring filter on span name/category. Searches the whole subtree below --parent.' 'Substring filter on span name/category. Searches the whole subtree below --parent.'
) )
) )
.addOption(
new Option(
'--recursive',
'List every span in the subtree below --parent, as if --search matched everything.'
)
)
.addOption( .addOption(
new Option( new Option(
'--max-depth <depth>', '--max-depth <depth>',
'Levels to descend for --search and --depth (default 32, also the cap).' 'Levels to descend for --search and --recursive (default unlimited).'
).argParser(parseValidPositiveInteger) ).argParser(parseValidPositiveInteger)
) )
.addOption( .addOption(
new Option( new Option(
'--depth <depth>', '--depth <depth>',
'Levels of descendants to nest inline under each span (default 1).' 'Levels of descendants to nest inline under each span (default 1, max 32).'
).argParser(parseValidPositiveInteger)
)
.addOption(
new Option(
'--start <ticks>',
'memory_timeline: absolute start in ticks (10 ns), overriding --parent.'
).argParser(parseValidPositiveInteger)
)
.addOption(
new Option(
'--end <ticks>',
'memory_timeline: absolute end in ticks (10 ns), overriding --parent.'
).argParser(parseValidPositiveInteger)
)
.addOption(
new Option(
'--max-samples <count>',
'memory_timeline: samples to downsample to (default 100, max 2000).'
).argParser(parseValidPositiveInteger)
)
.addOption(
new Option(
'--max-phases <count>',
'memory_timeline: phases to list (default 20, max 200).'
).argParser(parseValidPositiveInteger) ).argParser(parseValidPositiveInteger)
) )
.addOption(new Option('--json', 'Output as JSON instead of markdown.')) .addOption(new Option('--json', 'Output as JSON instead of markdown.'))
.addOption(
new Option(
'--fields <fields>',
'query_spans: comma-separated span fields to return (plus id), e.g. "name,args". Implies --json and allows --page-size up to 10000.'
)
)
.addOption( .addOption(
new Option('--page <page>', 'Page number (1-based, default 1).').argParser( new Option('--page <page>', 'Page number (1-based, default 1).').argParser(
parseValidPositiveInteger parseValidPositiveInteger
...@@ -863,12 +915,16 @@ internal ...@@ -863,12 +915,16 @@ internal
.addOption( .addOption(
new Option( new Option(
'--page-size <size>', '--page-size <size>',
'Spans per page (default 20, max 500).' 'Spans per page (default 20, max 500, or 10000 with --fields).'
).argParser(parseValidPositiveInteger) ).argParser(parseValidPositiveInteger)
) )
.addHelpText('after', ({ command }) => { .addHelpText('after', ({ command }) => {
const port = (command.opts() as { port?: number }).port ?? 5748 const port = (command.opts() as { port?: number }).port ?? 5748
return `\nExample:\n next internal query-trace --port ${port} --parent <id>` return (
`\nExamples:\n next internal query-trace --port ${port} --parent <id>` +
`\n next internal query-trace --port ${port} --tool flat_profile` +
`\n next internal query-trace --port ${port} --tool memory_timeline`
)
}) })
.action((options) => .action((options) =>
import('../cli/internal/query-trace.js').then((mod) => import('../cli/internal/query-trace.js').then((mod) =>
......
...@@ -1474,6 +1474,18 @@ async function loadWasm(importPath = '') { ...@@ -1474,6 +1474,18 @@ async function loadWasm(importPath = '') {
`Only WebAssembly (WASM) bindings were loaded, and Turbopack requires native bindings.` `Only WebAssembly (WASM) bindings were loaded, and Turbopack requires native bindings.`
) )
}, },
queryTraceFlatProfile(_handle: any, _options: any) {
throw new Error(
`Turbopack trace server is not supported on this platform (${PlatformName}/${ArchName}) because native bindings are not available. ` +
`Only WebAssembly (WASM) bindings were loaded, and Turbopack requires native bindings.`
)
},
queryTraceMemoryTimeline(_handle: any, _options: any) {
throw new Error(
`Turbopack trace server is not supported on this platform (${PlatformName}/${ArchName}) because native bindings are not available. ` +
`Only WebAssembly (WASM) bindings were loaded, and Turbopack requires native bindings.`
)
},
databaseCompact(_path: string, _nextVersion: string): Promise<void> { databaseCompact(_path: string, _nextVersion: string): Promise<void> {
throw new Error( throw new Error(
'Turbopack database compaction is not supported on this platform' 'Turbopack database compaction is not supported on this platform'
...@@ -1724,6 +1736,18 @@ function loadNative(importPath?: string): Binding { ...@@ -1724,6 +1736,18 @@ function loadNative(importPath?: string): Binding {
queryTraceSpans(handle, options) { queryTraceSpans(handle, options) {
return (customBindings ?? bindings).queryTraceSpans(handle, options) return (customBindings ?? bindings).queryTraceSpans(handle, options)
}, },
queryTraceFlatProfile(handle, options) {
return (customBindings ?? bindings).queryTraceFlatProfile(
handle,
options
)
},
queryTraceMemoryTimeline(handle, options) {
return (customBindings ?? bindings).queryTraceMemoryTimeline(
handle,
options
)
},
databaseCompact(dbPath: string, dbNextVersion: string) { databaseCompact(dbPath: string, dbNextVersion: string) {
return (customBindings ?? bindings).turbopackDatabaseCompact( return (customBindings ?? bindings).turbopackDatabaseCompact(
dbPath, dbPath,
......
...@@ -12,6 +12,10 @@ import type { ...@@ -12,6 +12,10 @@ import type {
TraceServerHandle, TraceServerHandle,
TraceQueryOptions, TraceQueryOptions,
TraceQueryResult, TraceQueryResult,
TraceFlatProfileOptions,
TraceFlatProfileResult,
TraceMemoryTimelineOptions,
TraceMemoryTimeline,
MemoryEvictionMode, MemoryEvictionMode,
NapiTurbopackGcOptions, NapiTurbopackGcOptions,
ServerHmrVersion as NativeServerHmrVersion, ServerHmrVersion as NativeServerHmrVersion,
...@@ -25,7 +29,15 @@ import type { ...@@ -25,7 +29,15 @@ import type {
projectUpdateInfoSubscribe, projectUpdateInfoSubscribe,
} from './generated-native' } from './generated-native'
export type { TraceServerHandle, TraceQueryOptions, TraceQueryResult } export type {
TraceServerHandle,
TraceQueryOptions,
TraceQueryResult,
TraceFlatProfileOptions,
TraceFlatProfileResult,
TraceMemoryTimelineOptions,
TraceMemoryTimeline,
}
export type { LockfileError } export type { LockfileError }
export type { NapiTurboEngineOptions as TurboEngineOptions } export type { NapiTurboEngineOptions as TurboEngineOptions }
...@@ -56,6 +68,14 @@ export interface Binding { ...@@ -56,6 +68,14 @@ export interface Binding {
handle: TraceServerHandle, handle: TraceServerHandle,
options: TraceQueryOptions options: TraceQueryOptions
): TraceQueryResult ): TraceQueryResult
queryTraceFlatProfile(
handle: TraceServerHandle,
options: TraceFlatProfileOptions
): TraceFlatProfileResult
queryTraceMemoryTimeline(
handle: TraceServerHandle,
options: TraceMemoryTimelineOptions
): TraceMemoryTimeline
databaseCompact(path: string, nextVersion: string): Promise<void> databaseCompact(path: string, nextVersion: string): Promise<void>
nextBuild?: any nextBuild?: any
......
...@@ -10,37 +10,65 @@ const DEFAULT_MCP_PORT = 5748 // Keep in sync with turbo-trace-server.ts ...@@ -10,37 +10,65 @@ const DEFAULT_MCP_PORT = 5748 // Keep in sync with turbo-trace-server.ts
interface QueryTraceOptions { interface QueryTraceOptions {
port: number | undefined port: number | undefined
tool: 'query_spans' | 'flat_profile' | 'memory_timeline' | undefined
parent: string | undefined parent: string | undefined
aggregated: boolean | undefined aggregated: boolean | undefined
sort: string | undefined sort: string | undefined
search: string | undefined search: string | undefined
recursive: boolean | undefined
maxDepth: number | undefined maxDepth: number | undefined
depth: number | undefined depth: number | undefined
start: number | undefined
end: number | undefined
maxSamples: number | undefined
maxPhases: number | undefined
page: number | undefined page: number | undefined
pageSize: number | undefined pageSize: number | undefined
json: boolean | undefined json: boolean | undefined
fields: string | undefined
} }
export async function queryTraceCli(options: QueryTraceOptions): Promise<void> { export async function queryTraceCli(options: QueryTraceOptions): Promise<void> {
const port = options.port ?? DEFAULT_MCP_PORT const port = options.port ?? DEFAULT_MCP_PORT
// Build arguments — only include values explicitly set by the user. const tool = options.tool ?? 'query_spans'
// Build arguments — only include values explicitly set by the user. Each
// tool validates its own arguments, so options another tool doesn't take
// are left out rather than rejected.
const args: Record<string, unknown> = {} const args: Record<string, unknown> = {}
if (options.parent !== undefined) args.parent = options.parent if (options.parent !== undefined) args.parent = options.parent
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' if (options.json) args.outputType = 'json'
if (tool === 'query_spans' || tool === 'flat_profile') {
if (options.sort !== undefined) args.sort = options.sort
if (options.search !== undefined) args.search = options.search
if (options.page !== undefined) args.page = options.page
if (options.pageSize !== undefined) args.pageSize = options.pageSize
}
if (tool === 'query_spans') {
if (options.aggregated !== undefined) args.aggregated = options.aggregated
if (options.recursive !== undefined) args.recursive = options.recursive
if (options.maxDepth !== undefined) args.maxDepth = options.maxDepth
if (options.depth !== undefined) args.depth = options.depth
if (options.fields !== undefined) {
args.fields = options.fields
.split(',')
.map((field) => field.trim())
.filter(Boolean)
}
}
if (tool === 'memory_timeline') {
if (options.start !== undefined) args.start = options.start
if (options.end !== undefined) args.end = options.end
if (options.maxSamples !== undefined) args.maxSamples = options.maxSamples
if (options.maxPhases !== undefined) args.maxPhases = options.maxPhases
}
const requestBody = JSON.stringify({ const requestBody = JSON.stringify({
jsonrpc: '2.0', jsonrpc: '2.0',
method: 'tools/call', method: 'tools/call',
params: { params: {
name: 'query_spans', name: tool,
arguments: args, arguments: args,
}, },
id: 1, id: 1,
...@@ -88,7 +116,10 @@ export async function queryTraceCli(options: QueryTraceOptions): Promise<void> { ...@@ -88,7 +116,10 @@ export async function queryTraceCli(options: QueryTraceOptions): Promise<void> {
for (const line of body.split('\n')) { for (const line of body.split('\n')) {
if (!line.startsWith('data: ')) continue if (!line.startsWith('data: ')) continue
let msg: { let msg: {
result?: { content?: Array<{ type: string; text?: string }> } result?: {
content?: Array<{ type: string; text?: string }>
isError?: boolean
}
error?: unknown error?: unknown
} }
try { try {
...@@ -101,6 +132,12 @@ export async function queryTraceCli(options: QueryTraceOptions): Promise<void> { ...@@ -101,6 +132,12 @@ export async function queryTraceCli(options: QueryTraceOptions): Promise<void> {
process.exit(1) process.exit(1)
} }
const text = msg.result?.content?.find((c) => c.type === 'text')?.text const text = msg.result?.content?.find((c) => c.type === 'text')?.text
if (msg.result?.isError) {
// e.g. an option the tool's schema rejects, like a `--sort` mode of
// another tool.
console.error(`Error: ${text ?? JSON.stringify(msg.result)}`)
process.exit(1)
}
if (text !== undefined) { if (text !== undefined) {
process.stdout.write(text) process.stdout.write(text)
return return
......
...@@ -81,13 +81,44 @@ async function querySpansJson( ...@@ -81,13 +81,44 @@ async function querySpansJson(
port: number, port: number,
args: Record<string, unknown> = {} args: Record<string, unknown> = {}
): Promise<QuerySpansResult> { ): Promise<QuerySpansResult> {
const text = await callMcpTool(port, 'query_spans', { return callToolJson(port, 'query_spans', args)
}
/** Call any tool with outputType:'json' and return the parsed result. */
async function callToolJson<T>(
port: number,
toolName: string,
args: Record<string, unknown> = {}
): Promise<T> {
const text = await callMcpTool(port, toolName, {
...args, ...args,
outputType: 'json', outputType: 'json',
}) })
return JSON.parse(text) return JSON.parse(text)
} }
type ProfileEntry = {
name: string
count: number
correctedSelfDuration: number
exampleSpanId: string
}
type FlatProfileResult = {
entries: ProfileEntry[]
totalCount: number
spanCount: number
totalCorrectedSelfDuration: number
}
type MemoryTimelineResult = {
start: number
end: number
samples: number[][]
rawSampleCount: number
phases: Array<{ id: string; name: string; start: number; end: number }>
}
/** /**
* Run `next internal query-trace` with the given extra arguments. * Run `next internal query-trace` with the given extra arguments.
* Returns captured stdout, stderr, and exit code. * Returns captured stdout, stderr, and exit code.
...@@ -364,7 +395,10 @@ describe('turbopack-trace-server', () => { ...@@ -364,7 +395,10 @@ describe('turbopack-trace-server', () => {
const md = await callMcpTool(mcpPort, 'query_spans', { const md = await callMcpTool(mcpPort, 'query_spans', {
sort: 'allocations', sort: 'allocations',
}) })
expect(md).toContain('**Allocations:**') // Groups label theirs as group totals, apart from their example span.
expect(md).toMatch(
/\*\*Allocations( \(group totals over all members\))?:\*\*/
)
expect(md).toMatch(/- \*\*Allocated:\*\* .+ \(self .+\)/) expect(md).toMatch(/- \*\*Allocated:\*\* .+ \(self .+\)/)
expect(md).toMatch( expect(md).toMatch(
/- \*\*Persistent \(ranking signal, not retained\):\*\* .+ \(self .+\)/ /- \*\*Persistent \(ranking signal, not retained\):\*\* .+ \(self .+\)/
...@@ -512,8 +546,8 @@ describe('turbopack-trace-server', () => { ...@@ -512,8 +546,8 @@ describe('turbopack-trace-server', () => {
it('should point heaviestSpanId at the group member holding the most bytes', async () => { it('should point heaviestSpanId at the group member holding the most bytes', async () => {
// A group's members are the raw spans under the group's *parent* that // A group's members are the raw spans under the group's *parent* that
// share its name — not the children of the group id, which belong to the // share its name — not the children of the group id, which are the
// example span alone. So the walk has to keep the parent it descended // members' children. So the walk has to keep the parent it descended
// from. // from.
const isGroup = (s: SpanData) => const isGroup = (s: SpanData) =>
s.isAggregated && (s.count as number) > 1 && s.heaviestSpanId s.isAggregated && (s.count as number) > 1 && s.heaviestSpanId
...@@ -575,6 +609,131 @@ describe('turbopack-trace-server', () => { ...@@ -575,6 +609,131 @@ describe('turbopack-trace-server', () => {
) )
}) })
// ─── absolute times ──────────────────────────────────────────────────────
it('should report absolute times and units in JSON output', async () => {
const data = await callToolJson<
QuerySpansResult & { units: unknown; depthLimited: boolean }
>(mcpPort, 'query_spans', { sort: 'value' })
expect(data.units).toHaveProperty('time')
expect(data.depthLimited).toBe(false)
for (const span of data.spans) {
const start = span.start as number
const end = span.end as number
expect(typeof start).toBe('number')
expect(end).toBeGreaterThanOrEqual(start)
expect(typeof span.groupName).toBe('string')
// Memory samples share the span clock, so they fall inside its range.
// For a group they cover the example span, which lies within it.
for (const [ts] of span.memorySamples as number[][]) {
expect(ts).toBeGreaterThanOrEqual(start)
expect(ts).toBeLessThanOrEqual(end)
}
}
})
// ─── recursive listing ───────────────────────────────────────────────────
it('should list the whole subtree with recursive', async () => {
const { spans } = await querySpansJson(mcpPort, { sort: 'value' })
const parent = spans[0].id
const direct = await querySpansJson(mcpPort, {
parent,
aggregated: false,
})
const all = await querySpansJson(mcpPort, {
parent,
aggregated: false,
recursive: true,
})
expect(all.totalCount).toBeGreaterThanOrEqual(direct.totalCount)
})
// ─── field masks ─────────────────────────────────────────────────────────
it('should return only the requested fields, with larger pages', async () => {
const full = await querySpansJson(mcpPort, {
aggregated: false,
recursive: true,
})
const masked = await querySpansJson(mcpPort, {
aggregated: false,
recursive: true,
fields: ['name', 'args'],
pageSize: 2000,
})
expect(masked.totalCount).toBe(full.totalCount)
// Past the 500 cap of full responses.
expect(masked.spans.length).toBe(Math.min(2000, full.totalCount))
for (const span of masked.spans) {
expect(Object.keys(span).sort()).toEqual(['args', 'id', 'name'])
}
// Same spans, same order, as the full response's first page.
expect(masked.spans.slice(0, full.spans.length).map((s) => s.id)).toEqual(
full.spans.map((s) => s.id)
)
})
// ─── flat profile ────────────────────────────────────────────────────────
it('should return a flat profile grouped by name', async () => {
const result = await callToolJson<FlatProfileResult>(
mcpPort,
'flat_profile',
{ pageSize: 500 }
)
expect(result.entries.length).toBeGreaterThan(0)
expect(result.spanCount).toBeGreaterThan(0)
// One entry per name, sorted by corrected self time.
const names = result.entries.map((e) => e.name)
expect(new Set(names).size).toBe(names.length)
const values = result.entries.map((e) => e.correctedSelfDuration)
expect(values).toEqual([...values].sort((a, b) => b - a))
// Self times partition the subtree, so they can't exceed its total.
const sum = values.reduce((a, b) => a + b, 0)
expect(sum).toBeLessThanOrEqual(result.totalCorrectedSelfDuration)
// The example span is navigable.
const example = await querySpansJson(mcpPort, {
parent: result.entries[0].exampleSpanId,
})
expect(example).toHaveProperty('totalCount')
})
it('should render a flat profile as a markdown table', async () => {
const md = await callMcpTool(mcpPort, 'flat_profile', {})
expect(md).toContain('## Flat profile of whole trace')
expect(md).toContain('| Name | Count | Self (corrected) |')
})
// ─── memory timeline ─────────────────────────────────────────────────────
it('should return a memory timeline with phases', async () => {
const timeline = await callToolJson<MemoryTimelineResult>(
mcpPort,
'memory_timeline',
{ maxSamples: 10 }
)
expect(timeline.end).toBeGreaterThanOrEqual(timeline.start)
expect(timeline.samples.length).toBeLessThanOrEqual(10)
for (const [ts] of timeline.samples) {
expect(ts).toBeGreaterThanOrEqual(timeline.start)
expect(ts).toBeLessThanOrEqual(timeline.end)
}
const starts = timeline.phases.map((p) => p.start)
expect(starts).toEqual([...starts].sort((a, b) => a - b))
// Phases are single spans, so their IDs are raw span IDs.
for (const phase of timeline.phases) {
expect(phase.id).toMatch(/^\d+$/)
expect(phase.end).toBeGreaterThanOrEqual(phase.start)
}
const md = await callMcpTool(mcpPort, 'memory_timeline', {})
expect(md).toContain('## Memory timeline of whole trace')
})
// ─── CLI tests ─────────────────────────────────────────────────────────── // ─── CLI tests ───────────────────────────────────────────────────────────
it('CLI: should return root-level spans', async () => { it('CLI: should return root-level spans', async () => {
...@@ -693,4 +852,58 @@ describe('turbopack-trace-server', () => { ...@@ -693,4 +852,58 @@ describe('turbopack-trace-server', () => {
expect(Array.isArray(data.spans)).toBe(true) expect(Array.isArray(data.spans)).toBe(true)
expect(data.spans.length).toBeGreaterThan(0) expect(data.spans.length).toBeGreaterThan(0)
}) })
it('CLI: should support --fields', async () => {
const { stdout, exitCode } = await runQueryTraceCli([
'--port',
String(mcpPort),
'--fields',
'name,groupName',
])
expect(exitCode).toBe(0)
const data = JSON.parse(stdout)
expect(data.spans.length).toBeGreaterThan(0)
for (const span of data.spans) {
expect(Object.keys(span).sort()).toEqual(['groupName', 'id', 'name'])
}
})
it('CLI: should support --tool flat_profile', async () => {
const { stdout, exitCode } = await runQueryTraceCli([
'--port',
String(mcpPort),
'--tool',
'flat_profile',
'--sort',
'count',
])
expect(exitCode).toBe(0)
expect(stdout).toContain('## Flat profile of whole trace')
})
it('CLI: should support --tool memory_timeline', async () => {
const { stdout, exitCode } = await runQueryTraceCli([
'--port',
String(mcpPort),
'--tool',
'memory_timeline',
'--max-samples',
'5',
])
expect(exitCode).toBe(0)
expect(stdout).toContain('## Memory timeline of whole trace')
})
it('CLI: should fail on a sort mode the tool does not take', async () => {
const { stderr, exitCode } = await runQueryTraceCli([
'--port',
String(mcpPort),
'--tool',
'flat_profile',
'--sort',
'value',
])
expect(exitCode).toBe(1)
expect(stderr).toContain('Error')
})
}) })
This diff is collapsed.
//! A flat profile: every span below a parent, grouped by name across the whole
//! subtree, wherever in the tree each one sits.
use rustc_hash::FxHashMap;
use turbo_rcstr::RcStr;
use crate::{
DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, Parent, format_span_name, name_matches, paginate,
span_ref::SpanRef, store_container::StoreContainer, wait_for_data,
};
/// How flat profile entries are sorted. Every mode sorts descending.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ProfileSort {
/// `corrected_self_duration`.
#[default]
SelfTime,
/// `corrected_total_duration`.
TotalTime,
/// `self_allocations`.
SelfAllocations,
/// `self_persistent_allocations`.
SelfPersistentAllocations,
/// `count`.
Count,
}
pub struct FlatProfileOptions {
/// Span ID whose subtree to profile, as produced by `SpanInfo::id`. `None`
/// profiles the whole trace. For an aggregated group, every member's
/// subtree is included.
pub parent: Option<String>,
/// Keep only entries whose name matches, with the same matching as
/// `QueryOptions::search`.
pub search: Option<String>,
pub sort: ProfileSort,
/// 1-based page number.
pub page: usize,
/// Entries per page. Clamped to `MAX_PAGE_SIZE`; `None` uses
/// `DEFAULT_PAGE_SIZE`.
pub page_size: Option<usize>,
}
/// All spans with one name. Durations are in internal ticks (100 ticks = 1 µs).
pub struct ProfileEntry {
/// The span's group name, without its `name` arg, so e.g. every module's
/// analysis lands in one entry.
pub name: String,
/// Number of spans with this name.
pub count: u64,
/// Summed self time (excluding children).
pub self_duration: u64,
/// Summed concurrency-corrected self time. These sum to the subtree's
/// wall-clock-like total, so they are the figures to rank by.
pub corrected_self_duration: u64,
/// Summed total time (including children), counting only the outermost
/// span where spans with this name nest, so recursion isn't counted twice.
pub total_duration: u64,
/// Like `total_duration`, concurrency-corrected.
pub corrected_total_duration: u64,
/// Summed `self_allocations` of the spans.
pub self_allocations: u64,
/// Summed `self_deallocations` of the spans.
pub self_deallocations: u64,
/// Summed `self_persistent_allocations` of the spans.
pub self_persistent_allocations: u64,
/// Summed `self_allocation_count` of the spans.
pub self_allocation_count: u64,
/// Raw span ID of the span with the largest corrected total time. Usable
/// as a `parent`.
pub example_span_id: String,
/// Corrected total time of the example span.
pub example_corrected_duration: u64,
}
pub struct FlatProfileResult {
pub entries: Vec<ProfileEntry>,
pub page: usize,
pub total_pages: usize,
/// Number of entries (distinct names) across all pages.
pub total_count: usize,
/// Number of spans in the profiled subtree.
pub span_count: u64,
/// Corrected self time of the whole subtree, the denominator for shares of
/// `corrected_self_duration`.
pub total_corrected_self_duration: u64,
/// Self allocations of the whole subtree.
pub total_self_allocations: u64,
}
#[derive(Default)]
struct Accumulator<'a> {
count: u64,
self_duration: u64,
corrected_self_duration: u64,
total_duration: u64,
corrected_total_duration: u64,
self_allocations: u64,
self_deallocations: u64,
self_persistent_allocations: u64,
self_allocation_count: u64,
example: Option<(u64, SpanRef<'a>)>,
}
enum Step<'a> {
Enter(SpanRef<'a>),
/// Leaves the span with this group name.
Exit((&'a RcStr, &'a RcStr)),
}
pub fn flat_profile(store: &StoreContainer, options: FlatProfileOptions) -> FlatProfileResult {
wait_for_data(store);
let store_guard = store.read();
let store_ref = &*store_guard;
let page_size = options
.page_size
.unwrap_or(DEFAULT_PAGE_SIZE)
.clamp(1, MAX_PAGE_SIZE);
let members = Parent::resolve(store_ref, options.parent.as_deref())
.map(|parent| parent.members())
.unwrap_or_default();
let mut groups: FxHashMap<(&RcStr, &RcStr), Accumulator<'_>> = FxHashMap::default();
// How many spans with each name are on the current path, to count only the
// outermost one of nested same-named spans towards the totals.
let mut on_path: FxHashMap<(&RcStr, &RcStr), u32> = FxHashMap::default();
let mut stack: Vec<Step<'_>> = members
.iter()
.flat_map(|span| span.children())
.map(Step::Enter)
.collect();
let mut span_count = 0;
while let Some(step) = stack.pop() {
let span = match step {
Step::Enter(span) => span,
Step::Exit(name) => {
*on_path.get_mut(&name).expect("entered before") -= 1;
continue;
}
};
span_count += 1;
let name = span.group_name();
let group = groups.entry(name).or_default();
let corrected_total = *span.corrected_total_time();
group.count += 1;
group.self_duration += *span.self_time();
group.corrected_self_duration += *span.corrected_self_time();
group.self_allocations += span.self_allocations();
group.self_deallocations += span.self_deallocations();
group.self_persistent_allocations += span.self_persistent_allocations();
group.self_allocation_count += span.self_allocation_count();
let depth = on_path.entry(name).or_default();
if *depth == 0 {
group.total_duration += *span.total_time();
group.corrected_total_duration += corrected_total;
}
*depth += 1;
if group
.example
.is_none_or(|(duration, _)| corrected_total > duration)
{
group.example = Some((corrected_total, span));
}
stack.push(Step::Exit(name));
stack.extend(span.children().map(Step::Enter));
}
let total_corrected_self_duration = groups.values().map(|g| g.corrected_self_duration).sum();
let total_self_allocations = groups.values().map(|g| g.self_allocations).sum();
let mut entries: Vec<ProfileEntry> = groups
.into_iter()
.filter(|((cat, title), _)| {
options
.search
.as_deref()
.is_none_or(|query| name_matches(cat, title, query))
})
.map(|((cat, title), group)| {
let (example_corrected_duration, example) = group.example.expect("at least one span");
ProfileEntry {
name: format_span_name(cat, title),
count: group.count,
self_duration: group.self_duration,
corrected_self_duration: group.corrected_self_duration,
total_duration: group.total_duration,
corrected_total_duration: group.corrected_total_duration,
self_allocations: group.self_allocations,
self_deallocations: group.self_deallocations,
self_persistent_allocations: group.self_persistent_allocations,
self_allocation_count: group.self_allocation_count,
example_span_id: example.index.to_string(),
example_corrected_duration,
}
})
.collect();
let key = |entry: &ProfileEntry| match options.sort {
ProfileSort::SelfTime => entry.corrected_self_duration,
ProfileSort::TotalTime => entry.corrected_total_duration,
ProfileSort::SelfAllocations => entry.self_allocations,
ProfileSort::SelfPersistentAllocations => entry.self_persistent_allocations,
ProfileSort::Count => entry.count,
};
// Ties broken by name so pages are stable across calls.
entries.sort_by(|a, b| key(b).cmp(&key(a)).then_with(|| a.name.cmp(&b.name)));
let (entries, page, total_pages, total_count) = paginate(entries, options.page, page_size);
FlatProfileResult {
entries,
page,
total_pages,
total_count,
span_count,
total_corrected_self_duration,
total_self_allocations,
}
}
//! The process memory series over a time range, with the spans running in it
//! as phase markers.
use std::cmp::Reverse;
use crate::{
MemoryPoint, Parent, build_span_id, format_span_name, store_container::StoreContainer,
timestamp::Timestamp, wait_for_data,
};
/// Default for `MemoryTimelineOptions::max_samples`.
const DEFAULT_TIMELINE_SAMPLES: usize = 100;
/// Cap for `MemoryTimelineOptions::max_samples`.
const MAX_TIMELINE_SAMPLES: usize = 2000;
/// Default for `MemoryTimelineOptions::max_phases`.
const DEFAULT_TIMELINE_PHASES: usize = 20;
/// Cap for `MemoryTimelineOptions::max_phases`.
const MAX_TIMELINE_PHASES: usize = 200;
pub struct MemoryTimelineOptions {
/// Span ID whose time range to cover and whose children are the phases,
/// as produced by `SpanInfo::id`. `None` covers the whole trace, with the
/// top-level spans as phases. For an aggregated group, the children of
/// every member.
pub parent: Option<String>,
/// Absolute start in internal ticks, overriding the parent's.
pub start: Option<u64>,
/// Absolute end in internal ticks, overriding the parent's.
pub end: Option<u64>,
/// Number of samples to downsample to. Clamped to `MAX_TIMELINE_SAMPLES`.
pub max_samples: Option<usize>,
/// Number of phases to return, the ones with the largest corrected
/// duration. Clamped to `MAX_TIMELINE_PHASES`.
pub max_phases: Option<usize>,
}
/// A reading at one point in time. `ts` is absolute, in internal ticks.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct MemoryReading {
pub ts: u64,
/// Bytes the allocator has committed from the OS.
pub bytes: u64,
/// Process memory footprint (RSS) in bytes (0 = not reported).
pub footprint: u64,
}
/// A span running in the timeline's range.
///
/// Always a single span, never an aggregated group: a group's extent covers
/// the gaps between its members, so it would mark a phase where none ran.
pub struct TimelinePhase {
/// Raw span ID, usable as a `parent`.
pub id: String,
pub name: String,
/// Absolute start in internal ticks.
pub start: u64,
/// Absolute end in internal ticks.
pub end: u64,
/// Concurrency-corrected duration.
pub corrected_duration: u64,
/// Interpolated memory at `start`.
pub memory_at_start: Option<MemoryPoint>,
/// Interpolated memory at `end`.
pub memory_at_end: Option<MemoryPoint>,
/// Largest committed-bytes sample between `start` and `end`.
pub peak_bytes: Option<u64>,
/// Largest footprint sample between `start` and `end`.
pub peak_footprint: Option<u64>,
}
pub struct MemoryTimeline {
/// Absolute start of the covered range, in internal ticks.
pub start: u64,
/// Absolute end of the covered range, in internal ticks.
pub end: u64,
/// `(ts, bytes, pressure, footprint, active_worker_threads)`, downsampled
/// like `SpanInfo::memory_samples`.
pub samples: Vec<(u64, u64, u8, u64, u64)>,
/// Number of samples in the range before downsampling.
pub raw_sample_count: usize,
/// The sample with the most committed bytes.
pub peak_bytes: Option<MemoryReading>,
/// The sample with the largest footprint.
pub peak_footprint: Option<MemoryReading>,
/// The sample where footprint minus committed bytes is largest. A positive
/// gap is memory the process holds outside the allocator's committed pages
/// (stacks, mapped files, other allocators); a negative one means
/// committed pages that aren't resident (never touched, or swapped or
/// compressed). `None` when the platform doesn't report footprint.
pub max_gap: Option<MemoryReading>,
/// The phases with the largest corrected duration, in start order.
pub phases: Vec<TimelinePhase>,
}
pub fn memory_timeline(store: &StoreContainer, options: MemoryTimelineOptions) -> MemoryTimeline {
wait_for_data(store);
let store_guard = store.read();
let store_ref = &*store_guard;
let max_samples = options
.max_samples
.unwrap_or(DEFAULT_TIMELINE_SAMPLES)
.clamp(1, MAX_TIMELINE_SAMPLES);
let max_phases = options
.max_phases
.unwrap_or(DEFAULT_TIMELINE_PHASES)
.min(MAX_TIMELINE_PHASES);
let parent = Parent::resolve(store_ref, options.parent.as_deref());
let (default_start, default_end) = match (&parent, options.parent.as_deref()) {
(Some(parent), Some(_)) => parent.extent(),
// The whole trace: wherever there are samples, or the spans' range.
_ => store_ref
.memory_sample_range()
.unwrap_or_else(|| (Timestamp::ZERO, store_ref.root_span().end())),
};
let start = options.start.map_or(default_start, Timestamp::from_value);
let end = options.end.map_or(default_end, Timestamp::from_value);
let raw = store_ref.memory_samples_slice(start, end);
let reading = |&(ts, bytes, _, footprint, _): &(Timestamp, u64, u8, u64, u64)| MemoryReading {
ts: *ts,
bytes,
footprint,
};
let peak_bytes = raw.iter().max_by_key(|sample| sample.1).map(reading);
let peak_footprint = raw
.iter()
.filter(|sample| sample.3 > 0)
.max_by_key(|sample| sample.3)
.map(reading);
let max_gap = raw
.iter()
.filter(|sample| sample.3 > 0)
// Signed, since committed pages that were never touched or were
// swapped out make footprint smaller than committed bytes.
.max_by_key(|sample| sample.3 as i128 - sample.1 as i128)
.map(reading);
let samples = store_ref
.memory_samples_for_range_downsampled(start, end, max_samples)
.into_iter()
.map(|(ts, mem, pressure, footprint, workers)| (*ts, mem, pressure, footprint, workers))
.collect();
let mut phases: Vec<_> = parent
.map(|parent| parent.members())
.unwrap_or_default()
.iter()
.flat_map(|span| span.children())
.filter(|span| span.start() <= end && span.end() >= start)
.collect();
phases.sort_by_key(|span| Reverse(span.corrected_total_time()));
phases.truncate(max_phases);
phases.sort_by_key(|span| span.start());
let phases = phases
.into_iter()
.map(|span| {
let (cat, title) = span.nice_name();
let (phase_start, phase_end) = (span.start(), span.end());
let in_phase = store_ref.memory_samples_slice(phase_start, phase_end);
TimelinePhase {
id: build_span_id(options.parent.as_deref(), &span.index.to_string()),
name: format_span_name(cat, title),
start: *phase_start,
end: *phase_end,
corrected_duration: *span.corrected_total_time(),
memory_at_start: MemoryPoint::at(store_ref, phase_start),
memory_at_end: MemoryPoint::at(store_ref, phase_end),
peak_bytes: in_phase.iter().map(|sample| sample.1).max(),
peak_footprint: in_phase.iter().map(|sample| sample.3).max(),
}
})
.collect();
MemoryTimeline {
start: *start,
end: *end,
samples,
raw_sample_count: raw.len(),
peak_bytes,
peak_footprint,
max_gap,
phases,
}
}
...@@ -61,17 +61,22 @@ fn reads_active_workers_and_exposes_them_in_span_queries() { ...@@ -61,17 +61,22 @@ fn reads_active_workers_and_exposes_them_in_span_queries() {
aggregated, aggregated,
sort: SortMode::ExecutionOrder, sort: SortMode::ExecutionOrder,
search: None, search: None,
recursive: false,
max_depth: u32::MAX, max_depth: u32::MAX,
depth: 1, depth: 1,
page: 1, page: 1,
page_size: None, page_size: None,
include_memory_samples: true,
}, },
); );
assert_eq!(result.spans.len(), 1); assert_eq!(result.spans.len(), 1);
// Sample timestamps are absolute: 20 µs, on the same clock as the span.
assert_eq!( assert_eq!(
result.spans[0].memory_samples, result.spans[0].memory_samples,
vec![(1000, 1234, 7, 5555, 2)] vec![(2000, 1234, 7, 5555, 2)]
); );
assert_eq!(result.spans[0].start, 1000);
assert_eq!(result.spans[0].end, 3000);
} }
} }
......
...@@ -29,7 +29,7 @@ const CUT_OFF_DEPTH: u32 = 80; ...@@ -29,7 +29,7 @@ const CUT_OFF_DEPTH: u32 = 80;
/// `memory_pressure` is an OS-reported value in `0..=100`; `memory_footprint` /// `memory_pressure` is an OS-reported value in `0..=100`; `memory_footprint`
/// is the process resident memory size in bytes. `0` is used when the reporter /// is the process resident memory size in bytes. `0` is used when the reporter
/// platform did not expose the corresponding signal. /// platform did not expose the corresponding signal.
type MemorySample = (Timestamp, u64, u8, u64, u64); pub(crate) type MemorySample = (Timestamp, u64, u8, u64, u64);
/// Maximum number of memory samples returned in a query result. /// Maximum number of memory samples returned in a query result.
const MAX_MEMORY_SAMPLES: usize = 200; const MAX_MEMORY_SAMPLES: usize = 200;
...@@ -410,19 +410,31 @@ impl Store { ...@@ -410,19 +410,31 @@ impl Store {
start: Timestamp, start: Timestamp,
end: Timestamp, end: Timestamp,
) -> Vec<MemorySample> { ) -> Vec<MemorySample> {
self.memory_samples_for_range_downsampled(start, end, MAX_MEMORY_SAMPLES)
}
/// Like [`Self::memory_samples_for_range_with_ts`], but downsamples to at
/// most `max_samples` instead of `MAX_MEMORY_SAMPLES`.
pub fn memory_samples_for_range_downsampled(
&self,
start: Timestamp,
end: Timestamp,
max_samples: usize,
) -> Vec<MemorySample> {
let max_samples = max_samples.max(1);
let slice = self.memory_samples_slice(start, end); let slice = self.memory_samples_slice(start, end);
let count = slice.len(); let count = slice.len();
if count == 0 { if count == 0 {
return Vec::new(); return Vec::new();
} }
if count <= MAX_MEMORY_SAMPLES { if count <= max_samples {
return slice.to_vec(); return slice.to_vec();
} }
// Merge groups of N samples: timestamp and memory come from the // Merge groups of N samples: timestamp and memory come from the
// max-memory sample, pressure, footprint and workers are column maxes. // max-memory sample, pressure, footprint and workers are column maxes.
let n = count.div_ceil(MAX_MEMORY_SAMPLES); let n = count.div_ceil(max_samples);
slice slice
.chunks(n) .chunks(n)
.map(|chunk| { .map(|chunk| {
...@@ -510,7 +522,51 @@ impl Store { ...@@ -510,7 +522,51 @@ impl Store {
}) })
} }
fn memory_samples_slice(&self, start: Timestamp, end: Timestamp) -> &[MemorySample] { /// Timestamps of the first and last memory sample, or `None` without any.
#[allow(
dead_code,
reason = "only used by the query API in lib.rs, not the binary"
)]
pub fn memory_sample_range(&self) -> Option<(Timestamp, Timestamp)> {
Some((
self.memory_samples.first()?.0,
self.memory_samples.last()?.0,
))
}
/// Committed bytes and footprint at `ts`, linearly interpolated between the
/// samples on either side. Before the first sample or after the last, the
/// nearest one: the first sample often lands just after work starts, and
/// the longest spans lost their start reading. `None` only without any
/// samples.
///
/// Short spans often contain no sample at all, so this is what gives them
/// a memory reading.
#[allow(
dead_code,
reason = "only used by the query API in lib.rs, not the binary"
)]
pub fn memory_at(&self, ts: Timestamp) -> Option<(u64, u64)> {
let after = self.memory_samples.partition_point(|(t, ..)| *t < ts);
let Some(&(after_ts, after_mem, _, after_footprint, _)) = self.memory_samples.get(after)
else {
let &(_, mem, _, footprint, _) = self.memory_samples.last()?;
return Some((mem, footprint));
};
if after_ts == ts || after == 0 {
return Some((after_mem, after_footprint));
}
let (before_ts, before_mem, _, before_footprint, _) = self.memory_samples[after - 1];
let span = (*after_ts - *before_ts) as f64;
let t = (*ts - *before_ts) as f64 / span;
let lerp = |a: u64, b: u64| (a as f64 + (b as f64 - a as f64) * t).round() as u64;
Some((
lerp(before_mem, after_mem),
lerp(before_footprint, after_footprint),
))
}
pub(crate) fn memory_samples_slice(&self, start: Timestamp, end: Timestamp) -> &[MemorySample] {
// Binary search for the first sample >= start // Binary search for the first sample >= start
let lo = self.memory_samples.partition_point(|(ts, ..)| *ts < start); let lo = self.memory_samples.partition_point(|(ts, ..)| *ts < start);
// Binary search for the first sample > end // Binary search for the first sample > end
...@@ -695,6 +751,43 @@ mod tests { ...@@ -695,6 +751,43 @@ mod tests {
); );
} }
#[test]
fn memory_at_interpolates_between_samples() {
let mut store = Store::new();
// Without samples there is nothing to report.
assert_eq!(store.memory_at(Timestamp::from_micros(5)), None);
store.add_memory_sample(Timestamp::from_micros(10), 100, 0, 1000, 1);
store.add_memory_sample(Timestamp::from_micros(20), 200, 0, 3000, 1);
assert_eq!(
store.memory_at(Timestamp::from_micros(10)),
Some((100, 1000))
);
assert_eq!(
store.memory_at(Timestamp::from_micros(15)),
Some((150, 2000))
);
assert_eq!(
store.memory_at(Timestamp::from_micros(20)),
Some((200, 3000))
);
// Outside the sampled range, the nearest sample.
assert_eq!(
store.memory_at(Timestamp::from_micros(9)),
Some((100, 1000))
);
assert_eq!(
store.memory_at(Timestamp::from_micros(21)),
Some((200, 3000))
);
// Decreasing memory interpolates downwards.
store.add_memory_sample(Timestamp::from_micros(30), 0, 0, 0, 1);
assert_eq!(
store.memory_at(Timestamp::from_micros(25)),
Some((100, 1500))
);
}
fn ts(micros: u64) -> Timestamp { fn ts(micros: u64) -> Timestamp {
Timestamp::from_micros(micros) Timestamp::from_micros(micros)
} }
......
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