Add script for collecting CPU profile information

This commit is contained in:
James Babcock committed 2026-09-22 11:54:45 -07:00
1 parent 392554dd37
commit 44eddedc01
5 files changed
+481

No files matched your search

+304
View File
@@ -0,0 +1,304 @@
#!/usr/bin/env node
'use strict';
// Host-side only: ART samples the process; V8 samples each JS isolate over CDP.
const fs = require('node:fs');
const path = require('node:path');
const { execFileSync } = require('node:child_process');
const { SourceMap } = require('node:module');
const HELP = `Usage: npm run profile:android -- [options]
--device SERIAL ADB device (or ANDROID_SERIAL; required if ambiguous)
--seconds N Recording duration, 1–300 (default: 10)
--mode all|js|art V8 TypeScript/JS, ART Java/Kotlin, or both (default: all)
--interval N Sampling interval in microseconds, 100–1000000 (default: 1000)
--out DIRECTORY New output directory (default: profiles/<timestamp>)
--package ID App package (default: com.faceclaw.app)
--no-source-maps Keep only generated JS locations
Requires Node 22+, adb, and an already running debug build. No rebuild or restart.
Reproduce the workload while recording. Ctrl-C stops and saves early.
Disconnect other debuggers/profilers first. See scripts/profile-android.md.
`;
function parseArgs(args, env = process.env) {
const options = { device: env.ANDROID_SERIAL, seconds: 10, mode: 'all', interval: 1000,
package: 'com.faceclaw.app', sourceMaps: true };
for (let i = 0; i < args.length; i++) {
const arg = args[i];
if (arg === '--help' || arg === '-h') return { help: true };
if (arg === '--no-source-maps') { options.sourceMaps = false; continue; }
if (!['--device', '--seconds', '--mode', '--interval', '--out', '--package'].includes(arg)) {
throw new Error(`Unknown option: ${arg}`);
}
const value = args[++i];
if (!value || value.startsWith('--')) throw new Error(`Missing value for ${arg}`);
options[arg.slice(2)] = ['--seconds', '--interval'].includes(arg) ? Number(value) : value;
}
if (!Number.isFinite(options.seconds) || options.seconds < 1 || options.seconds > 300) throw new Error('--seconds must be between 1 and 300.');
if (!Number.isInteger(options.interval) || options.interval < 100 || options.interval > 1000000) throw new Error('--interval must be an integer between 100 and 1000000.');
if (!['all', 'js', 'art'].includes(options.mode)) throw new Error('--mode must be all, js, or art.');
// ADB shell joins arguments into a remote shell command. Keep all interpolated
// remote paths and package names restricted, even though execFile uses no shell.
if (!/^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)+$/.test(options.package)) throw new Error('Invalid Android package ID.');
return options;
}
class Inspector {
constructor(socket) {
this.socket = socket;
this.nextId = 0;
this.pending = new Map();
this.onEvent = () => {};
socket.addEventListener('message', ({ data }) => {
const message = JSON.parse(data);
if (!message.id) { this.onEvent(message); return; }
const pending = this.pending.get(message.id);
if (!pending) return;
this.pending.delete(message.id);
clearTimeout(pending.timer);
if (message.error) pending.reject(new Error(`${pending.method}: ${message.error.message}`));
else pending.resolve(message.result);
});
const disconnected = () => {
for (const pending of this.pending.values()) {
clearTimeout(pending.timer);
pending.reject(new Error('NativeScript inspector disconnected.'));
}
this.pending.clear();
};
socket.addEventListener('close', disconnected);
socket.addEventListener('error', disconnected);
}
static async connect(port) {
const socket = new WebSocket(`ws://127.0.0.1:${port}`);
const inspector = new Inspector(socket);
await new Promise((resolve, reject) => {
const timer = setTimeout(() => { socket.close(); reject(new Error('Inspector connection timed out. Is this a running NativeScript debug build?')); }, 10000);
socket.addEventListener('open', () => { clearTimeout(timer); resolve(); }, { once: true });
socket.addEventListener('error', () => { clearTimeout(timer); reject(new Error('Cannot connect to NativeScript inspector. Use a running debug build.')); }, { once: true });
});
return inspector;
}
call(method, params = {}, sessionId) {
if (this.socket.readyState !== WebSocket.OPEN) return Promise.reject(new Error('Inspector is not connected.'));
const id = ++this.nextId;
return new Promise((resolve, reject) => {
const timer = setTimeout(() => {
this.pending.delete(id);
reject(new Error(`${method} timed out${sessionId ? ` (${sessionId})` : ''}.`));
}, 10000);
this.pending.set(id, { resolve, reject, timer, method });
this.socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
});
}
close() { this.socket.close(); }
}
function remapProfile(profile, maps) {
const mapped = structuredClone(profile);
let mappedNodes = 0;
for (const node of mapped.nodes) {
const frame = node.callFrame;
const map = maps.get(frame.url);
if (!map || frame.lineNumber < 0 || frame.columnNumber < 0) continue;
const entry = map.findEntry(frame.lineNumber, frame.columnNumber);
if (!entry.originalSource || entry.originalLine === undefined) continue;
frame.url = entry.originalSource;
frame.lineNumber = entry.originalLine;
frame.columnNumber = entry.originalColumn;
if (entry.name) frame.functionName = entry.name;
// V8's generated line ticks no longer describe this source file. Keep them
// in the raw profile, but don't show misleading line counts in the mapped one.
delete node.positionTicks;
mappedNodes++;
}
return { profile: mapped, mappedNodes };
}
function traceSummary(buffer) {
const end = buffer.indexOf('*end\n');
if (end < 0 || buffer.subarray(0, 8).toString() !== '*version') throw new Error('ART did not produce a valid method trace.');
const header = buffer.subarray(0, end).toString();
const methods = header.split('*methods\n')[1]?.trim().split('\n') || [];
return { bytes: buffer.length, overflow: header.includes('data-file-overflow=true'),
methods: methods.length,
faceclawMethods: methods.filter(line => line.includes('\tcom.faceclaw.')).length,
kotlinMethods: methods.filter(line => /\.kt(?:\t|$)/.test(line)).length };
}
async function record(options) {
if (typeof WebSocket === 'undefined') throw new Error('Node 22+ is required (built-in WebSocket).');
const adb = (...args) => execFileSync('adb', [...(options.device ? ['-s', options.device] : []), ...args],
{ encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, timeout: 30000, stdio: ['ignore', 'pipe', 'pipe'] });
if (!options.device) {
const devices = adb('devices').split('\n').filter(line => /\tdevice\s*$/.test(line)).map(line => line.split('\t')[0]);
if (devices.length !== 1) throw new Error(`Found ${devices.length} ADB devices. Select one with --device SERIAL.`);
options.device = devices[0];
}
const pids = adb('shell', 'pidof', options.package).trim().split(/\s+/);
if (pids.length !== 1 || !/^\d+$/.test(pids[0])) throw new Error('Start Faceclaw before profiling; expected one app process.');
const pid = pids[0];
try { adb('shell', 'run-as', options.package, 'id'); }
catch { throw new Error('Profiling requires an installed debug build (run-as failed). Build with ./build.sh --env.sourceMap=source-map.'); }
const stamp = new Date().toISOString().replace(/[:.]/g, '-');
const output = path.resolve(options.out || path.join('profiles', stamp));
fs.mkdirSync(path.dirname(output), { recursive: true });
fs.mkdirSync(output); // Refuse to overwrite an earlier capture.
const remoteTrace = `/data/local/tmp/faceclaw-${stamp}-${process.pid}.trace`;
const summary = { device: options.device, package: options.package, pid, mode: options.mode,
intervalUs: options.interval, requestedSeconds: options.seconds, startedAt: new Date().toISOString(),
profiles: [], warnings: [] };
const warn = message => { summary.warnings.push(message); console.error(`Warning: ${message}`); };
let port, inspector, artStarted = false, stopping = false, interrupted = false, wake;
const targets = new Map();
const stopEarly = () => { interrupted = true; if (wake) wake(); };
process.on('SIGINT', stopEarly);
process.on('SIGTERM', stopEarly);
let failure;
async function startTarget(sessionId, title) {
const key = sessionId || 'main';
if (targets.has(key) || stopping) return;
const target = { sessionId, title, key, started: false };
targets.set(key, target);
target.ready = (async () => {
await inspector.call('Profiler.enable', {}, sessionId);
await inspector.call('Profiler.setSamplingInterval', { interval: options.interval }, sessionId);
await inspector.call('Profiler.start', {}, sessionId);
target.started = true;
target.startedAt = new Date().toISOString();
console.log(`V8 recording: ${title}`);
})().catch(error => { warn(`Cannot profile ${title}: ${error.message}`); });
await target.ready;
}
try {
if (options.mode !== 'art') {
port = adb('forward', 'tcp:0', `localabstract:${options.package}-inspectorServer`).trim();
if (!/^\d+$/.test(port)) throw new Error('ADB did not allocate an inspector port.');
inspector = await Inspector.connect(port);
inspector.onEvent = message => {
if (message.method === 'Target.attachedToTarget') {
const { sessionId, targetInfo } = message.params;
if (targetInfo.type === 'worker') void startTarget(sessionId, targetInfo.url || targetInfo.title);
} else if (message.method === 'Target.detachedFromTarget') {
const target = targets.get(message.params.sessionId);
if (target) { target.detached = true; warn(`Worker exited before its profile could be saved: ${target.title}`); }
}
};
await startTarget(undefined, 'main');
if (!targets.get('main').started) throw new Error('Main V8 profiler failed to start.');
try {
await inspector.call('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: false, flatten: true });
await Promise.all([...targets.values()].map(target => target.ready));
} catch (error) { warn(`Worker discovery unavailable; main V8 profile still active: ${error.message}`); }
}
if (options.mode !== 'js') {
const result = adb('shell', 'am', 'profile', 'start', '--sampling', String(options.interval), pid, remoteTrace);
if (/error|exception|failed/i.test(result)) throw new Error(result.trim());
artStarted = true;
console.log('ART recording: Java/Kotlin across the app process');
}
console.log(`Reproduce the workload now (${options.seconds}s; Ctrl-C saves early).`);
if (!interrupted) await new Promise(resolve => {
const timer = setTimeout(resolve, options.seconds * 1000);
wake = () => { clearTimeout(timer); resolve(); };
});
} catch (error) { failure = error; }
finally {
stopping = true;
// Stop every profiler before pulling maps/files. Failures in one profiler
// must not prevent the others from stopping or their data from being saved.
if (artStarted) {
try { adb('shell', 'am', 'profile', 'stop', pid); }
catch (error) { warn(`Could not stop ART: ${error.message}. Run adb -s ${options.device} shell am profile stop ${pid}`); }
}
await Promise.all([...targets.values()].map(async target => {
await target.ready;
if (!target.started || target.detached) return;
try {
const { profile } = await inspector.call('Profiler.stop', {}, target.sessionId);
if (!Array.isArray(profile?.nodes)) throw new Error('Inspector returned no CPU profile.');
const name = `js-${target.key.replace(/[^A-Za-z0-9_-]/g, '_')}`;
fs.writeFileSync(path.join(output, `${name}.raw.cpuprofile`), JSON.stringify(profile));
target.profile = profile;
summary.profiles.push({ name, title: target.title, startedAt: target.startedAt,
samples: profile.samples?.length || 0, nodes: profile.nodes.length });
} catch (error) { warn(`Could not save ${target.title}: ${error.message}`); }
}));
inspector?.close();
if (port) {
try { adb('forward', '--remove', `tcp:${port}`); }
catch (error) { warn(`Could not remove ADB forward tcp:${port}: ${error.message}`); }
}
process.removeListener('SIGINT', stopEarly);
process.removeListener('SIGTERM', stopEarly);
}
summary.stoppedAt = new Date().toISOString();
summary.interrupted = interrupted;
if (artStarted) {
try {
const file = path.join(output, 'java-kotlin.trace');
adb('pull', remoteTrace, file);
summary.art = traceSummary(fs.readFileSync(file));
if (summary.art.overflow) warn('ART trace buffer overflowed. Use a shorter capture or a larger --interval.');
adb('shell', 'rm', remoteTrace);
} catch (error) { warn(`Could not retrieve ART trace (left at ${remoteTrace}): ${error.message}`); }
}
if (options.sourceMaps && summary.profiles.length) {
// Use maps from the installed app, never a potentially mismatched local build.
const maps = new Map();
const urls = new Set([...targets.values()].flatMap(target => target.profile?.nodes.map(node => node.callFrame.url) || []));
for (const url of urls) {
const prefix = `file:///data/data/${options.package}/files/app/`;
const alternate = `file:///data/user/0/${options.package}/files/app/`;
const relative = url.startsWith(prefix) ? url.slice(prefix.length) : url.startsWith(alternate) ? url.slice(alternate.length) : '';
if (!/^[A-Za-z0-9_.-]+\.(?:m?js)$/.test(relative)) continue;
try {
let payload;
try { payload = adb('exec-out', 'run-as', options.package, 'cat', `files/app/${relative}.map`); }
catch {
const source = adb('exec-out', 'run-as', options.package, 'cat', `files/app/${relative}`);
const inline = source.match(/sourceMappingURL=data:application\/json[^,\n]*;base64,([A-Za-z0-9+/=]+)/);
if (!inline) throw new Error('no external or inline map');
payload = Buffer.from(inline[1], 'base64').toString('utf8');
}
maps.set(url, new SourceMap(JSON.parse(payload)));
fs.mkdirSync(path.join(output, 'source-maps'), { recursive: true });
fs.writeFileSync(path.join(output, 'source-maps', `${relative}.map`), payload);
} catch (error) { warn(`Source map unavailable for ${relative}: ${error.message}. Generated locations remain usable.`); }
}
for (const target of targets.values()) {
if (!target.profile) continue;
const name = `js-${target.key.replace(/[^A-Za-z0-9_-]/g, '_')}`;
const mapped = remapProfile(target.profile, maps);
fs.writeFileSync(path.join(output, `${name}.cpuprofile`), JSON.stringify(mapped.profile));
summary.profiles.find(item => item.name === name).mappedNodes = mapped.mappedNodes;
}
}
if (failure) summary.error = failure.message;
fs.writeFileSync(path.join(output, 'capture.json'), JSON.stringify(summary, null, 2) + '\n');
console.log(`Saved ${output}`);
for (const profile of summary.profiles) console.log(` ${profile.name}: ${profile.samples} samples, ${profile.mappedNodes || 0} source-mapped nodes`);
if (summary.art) console.log(` ART: ${summary.art.methods} methods (${summary.art.faceclawMethods} Faceclaw, ${summary.art.kotlinMethods} with Kotlin source)`);
if (failure) throw failure;
if ((options.mode !== 'js' && !summary.art) || (options.mode !== 'art' && !summary.profiles.length)) throw new Error('Capture incomplete; see capture.json.');
return summary;
}
if (require.main === module) {
Promise.resolve().then(() => {
const options = parseArgs(process.argv.slice(2));
if (options.help) console.log(HELP);
else return record(options);
}).catch(error => { console.error(`Profiling failed: ${error.message}`); process.exitCode = 1; });
}
module.exports = { parseArgs, Inspector, remapProfile, traceSummary, record };