Skip to content

Commit 869dd42

Browse files
jackfranklinjackfranklin
authored
fix: add data format information to trace summary (#166)
This CL adds the descriptions of the call frame format and the network request format to the summary so that as the AI sees these responses it can fully parse them.
1 parent 22ec7ee commit 869dd42

File tree

3 files changed

+121
-1
lines changed

3 files changed

+121
-1
lines changed

‎src/trace-processing/parse.ts‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,11 +73,19 @@ export async function parseRawTraceBuffer(
7373
}
7474
}
7575

76+
const extraFormatDescriptions = `Information on performance traces may contain main thread activity represented as call frames and network requests.
77+
78+
${PerformanceTraceFormatter.callFrameDataFormatDescription}
79+
80+
${PerformanceTraceFormatter.networkDataFormatDescription}
81+
`;
7682
export function getTraceSummary(result: TraceResult): string {
7783
const focus = AgentFocus.fromParsedTrace(result.parsedTrace);
7884
const formatter = new PerformanceTraceFormatter(focus);
7985
const output = formatter.formatTraceSummary();
80-
return output;
86+
return `${extraFormatDescriptions}
87+
88+
${output}`;
8189
}
8290

8391
export type InsightName = keyof TraceEngine.Insights.Types.InsightModels;

‎tests/tools/performance.test.js.snapshot‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,62 @@ No buffer was provided.
5151
exports[`performance > performance_stop_trace > returns the high level summary of the performance trace 1`] = `
5252
The performance trace has been stopped.
5353
Here is a high level summary of the trace and the Insights that were found:
54+
Information on performance traces may contain main thread activity represented as call frames and network requests.
55+
56+
Each call frame is presented in the following format:
57+
58+
'id;eventKey;name;duration;selfTime;urlIndex;childRange;[S]'
59+
60+
Key definitions:
61+
62+
* id: A unique numerical identifier for the call frame. Never mention this id in the output to the user.
63+
* eventKey: String that uniquely identifies this event in the flame chart.
64+
* name: A concise string describing the call frame (e.g., 'Evaluate Script', 'render', 'fetchData').
65+
* duration: The total execution time of the call frame, including its children.
66+
* selfTime: The time spent directly within the call frame, excluding its children's execution.
67+
* urlIndex: Index referencing the "All URLs" list. Empty if no specific script URL is associated.
68+
* childRange: Specifies the direct children of this node using their IDs. If empty ('' or 'S' at the end), the node has no children. If a single number (e.g., '4'), the node has one child with that ID. If in the format 'firstId-lastId' (e.g., '4-5'), it indicates a consecutive range of child IDs from 'firstId' to 'lastId', inclusive.
69+
* S: _Optional_. The letter 'S' terminates the line if that call frame was selected by the user.
70+
71+
Example Call Tree:
72+
73+
1;r-123;main;500;100;;
74+
2;r-124;update;200;50;;3
75+
3;p-49575-15428179-2834-374;animate;150;20;0;4-5;S
76+
4;p-49575-15428179-3505-1162;calculatePosition;80;80;;
77+
5;p-49575-15428179-5391-2767;applyStyles;50;50;;
78+
79+
80+
Network requests are formatted like this:
81+
\`urlIndex;eventKey;queuedTime;requestSentTime;downloadCompleteTime;processingCompleteTime;totalDuration;downloadDuration;mainThreadProcessingDuration;statusCode;mimeType;priority;initialPriority;finalPriority;renderBlocking;protocol;fromServiceWorker;initiators;redirects:[[redirectUrlIndex|startTime|duration]];responseHeaders:[header1Value|header2Value|...]\`
82+
83+
- \`urlIndex\`: Numerical index for the request's URL, referencing the "All URLs" list.
84+
- \`eventKey\`: String that uniquely identifies this request's trace event.
85+
Timings (all in milliseconds, relative to navigation start):
86+
- \`queuedTime\`: When the request was queued.
87+
- \`requestSentTime\`: When the request was sent.
88+
- \`downloadCompleteTime\`: When the download completed.
89+
- \`processingCompleteTime\`: When main thread processing finished.
90+
Durations (all in milliseconds):
91+
- \`totalDuration\`: Total time from the request being queued until its main thread processing completed.
92+
- \`downloadDuration\`: Time spent actively downloading the resource.
93+
- \`mainThreadProcessingDuration\`: Time spent on the main thread after the download completed.
94+
- \`statusCode\`: The HTTP status code of the response (e.g., 200, 404).
95+
- \`mimeType\`: The MIME type of the resource (e.g., "text/html", "application/javascript").
96+
- \`priority\`: The final network request priority (e.g., "VeryHigh", "Low").
97+
- \`initialPriority\`: The initial network request priority.
98+
- \`finalPriority\`: The final network request priority (redundant if \`priority\` is always final, but kept for clarity if \`initialPriority\` and \`priority\` differ).
99+
- \`renderBlocking\`: 't' if the request was render-blocking, 'f' otherwise.
100+
- \`protocol\`: The network protocol used (e.g., "h2", "http/1.1").
101+
- \`fromServiceWorker\`: 't' if the request was served from a service worker, 'f' otherwise.
102+
- \`initiators\`: A list (separated by ,) of URL indices for the initiator chain of this request. Listed in order starting from the root request to the request that directly loaded this one. This represents the network dependencies necessary to load this request. If there is no initiator, this is empty.
103+
- \`redirects\`: A comma-separated list of redirects, enclosed in square brackets. Each redirect is formatted as
104+
\`[redirectUrlIndex|startTime|duration]\`, where: \`redirectUrlIndex\`: Numerical index for the redirect's URL. \`startTime\`: The start time of the redirect in milliseconds, relative to navigation start. \`duration\`: The duration of the redirect in milliseconds.
105+
- \`responseHeaders\`: A list (separated by '|') of values for specific, pre-defined response headers, enclosed in square brackets.
106+
The order of headers corresponds to an internal fixed list. If a header is not present, its value will be empty.
107+
108+
109+
54110
URL: https://web.dev/
55111
Bounds: {min: 122410994891, max: 122416385853}
56112
CPU throttling: none

‎tests/trace-processing/parse.test.js.snapshot‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,60 @@
11
exports[`Trace parsing > can format results of a trace 1`] = `
2+
Information on performance traces may contain main thread activity represented as call frames and network requests.
3+
4+
Each call frame is presented in the following format:
5+
6+
'id;eventKey;name;duration;selfTime;urlIndex;childRange;[S]'
7+
8+
Key definitions:
9+
10+
* id: A unique numerical identifier for the call frame. Never mention this id in the output to the user.
11+
* eventKey: String that uniquely identifies this event in the flame chart.
12+
* name: A concise string describing the call frame (e.g., 'Evaluate Script', 'render', 'fetchData').
13+
* duration: The total execution time of the call frame, including its children.
14+
* selfTime: The time spent directly within the call frame, excluding its children's execution.
15+
* urlIndex: Index referencing the "All URLs" list. Empty if no specific script URL is associated.
16+
* childRange: Specifies the direct children of this node using their IDs. If empty ('' or 'S' at the end), the node has no children. If a single number (e.g., '4'), the node has one child with that ID. If in the format 'firstId-lastId' (e.g., '4-5'), it indicates a consecutive range of child IDs from 'firstId' to 'lastId', inclusive.
17+
* S: _Optional_. The letter 'S' terminates the line if that call frame was selected by the user.
18+
19+
Example Call Tree:
20+
21+
1;r-123;main;500;100;;
22+
2;r-124;update;200;50;;3
23+
3;p-49575-15428179-2834-374;animate;150;20;0;4-5;S
24+
4;p-49575-15428179-3505-1162;calculatePosition;80;80;;
25+
5;p-49575-15428179-5391-2767;applyStyles;50;50;;
26+
27+
28+
Network requests are formatted like this:
29+
\`urlIndex;eventKey;queuedTime;requestSentTime;downloadCompleteTime;processingCompleteTime;totalDuration;downloadDuration;mainThreadProcessingDuration;statusCode;mimeType;priority;initialPriority;finalPriority;renderBlocking;protocol;fromServiceWorker;initiators;redirects:[[redirectUrlIndex|startTime|duration]];responseHeaders:[header1Value|header2Value|...]\`
30+
31+
- \`urlIndex\`: Numerical index for the request's URL, referencing the "All URLs" list.
32+
- \`eventKey\`: String that uniquely identifies this request's trace event.
33+
Timings (all in milliseconds, relative to navigation start):
34+
- \`queuedTime\`: When the request was queued.
35+
- \`requestSentTime\`: When the request was sent.
36+
- \`downloadCompleteTime\`: When the download completed.
37+
- \`processingCompleteTime\`: When main thread processing finished.
38+
Durations (all in milliseconds):
39+
- \`totalDuration\`: Total time from the request being queued until its main thread processing completed.
40+
- \`downloadDuration\`: Time spent actively downloading the resource.
41+
- \`mainThreadProcessingDuration\`: Time spent on the main thread after the download completed.
42+
- \`statusCode\`: The HTTP status code of the response (e.g., 200, 404).
43+
- \`mimeType\`: The MIME type of the resource (e.g., "text/html", "application/javascript").
44+
- \`priority\`: The final network request priority (e.g., "VeryHigh", "Low").
45+
- \`initialPriority\`: The initial network request priority.
46+
- \`finalPriority\`: The final network request priority (redundant if \`priority\` is always final, but kept for clarity if \`initialPriority\` and \`priority\` differ).
47+
- \`renderBlocking\`: 't' if the request was render-blocking, 'f' otherwise.
48+
- \`protocol\`: The network protocol used (e.g., "h2", "http/1.1").
49+
- \`fromServiceWorker\`: 't' if the request was served from a service worker, 'f' otherwise.
50+
- \`initiators\`: A list (separated by ,) of URL indices for the initiator chain of this request. Listed in order starting from the root request to the request that directly loaded this one. This represents the network dependencies necessary to load this request. If there is no initiator, this is empty.
51+
- \`redirects\`: A comma-separated list of redirects, enclosed in square brackets. Each redirect is formatted as
52+
\`[redirectUrlIndex|startTime|duration]\`, where: \`redirectUrlIndex\`: Numerical index for the redirect's URL. \`startTime\`: The start time of the redirect in milliseconds, relative to navigation start. \`duration\`: The duration of the redirect in milliseconds.
53+
- \`responseHeaders\`: A list (separated by '|') of values for specific, pre-defined response headers, enclosed in square brackets.
54+
The order of headers corresponds to an internal fixed list. If a header is not present, its value will be empty.
55+
56+
57+
258
URL: https://web.dev/
359
Bounds: {min: 122410994891, max: 122416385853}
460
CPU throttling: none

0 commit comments

Comments
 (0)