Skip to content

Commit f8704f4

Browse files
authored
feat: add Apple xctrace perf profiling (#755)
1 parent a35c444 commit f8704f4

24 files changed

Lines changed: 1917 additions & 70 deletions

‎src/__tests__/cli-perf.test.ts‎

Lines changed: 118 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -170,6 +170,122 @@ test('perf forwards shared perf kind values through CLI parsing', async () => {
170170
assert.equal(payload.error.code, 'INVALID_ARGS');
171171
});
172172

173+
test('perf cpu profile start forwards xctrace options to daemon positionals', async () => {
174+
const result = await runCliCapture(
175+
[
176+
'perf',
177+
'cpu',
178+
'profile',
179+
'start',
180+
'--kind',
181+
'xctrace',
182+
'--template',
183+
'Time Profiler',
184+
'--out',
185+
'app.trace',
186+
'--json',
187+
],
188+
async () => ({
189+
ok: true,
190+
data: {
191+
perf: 'started',
192+
kind: 'xctrace',
193+
mode: 'cpu-profile',
194+
outPath: '/tmp/app.trace',
195+
},
196+
}),
197+
);
198+
199+
assert.equal(result.code, null);
200+
assert.equal(result.calls[0]?.command, 'perf');
201+
assert.deepEqual(result.calls[0]?.positionals, [
202+
'cpu',
203+
'profile',
204+
'start',
205+
'xctrace',
206+
'Time Profiler',
207+
'app.trace',
208+
]);
209+
});
210+
211+
test('perf trace stop forwards xctrace trace artifact path', async () => {
212+
const result = await runCliCapture(
213+
['perf', 'trace', 'stop', '--kind', 'xctrace', '--out', 'hitches.trace', '--json'],
214+
async () => ({
215+
ok: true,
216+
data: {
217+
perf: 'stopped',
218+
kind: 'xctrace',
219+
mode: 'trace',
220+
outPath: '/tmp/hitches.trace',
221+
},
222+
}),
223+
);
224+
225+
assert.equal(result.code, null);
226+
assert.equal(result.calls[0]?.command, 'perf');
227+
assert.deepEqual(result.calls[0]?.positionals, ['trace', 'stop', 'xctrace', '', 'hitches.trace']);
228+
});
229+
230+
test('perf cpu profile report preserves the report out path when template is omitted', async () => {
231+
const result = await runCliCapture(
232+
[
233+
'perf',
234+
'cpu',
235+
'profile',
236+
'report',
237+
'--kind',
238+
'xctrace',
239+
'--out',
240+
'app-profile.json',
241+
'--json',
242+
],
243+
async () => ({
244+
ok: true,
245+
data: {
246+
perf: 'reported',
247+
kind: 'xctrace',
248+
mode: 'cpu-profile',
249+
reportPath: '/tmp/app-profile.json',
250+
},
251+
}),
252+
);
253+
254+
assert.equal(result.code, null);
255+
assert.equal(result.calls[0]?.command, 'perf');
256+
assert.deepEqual(result.calls[0]?.positionals, [
257+
'cpu',
258+
'profile',
259+
'report',
260+
'xctrace',
261+
'',
262+
'app-profile.json',
263+
]);
264+
});
265+
266+
test('perf xctrace output prints only compact artifact metadata by default', async () => {
267+
const result = await runCliCapture(
268+
['perf', 'cpu', 'profile', 'report', '--kind', 'xctrace', '--out', 'app-profile.json'],
269+
async () => ({
270+
ok: true,
271+
data: {
272+
perf: 'reported',
273+
kind: 'xctrace',
274+
mode: 'cpu-profile',
275+
reportPath: '/tmp/app-profile.json',
276+
tracePath: '/tmp/app.trace',
277+
summary: {
278+
tableSchemas: ['time-profile'],
279+
},
280+
},
281+
}),
282+
);
283+
284+
assert.equal(result.code, null);
285+
assert.equal(result.stdout, '/tmp/app-profile.json\nPerf cpu-profile: reported\n');
286+
assert.doesNotMatch(result.stdout, /time-profile|app\.trace/);
287+
});
288+
173289
test('perf sample defaults to metrics sample', async () => {
174290
const result = await runCliCapture(['perf', 'sample', '--json'], async () => ({
175291
ok: true,
@@ -206,7 +322,7 @@ test('perf area and action positionals are case-insensitive', async () => {
206322
assert.deepEqual(result.calls[0]?.positionals, ['frames', 'sample']);
207323
});
208324

209-
test('perf rejects unknown CLI area before daemon dispatch', async () => {
325+
test('perf rejects incomplete native CLI area before daemon dispatch', async () => {
210326
const result = await runCliCapture(['perf', 'cpu', '--json'], async () => ({
211327
ok: true,
212328
data: {},
@@ -216,7 +332,7 @@ test('perf rejects unknown CLI area before daemon dispatch', async () => {
216332
assert.equal(result.calls.length, 0);
217333
const payload = JSON.parse(result.stdout);
218334
assert.equal(payload.error.code, 'INVALID_ARGS');
219-
assert.match(payload.error.message, /perf area must be metrics, frames, or memory/i);
335+
assert.match(payload.error.message, /perf cpu requires profile/i);
220336
});
221337

222338
test('perf prints unavailable frame health reason by default', async () => {

‎src/client-types.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ import type {
4040
import type { MetroBridgeScope } from './client-companion-tunnel-contract.ts';
4141
import type { AppsFilter } from './contracts/app-inventory.ts';
4242
import type { ScreenshotRequestFlags } from './contracts/screenshot.ts';
43-
import type { PerfAction, PerfArea, PerfKind } from './contracts/perf.ts';
43+
import type { PerfAction, PerfArea, PerfKind, PerfSubject } from './contracts/perf.ts';
4444
import type { DaemonBatchStep } from './core/batch.ts';
4545
import type { AlertAction, AlertInfo } from './alert-contract.ts';
4646

@@ -741,9 +741,12 @@ export type BatchRunOptions = AgentDeviceRequestOverrides & {
741741

742742
export type PerfOptions = DeviceCommandBaseOptions & {
743743
area?: PerfArea;
744+
subject?: PerfSubject;
744745
action?: PerfAction;
745746
kind?: PerfKind;
747+
template?: string;
746748
out?: string;
749+
tracePath?: string;
747750
};
748751

749752
export type LogsOptions = AgentDeviceRequestOverrides & {

‎src/commands/cli-grammar/observability.ts‎

Lines changed: 84 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -13,12 +13,15 @@ import {
1313
isPerfAction,
1414
isPerfArea,
1515
isPerfKind,
16+
isPerfSubject,
1617
PERF_ACTION_ERROR_MESSAGE,
1718
PERF_AREA_ERROR_MESSAGE,
1819
PERF_KIND_ERROR_MESSAGE,
20+
PERF_SUBJECT_ERROR_MESSAGE,
1921
type PerfAction,
2022
type PerfArea,
2123
type PerfKind,
24+
type PerfSubject,
2225
} from '../perf-command-contract.ts';
2326
import {
2427
commonInputFromFlags,
@@ -33,9 +36,11 @@ import type { CliReader, DaemonWriter } from './types.ts';
3336
export const observabilityCliReaders = {
3437
perf: (positionals, flags) => ({
3538
...commonInputFromFlags(flags),
36-
...readPerfPositionals(positionals),
37-
kind: readPerfKind(flags.kind),
38-
out: flags.out,
39+
...readPerfPositionals(positionals, {
40+
kind: readPerfKindFlag(flags.kind),
41+
template: flags.perfTemplate,
42+
out: flags.out,
43+
}),
3944
}),
4045
logs: (positionals, flags) => ({
4146
...commonInputFromFlags(flags),
@@ -78,26 +83,76 @@ export const observabilityDaemonWriters = {
7883

7984
function perfPositionals(input: PerfOptions): string[] {
8085
const area = input.area ?? (input.action ? 'metrics' : undefined);
86+
if (area === 'cpu') {
87+
return nativePerfPositionals(
88+
[
89+
...optionalString(area),
90+
...optionalString(input.subject),
91+
...optionalString(input.action),
92+
...optionalString(input.kind),
93+
],
94+
input,
95+
);
96+
}
97+
if (area === 'trace') {
98+
return nativePerfPositionals(
99+
[...optionalString(area), ...optionalString(input.action), ...optionalString(input.kind)],
100+
input,
101+
);
102+
}
81103
return [...optionalString(area), ...optionalString(input.action)];
82104
}
83105

84-
function readPerfPositionals(positionals: string[]): Pick<PerfOptions, 'area' | 'action'> {
106+
function nativePerfPositionals(base: string[], input: PerfOptions): string[] {
107+
const positionals = [...base];
108+
if (input.template || input.out || input.tracePath) {
109+
positionals.push(input.template ?? '');
110+
}
111+
if (input.out || input.tracePath) {
112+
positionals.push(input.out ?? '');
113+
}
114+
if (input.tracePath) {
115+
positionals.push(input.tracePath);
116+
}
117+
return positionals;
118+
}
119+
120+
function readPerfPositionals(
121+
positionals: string[],
122+
flags: Pick<PerfOptions, 'kind' | 'template' | 'out'> = {},
123+
): Pick<PerfOptions, 'area' | 'subject' | 'action' | 'kind' | 'template' | 'out'> {
85124
if (positionals[0] !== undefined && positionals[1] === undefined) {
86125
const action = readPerfAction(positionals[0], { allowUndefined: true });
87-
if (action) return { action };
126+
if (action) return { action, kind: readPerfKind(flags.kind), out: flags.out };
127+
}
128+
const area = readPerfArea(positionals[0]);
129+
if (area === 'cpu') {
130+
return {
131+
area,
132+
subject: readPerfSubject(positionals[1]),
133+
action: readPerfAction(positionals[2]),
134+
kind: readPerfKind(flags.kind),
135+
template: flags.template,
136+
out: flags.out,
137+
};
138+
}
139+
if (area === 'trace') {
140+
return {
141+
area,
142+
action: readPerfAction(positionals[1]),
143+
kind: readPerfKind(flags.kind),
144+
template: flags.template,
145+
out: flags.out,
146+
};
88147
}
89148
return {
90-
area: readPerfArea(positionals[0]),
149+
area,
91150
action: readPerfAction(positionals[1]),
151+
kind: readPerfKind(flags.kind),
152+
out: flags.out,
92153
};
93154
}
94155

95-
function readPerfKind(value: string | undefined): PerfKind | undefined {
96-
if (value === undefined) return undefined;
97-
if (isPerfKind(value)) return value;
98-
throw new AppError('INVALID_ARGS', PERF_KIND_ERROR_MESSAGE);
99-
}
100-
101156
function logsPositionals(input: { action?: string; message?: string }): string[] {
102157
return [input.action ?? 'path', ...optionalString(input.message)];
103158
}
@@ -133,6 +188,23 @@ function readPerfAction(
133188
throw new AppError('INVALID_ARGS', PERF_ACTION_ERROR_MESSAGE);
134189
}
135190

191+
function readPerfSubject(value: string | undefined): PerfSubject {
192+
const normalized = value?.toLowerCase();
193+
if (normalized !== undefined && isPerfSubject(normalized)) return normalized;
194+
throw new AppError('INVALID_ARGS', PERF_SUBJECT_ERROR_MESSAGE);
195+
}
196+
197+
function readPerfKind(value: string | undefined): PerfKind | undefined {
198+
if (value === undefined) return undefined;
199+
const normalized = value.toLowerCase();
200+
if (isPerfKind(normalized)) return normalized;
201+
throw new AppError('INVALID_ARGS', PERF_KIND_ERROR_MESSAGE);
202+
}
203+
204+
function readPerfKindFlag(value: unknown): PerfKind | undefined {
205+
return typeof value === 'string' ? readPerfKind(value) : undefined;
206+
}
207+
136208
function readLogsAction(value: string | undefined): LogAction | undefined {
137209
if (value === undefined) return undefined;
138210
return parseStringMember(LOG_ACTION_VALUES, value, {

‎src/commands/client-command-metadata.ts‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,12 @@ import {
2323
type CommandFieldMap,
2424
} from './command-input.ts';
2525
import { defineFieldCommandMetadata } from './field-command-contract.ts';
26-
import { PERF_ACTION_VALUES, PERF_AREA_VALUES, PERF_KIND_VALUES } from './perf-command-contract.ts';
26+
import {
27+
PERF_ACTION_VALUES,
28+
PERF_AREA_VALUES,
29+
PERF_KIND_VALUES,
30+
PERF_SUBJECT_VALUES,
31+
} from './perf-command-contract.ts';
2732
import { WAIT_KIND_VALUES } from './wait-command-contract.ts';
2833

2934
const CLIPBOARD_ACTION_VALUES = ['read', 'write'] as const;
@@ -182,9 +187,12 @@ export const clientCommandMetadata = [
182187
}),
183188
defineClientCommandMetadata('perf', {
184189
area: enumField(PERF_AREA_VALUES),
190+
subject: enumField(PERF_SUBJECT_VALUES),
185191
action: enumField(PERF_ACTION_VALUES),
186192
kind: enumField(PERF_KIND_VALUES),
187-
out: stringField(),
193+
template: stringField('xctrace template name, for example Time Profiler.'),
194+
out: stringField('Output artifact path.'),
195+
tracePath: stringField('Existing .trace path to report, defaults to the latest session trace.'),
188196
}),
189197
defineClientCommandMetadata('logs', {
190198
action: enumField(LOG_ACTION_VALUES),

‎src/commands/runtime-output.ts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,8 @@ function joinDefinedLines(lines: Array<string | undefined>): string | undefined
147147
}
148148

149149
function formatPerfCliOutput(data: Record<string, unknown>): string {
150+
const nativeOutput = formatNativePerfOutput(data);
151+
if (nativeOutput) return nativeOutput;
150152
const artifact = readRecord(data.artifact);
151153
if (artifact) {
152154
return formatMemoryArtifactSummary(artifact);
@@ -190,6 +192,30 @@ function formatMemoryArtifactSummary(artifact: Record<string, unknown>): string
190192
: `Memory artifact (${kind}): captured${sizeText}`;
191193
}
192194

195+
function formatNativePerfOutput(data: Record<string, unknown>): string | undefined {
196+
const state = typeof data.perf === 'string' ? data.perf : undefined;
197+
const outPath = readNativePerfArtifactPath(data);
198+
if (!state || !outPath || data.kind !== 'xctrace') return undefined;
199+
const mode = typeof data.mode === 'string' ? data.mode : 'capture';
200+
return formatNativePerfLines(outPath, mode, state, data.template);
201+
}
202+
203+
function readNativePerfArtifactPath(data: Record<string, unknown>): string | undefined {
204+
if (typeof data.outPath === 'string') return data.outPath;
205+
return typeof data.reportPath === 'string' ? data.reportPath : undefined;
206+
}
207+
208+
function formatNativePerfLines(
209+
outPath: string,
210+
mode: string,
211+
state: string,
212+
template: unknown,
213+
): string {
214+
const lines = [outPath, `Perf ${mode}: ${state}`];
215+
if (typeof template === 'string') lines.push(`Template: ${template}`);
216+
return lines.join('\n');
217+
}
218+
193219
function formatPerfUnavailable(resourceSummary: string | undefined, reason: string): string {
194220
return resourceSummary
195221
? `Performance: ${resourceSummary}`

0 commit comments

Comments
 (0)