Unverified Commit f7dee1b8 authored by Luke Sandberg's avatar Luke Sandberg Committed by GitHub

[turbopack-trace-server] Add memory samples to the mcp tool results (#93338)

Expose memory data to the MCP tool for the turbo trace server
parent f49ed227
...@@ -62,6 +62,14 @@ pub struct TraceSpanInfo { ...@@ -62,6 +62,14 @@ pub struct TraceSpanInfo {
pub avg_corrected_duration: Option<i64>, pub avg_corrected_duration: Option<i64>,
/// Raw span ID for aggregated groups (the index of the first span). /// Raw span ID for aggregated groups (the index of the first span).
pub first_span_id: Option<String>, pub first_span_id: Option<String>,
/// TurboMalloc memory-usage samples recorded while this span
/// (or its example span, for aggregated groups) was live.
///
/// 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.
pub memory_samples: Vec<Vec<i64>>,
} }
/// The result of a `query_trace_spans` call. /// The result of a `query_trace_spans` call.
...@@ -125,6 +133,11 @@ pub fn query_trace_spans( ...@@ -125,6 +133,11 @@ pub fn query_trace_spans(
total_corrected_duration: s.total_corrected_duration.map(|v| v as i64), total_corrected_duration: s.total_corrected_duration.map(|v| v as i64),
avg_corrected_duration: s.avg_corrected_duration.map(|v| v as i64), avg_corrected_duration: s.avg_corrected_duration.map(|v| v as i64),
first_span_id: s.first_span_id, first_span_id: s.first_span_id,
memory_samples: s
.memory_samples
.into_iter()
.map(|(ts, mem, pressure)| vec![ts, mem as i64, pressure as i64])
.collect(),
}) })
.collect(), .collect(),
page: result.page as u32, page: result.page as u32,
......
...@@ -670,6 +670,16 @@ export interface TraceSpanInfo { ...@@ -670,6 +670,16 @@ export interface TraceSpanInfo {
avgCorrectedDuration?: number avgCorrectedDuration?: number
/** Raw span ID for aggregated groups (the index of the first span). */ /** Raw span ID for aggregated groups (the index of the first span). */
firstSpanId?: string firstSpanId?: string
/**
* TurboMalloc memory-usage samples recorded while this span
* (or its example span, for aggregated groups) was live.
*
* 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>>
} }
/** The result of a `query_trace_spans` call. */ /** The result of a `query_trace_spans` call. */
export interface TraceQueryResult { export interface TraceQueryResult {
......
...@@ -34,6 +34,34 @@ function formatRelative(ticks: number): string { ...@@ -34,6 +34,34 @@ function formatRelative(ticks: number): string {
return prefix + formatDuration(Math.abs(ticks)) return prefix + formatDuration(Math.abs(ticks))
} }
function formatBytes(bytes: number): string {
const KB = 1024
const MB = KB * 1024
const GB = MB * 1024
if (bytes >= GB) return `${(bytes / GB).toFixed(2)} GB`
if (bytes >= MB) return `${(bytes / MB).toFixed(2)} MB`
if (bytes >= KB) return `${(bytes / KB).toFixed(2)} KB`
return `${bytes} B`
}
function summarizeMemorySamples(samples: number[][]): string | null {
if (!samples || samples.length === 0) return null
const bytes = samples.map((s) => s[1])
const pressures = samples.map((s) => s[2] ?? 0)
const min = Math.min(...bytes)
const max = Math.max(...bytes)
const first = bytes[0]
const last = bytes[bytes.length - 1]
const delta = last - first
const deltaSign = delta >= 0 ? '+' : '-'
const maxPressure = Math.max(...pressures)
return (
`samples=${samples.length}, min=${formatBytes(min)}, max=${formatBytes(max)}, ` +
`start=${formatBytes(first)}, end=${formatBytes(last)}, ` +
`Δ=${deltaSign}${formatBytes(Math.abs(delta))}, maxPressure=${maxPressure}`
)
}
/** /**
* Render a single span (or aggregated span group) as a markdown section. * Render a single span (or aggregated span group) as a markdown section.
*/ */
...@@ -74,6 +102,11 @@ function renderSpanMarkdown(span: TraceSpanInfo): string { ...@@ -74,6 +102,11 @@ function renderSpanMarkdown(span: TraceSpanInfo): string {
} }
} }
const memSummary = summarizeMemorySamples(span.memorySamples)
if (memSummary) {
md += `\n**Memory (TurboMalloc live bytes):** ${memSummary}\n`
}
md += '\n---\n\n' md += '\n---\n\n'
return md return md
} }
...@@ -121,7 +154,7 @@ export async function startTurboTraceServerCli( ...@@ -121,7 +154,7 @@ export async function startTurboTraceServerCli(
'query_spans', 'query_spans',
{ {
description: description:
'Query spans from a turbopack trace file. Returns spans with timing, CPU usage, and attribute details. Set `outputType` to "json" for machine-readable output or "markdown" (default) for human-readable output. Use the `parent` parameter (with an ID from a previous result) to drill into children. Results are paginated to 20 spans per page.', 'Query spans from a turbopack trace file. Returns spans with timing, CPU usage, attribute details, and TurboMalloc live-memory samples recorded while each span was active. Set `outputType` to "json" for machine-readable output (including the raw `memorySamples` array of `[ts_offset_ticks, bytes, pressure]` triples per span — pressure is 0 = none, higher = more memory pressure) or "markdown" (default) for a human-readable summary. Use the `parent` parameter (with an ID from a previous result) to drill into children. Results are paginated to 20 spans per page.',
inputSchema: { inputSchema: {
parent: z parent: z
.string() .string()
......
...@@ -129,6 +129,19 @@ pub struct SpanInfo { ...@@ -129,6 +129,19 @@ pub struct SpanInfo {
pub avg_corrected_duration: Option<u64>, pub avg_corrected_duration: Option<u64>,
/// Raw span ID for aggregated groups (the index of the first span). /// Raw span ID for aggregated groups (the index of the first span).
pub first_span_id: Option<String>, pub first_span_id: Option<String>,
/// TurboMalloc memory-usage samples recorded while this span (or its
/// example span, for aggregated groups) was live.
///
/// Each tuple is `(ts_offset_from_span_start_in_ticks, bytes, pressure)`,
/// where `pressure` is the memory-pressure byte recorded with the sample
/// (0 = no pressure, higher = more pressure). `100 ticks = 1 µs`. The
/// offset is always `>= 0` and `<= span_duration`.
///
/// The store caps the series at `MAX_MEMORY_SAMPLES`; when more samples
/// exist in the range, consecutive groups are merged by picking the
/// group's max-memory sample (timestamp, value, and pressure kept
/// together).
pub memory_samples: Vec<(i64, u64, u8)>,
} }
/// Result of a `query_spans` call. /// Result of a `query_spans` call.
...@@ -283,6 +296,15 @@ pub fn query_spans(store: &Arc<StoreContainer>, options: QueryOptions) -> QueryR ...@@ -283,6 +296,15 @@ pub fn query_spans(store: &Arc<StoreContainer>, options: QueryOptions) -> QueryR
let rel_start = (span_start as i64) - (parent_start as i64); let rel_start = (span_start as i64) - (parent_start as i64);
let rel_end = (span_end as i64) - (parent_start as i64); let rel_end = (span_end as i64) - (parent_start as i64);
let first_start_ticks = *first.start();
let memory_samples: Vec<(i64, u64, u8)> = store_ref
.memory_samples_for_range_with_ts(first.start(), first.end())
.into_iter()
.map(|(ts, mem, pressure)| {
((*ts as i64) - (first_start_ticks as i64), mem, pressure)
})
.collect();
SpanInfo { SpanInfo {
id: graph_id, id: graph_id,
name, name,
...@@ -301,6 +323,7 @@ pub fn query_spans(store: &Arc<StoreContainer>, options: QueryOptions) -> QueryR ...@@ -301,6 +323,7 @@ pub fn query_spans(store: &Arc<StoreContainer>, options: QueryOptions) -> QueryR
total_corrected_duration: Some(total_corrected), total_corrected_duration: Some(total_corrected),
avg_corrected_duration: Some(avg_corrected), avg_corrected_duration: Some(avg_corrected),
first_span_id: Some(first_index.to_string()), first_span_id: Some(first_index.to_string()),
memory_samples,
} }
}) })
.collect(); .collect();
...@@ -361,6 +384,15 @@ pub fn query_spans(store: &Arc<StoreContainer>, options: QueryOptions) -> QueryR ...@@ -361,6 +384,15 @@ pub fn query_spans(store: &Arc<StoreContainer>, options: QueryOptions) -> QueryR
let rel_start = (span_start as i64) - (parent_start as i64); let rel_start = (span_start as i64) - (parent_start as i64);
let rel_end = (span_end as i64) - (parent_start as i64); let rel_end = (span_end as i64) - (parent_start as i64);
let raw_span_start = span_start;
let memory_samples: Vec<(i64, u64, u8)> = store_ref
.memory_samples_for_range_with_ts(span.start(), span.end())
.into_iter()
.map(|(ts, mem, pressure)| {
((*ts as i64) - (raw_span_start as i64), mem, pressure)
})
.collect();
SpanInfo { SpanInfo {
id: build_span_id(options.parent.as_deref(), &span.index.to_string()), id: build_span_id(options.parent.as_deref(), &span.index.to_string()),
name, name,
...@@ -379,6 +411,7 @@ pub fn query_spans(store: &Arc<StoreContainer>, options: QueryOptions) -> QueryR ...@@ -379,6 +411,7 @@ pub fn query_spans(store: &Arc<StoreContainer>, options: QueryOptions) -> QueryR
total_corrected_duration: None, total_corrected_duration: None,
avg_corrected_duration: None, avg_corrected_duration: None,
first_span_id: None, first_span_id: None,
memory_samples,
} }
}) })
.collect(); .collect();
......
...@@ -357,6 +357,23 @@ impl Store { ...@@ -357,6 +357,23 @@ impl Store {
/// `[start, end]`. When more samples exist, groups of N consecutive /// `[start, end]`. When more samples exist, groups of N consecutive
/// samples are merged by taking the maximum memory value in each group. /// samples are merged by taking the maximum memory value in each group.
pub fn memory_samples_for_range(&self, start: Timestamp, end: Timestamp) -> Vec<u64> { pub fn memory_samples_for_range(&self, start: Timestamp, end: Timestamp) -> Vec<u64> {
self.memory_samples_for_range_with_ts(start, end)
.into_iter()
.map(|(_, mem, _)| mem)
.collect()
}
/// Like `memory_samples_for_range` but keeps the timestamps and the
/// memory-pressure byte. Timestamps are absolute store timestamps (same
/// reference frame as span start/end). When the raw slice exceeds
/// `MAX_MEMORY_SAMPLES`, each merged group is represented by the sample
/// whose memory value was the group's max (its timestamp and pressure
/// byte are kept alongside it).
pub fn memory_samples_for_range_with_ts(
&self,
start: Timestamp,
end: Timestamp,
) -> Vec<MemorySample> {
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 {
...@@ -364,14 +381,15 @@ impl Store { ...@@ -364,14 +381,15 @@ impl Store {
} }
if count <= MAX_MEMORY_SAMPLES { if count <= MAX_MEMORY_SAMPLES {
return slice.iter().map(|(_, mem, _)| *mem).collect(); return slice.to_vec();
} }
// Merge groups of N samples, taking the max memory in each group. // Merge groups of N samples, taking the max memory in each group and
// keeping the timestamp and pressure of that max sample.
let n = count.div_ceil(MAX_MEMORY_SAMPLES); let n = count.div_ceil(MAX_MEMORY_SAMPLES);
slice slice
.chunks(n) .chunks(n)
.map(|chunk| chunk.iter().map(|(_, mem, _)| *mem).max().unwrap()) .map(|chunk| *chunk.iter().max_by_key(|(_, mem, _)| *mem).unwrap())
.collect() .collect()
} }
......
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