Compare commits
4 Commits
main
...
worktree-s
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
6fcf0206ea | ||
|
|
bab0f93610 | ||
|
|
95a305f4b2 | ||
|
|
3b42a71a99 |
@ -11,6 +11,11 @@ import { initStartupProfiler } from './src/utils/startupProfiler.js';
|
||||
// Must run before any other imports to capture the earliest possible T0.
|
||||
initStartupProfiler();
|
||||
|
||||
import { initCpuProfiler } from './src/utils/cpuProfiler.js';
|
||||
// Initialize early to register SIGUSR1 handler and start recording when
|
||||
// QWEN_CODE_CPU_PROFILE=1, capturing as much of the startup as possible.
|
||||
initCpuProfiler();
|
||||
|
||||
import './src/gemini.js';
|
||||
import { main } from './src/gemini.js';
|
||||
import { FatalError } from '@qwen-code/qwen-code-core';
|
||||
|
||||
@ -1898,6 +1898,8 @@ export default {
|
||||
'Open the memory manager.': 'Open the memory manager.',
|
||||
'Show current process memory diagnostics':
|
||||
'Show current process memory diagnostics',
|
||||
'Record a CPU profile for Chrome DevTools analysis':
|
||||
'Record a CPU profile for Chrome DevTools analysis',
|
||||
'Save a durable memory to the memory system.':
|
||||
'Save a durable memory to the memory system.',
|
||||
'Ask a quick side question without affecting the main conversation':
|
||||
|
||||
@ -1485,6 +1485,8 @@ export default {
|
||||
// === Core: added from PR #3328 ===
|
||||
'Open the memory manager.': '打開記憶管理器。',
|
||||
'Show current process memory diagnostics': '顯示目前程序的內存診斷。',
|
||||
'Record a CPU profile for Chrome DevTools analysis':
|
||||
'錄製 CPU 效能分析檔案,用於 Chrome DevTools 分析',
|
||||
'Save a durable memory to the memory system.': '將持久記憶保存到記憶系統。',
|
||||
'Ask a quick side question without affecting the main conversation':
|
||||
'在不影響主對話的情況下快速提問旁支問題',
|
||||
|
||||
@ -1720,6 +1720,8 @@ export default {
|
||||
'Loading suggestions...': '正在加载建议...',
|
||||
'Open the memory manager.': '打开记忆管理器。',
|
||||
'Show current process memory diagnostics': '显示当前进程的内存诊断。',
|
||||
'Record a CPU profile for Chrome DevTools analysis':
|
||||
'录制 CPU 性能分析文件,用于 Chrome DevTools 分析',
|
||||
'Save a durable memory to the memory system.':
|
||||
'将一条持久记忆保存到记忆系统。',
|
||||
'Show per-item context usage breakdown.': '显示按项目划分的上下文使用详情。',
|
||||
|
||||
@ -177,10 +177,14 @@ describe('doctorCommand', () => {
|
||||
it('should complete memory subcommand names', async () => {
|
||||
await expect(doctorCommand.completion!(mockContext, '')).resolves.toEqual([
|
||||
'memory',
|
||||
'cpu-profile',
|
||||
]);
|
||||
await expect(
|
||||
doctorCommand.completion!(mockContext, 'mem'),
|
||||
).resolves.toEqual(['memory']);
|
||||
await expect(
|
||||
doctorCommand.completion!(mockContext, 'cpu'),
|
||||
).resolves.toEqual(['cpu-profile']);
|
||||
await expect(doctorCommand.completion!(mockContext, 'x')).resolves.toEqual(
|
||||
[],
|
||||
);
|
||||
@ -1049,6 +1053,8 @@ describe('doctorCommand', () => {
|
||||
});
|
||||
|
||||
it('should advertise the memory subcommand on the parent doctor argumentHint', () => {
|
||||
expect(doctorCommand.argumentHint).toBe('[memory] [--sample] [--snapshot]');
|
||||
expect(doctorCommand.argumentHint).toBe(
|
||||
'[memory|cpu-profile] [--sample] [--snapshot] [--duration]',
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
@ -16,6 +16,11 @@ import {
|
||||
isHighHeapPressure,
|
||||
writeMemoryHeapSnapshot,
|
||||
} from '../../utils/memoryDiagnostics.js';
|
||||
import {
|
||||
isCpuProfileRecording,
|
||||
startCpuProfile,
|
||||
stopCpuProfile,
|
||||
} from '../../utils/cpuProfiler.js';
|
||||
import { t } from '../../i18n/index.js';
|
||||
import {
|
||||
collectMemoryDiagnostics,
|
||||
@ -24,7 +29,8 @@ import {
|
||||
import { formatMemoryUsage } from '../utils/formatters.js';
|
||||
|
||||
const MEMORY_SUBCOMMAND = 'memory';
|
||||
const DOCTOR_SUBCOMMANDS = [MEMORY_SUBCOMMAND] as const;
|
||||
const CPU_PROFILE_SUBCOMMAND = 'cpu-profile';
|
||||
const DOCTOR_SUBCOMMANDS = [MEMORY_SUBCOMMAND, CPU_PROFILE_SUBCOMMAND] as const;
|
||||
function getHeapSnapshotSensitiveDataWarning(): string {
|
||||
return t(
|
||||
'Heap snapshot may contain prompts, file contents, tool results, and other sensitive data. Do not share it publicly without reviewing it first.',
|
||||
@ -49,12 +55,14 @@ export const doctorCommand: SlashCommand = {
|
||||
},
|
||||
kind: CommandKind.BUILT_IN,
|
||||
supportedModes: ['interactive', 'non_interactive', 'acp'] as const,
|
||||
argumentHint: '[memory] [--sample] [--snapshot]',
|
||||
argumentHint: '[memory|cpu-profile] [--sample] [--snapshot] [--duration]',
|
||||
examples: [
|
||||
'/doctor',
|
||||
'/doctor memory',
|
||||
'/doctor memory --sample',
|
||||
'/doctor memory --snapshot',
|
||||
'/doctor cpu-profile',
|
||||
'/doctor cpu-profile --duration 10',
|
||||
],
|
||||
completion: async (_context, partialArg) => {
|
||||
const trimmed = partialArg.trimStart();
|
||||
@ -181,6 +189,10 @@ export const doctorCommand: SlashCommand = {
|
||||
};
|
||||
}
|
||||
|
||||
if (subCommand === CPU_PROFILE_SUBCOMMAND) {
|
||||
return cpuProfileDoctorAction(context, subCommandArgs.slice(1).join(' '));
|
||||
}
|
||||
|
||||
if (executionMode === 'interactive') {
|
||||
context.ui.setPendingItem({
|
||||
type: 'info',
|
||||
@ -233,6 +245,16 @@ export const doctorCommand: SlashCommand = {
|
||||
argumentHint: '[--json] [--sample] [--snapshot]',
|
||||
action: memoryDoctorAction,
|
||||
},
|
||||
{
|
||||
name: 'cpu-profile',
|
||||
get description() {
|
||||
return t('Record a CPU profile for Chrome DevTools analysis');
|
||||
},
|
||||
kind: CommandKind.BUILT_IN,
|
||||
supportedModes: ['interactive', 'non_interactive', 'acp'] as const,
|
||||
argumentHint: '[--duration <seconds>]',
|
||||
action: cpuProfileDoctorAction,
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
@ -382,3 +404,179 @@ function formatCoreDiagnostics(diagnostics: MemoryDiagnostics): string {
|
||||
);
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// /doctor cpu-profile
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const CPU_PROFILE_USAGE_HINT = '/doctor cpu-profile [--duration <seconds>]';
|
||||
const DEFAULT_CPU_PROFILE_DURATION_SEC = 30;
|
||||
const MAX_CPU_PROFILE_DURATION_SEC = 300;
|
||||
|
||||
async function cpuProfileDoctorAction(
|
||||
context: CommandContext,
|
||||
args = '',
|
||||
): Promise<void | {
|
||||
type: 'message';
|
||||
messageType: 'info' | 'error';
|
||||
content: string;
|
||||
}> {
|
||||
const executionMode = context.executionMode ?? 'interactive';
|
||||
const abortSignal = context.abortSignal;
|
||||
|
||||
if (abortSignal?.aborted) return;
|
||||
|
||||
const tokens = args.trim().split(/\s+/).filter(Boolean);
|
||||
|
||||
// Parse --duration flag
|
||||
let durationSec = DEFAULT_CPU_PROFILE_DURATION_SEC;
|
||||
const durationIdx = tokens.indexOf('--duration');
|
||||
if (durationIdx !== -1) {
|
||||
const rawVal = tokens[durationIdx + 1];
|
||||
const val = rawVal ? parseInt(rawVal, 10) : NaN;
|
||||
if (
|
||||
!Number.isFinite(val) ||
|
||||
val < 1 ||
|
||||
val > MAX_CPU_PROFILE_DURATION_SEC
|
||||
) {
|
||||
const errorMsg = `${t('Duration must be between 1 and {max} seconds', { max: String(MAX_CPU_PROFILE_DURATION_SEC) })}. ${t('Usage')}: ${CPU_PROFILE_USAGE_HINT}`;
|
||||
if (executionMode === 'interactive') {
|
||||
context.ui.addItem({ type: 'error', text: errorMsg }, Date.now());
|
||||
return;
|
||||
}
|
||||
return { type: 'message', messageType: 'error', content: errorMsg };
|
||||
}
|
||||
durationSec = val;
|
||||
}
|
||||
|
||||
// Validate unknown arguments
|
||||
const knownTokens = new Set(['--duration']);
|
||||
const unknown = tokens.filter((token, idx) => {
|
||||
if (knownTokens.has(token)) return false;
|
||||
// Skip the value after --duration
|
||||
if (idx > 0 && tokens[idx - 1] === '--duration') return false;
|
||||
return true;
|
||||
});
|
||||
if (unknown.length > 0) {
|
||||
const errorMsg = `${t('Unknown argument(s)')}: ${unknown.join(', ')}. ${t('Usage')}: ${CPU_PROFILE_USAGE_HINT}`;
|
||||
if (executionMode === 'interactive') {
|
||||
context.ui.addItem({ type: 'error', text: errorMsg }, Date.now());
|
||||
return;
|
||||
}
|
||||
return { type: 'message', messageType: 'error', content: errorMsg };
|
||||
}
|
||||
|
||||
// Check if already recording
|
||||
if (isCpuProfileRecording()) {
|
||||
const errorMsg =
|
||||
process.platform === 'win32'
|
||||
? t('CPU profiling is already in progress. Wait for it to complete.')
|
||||
: t(
|
||||
'CPU profiling is already in progress. Send SIGUSR1 or wait for it to complete.',
|
||||
);
|
||||
if (executionMode === 'interactive') {
|
||||
context.ui.addItem({ type: 'error', text: errorMsg }, Date.now());
|
||||
return;
|
||||
}
|
||||
return { type: 'message', messageType: 'error', content: errorMsg };
|
||||
}
|
||||
|
||||
// Start recording
|
||||
const startResult = await startCpuProfile();
|
||||
if (!startResult.ok) {
|
||||
if (executionMode === 'interactive') {
|
||||
context.ui.addItem(
|
||||
{ type: 'error', text: startResult.error },
|
||||
Date.now(),
|
||||
);
|
||||
return;
|
||||
}
|
||||
return {
|
||||
type: 'message',
|
||||
messageType: 'error',
|
||||
content: startResult.error,
|
||||
};
|
||||
}
|
||||
|
||||
if (abortSignal?.aborted) {
|
||||
const abortResult = await stopCpuProfile();
|
||||
if (abortResult.ok) {
|
||||
const msg = t('CPU profile aborted early. Profile saved: {path}', {
|
||||
path: abortResult.filePath,
|
||||
});
|
||||
if (executionMode === 'interactive') {
|
||||
context.ui.addItem({ type: 'info', text: msg }, Date.now());
|
||||
}
|
||||
} else {
|
||||
const msg = `${t('CPU profile aborted but failed to stop cleanly')}: ${abortResult.error}`;
|
||||
if (executionMode === 'interactive') {
|
||||
context.ui.addItem({ type: 'error', text: msg }, Date.now());
|
||||
}
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
// Show progress in interactive mode
|
||||
if (executionMode === 'interactive') {
|
||||
context.ui.setPendingItem({
|
||||
type: 'info',
|
||||
text: t('Recording CPU profile for {duration}s...', {
|
||||
duration: String(durationSec),
|
||||
}),
|
||||
});
|
||||
}
|
||||
|
||||
// Wait for duration or abort. Timer is NOT unref'd so non-interactive
|
||||
// mode keeps the process alive for the full recording window.
|
||||
await new Promise<void>((resolve) => {
|
||||
const timer = setTimeout(resolve, durationSec * 1000);
|
||||
if (abortSignal) {
|
||||
abortSignal.addEventListener(
|
||||
'abort',
|
||||
() => {
|
||||
clearTimeout(timer);
|
||||
resolve();
|
||||
},
|
||||
{ once: true },
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
if (executionMode === 'interactive') {
|
||||
context.ui.setPendingItem(null);
|
||||
}
|
||||
|
||||
// Stop and write profile. If profiler is no longer recording (e.g., SIGUSR1
|
||||
// stopped it during the wait), treat as success — the profile was already written.
|
||||
const stopResult = await stopCpuProfile();
|
||||
if (!stopResult.ok) {
|
||||
const alreadyStopped = stopResult.error.includes('not recording');
|
||||
if (alreadyStopped) {
|
||||
const infoMsg =
|
||||
process.platform === 'win32'
|
||||
? t(
|
||||
'CPU profile was stopped externally. Check ~/.qwen/cpu-profiles/ for the output.',
|
||||
)
|
||||
: t(
|
||||
'CPU profile was stopped externally (e.g., via SIGUSR1). Check ~/.qwen/cpu-profiles/ for the output.',
|
||||
);
|
||||
if (executionMode === 'interactive') {
|
||||
context.ui.addItem({ type: 'info', text: infoMsg }, Date.now());
|
||||
return;
|
||||
}
|
||||
return { type: 'message', messageType: 'info', content: infoMsg };
|
||||
}
|
||||
if (executionMode === 'interactive') {
|
||||
context.ui.addItem({ type: 'error', text: stopResult.error }, Date.now());
|
||||
return;
|
||||
}
|
||||
return { type: 'message', messageType: 'error', content: stopResult.error };
|
||||
}
|
||||
|
||||
const successMsg = `${t('CPU profile written:')} ${stopResult.filePath}\n${t('Open in Chrome DevTools → Performance tab → Load profile')}`;
|
||||
if (executionMode === 'interactive') {
|
||||
context.ui.addItem({ type: 'info', text: successMsg }, Date.now());
|
||||
return;
|
||||
}
|
||||
return { type: 'message', messageType: 'info', content: successMsg };
|
||||
}
|
||||
|
||||
357
packages/cli/src/utils/cpuProfiler.test.ts
Normal file
357
packages/cli/src/utils/cpuProfiler.test.ts
Normal file
@ -0,0 +1,357 @@
|
||||
/**
|
||||
* @license
|
||||
* Copyright 2025 Qwen
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
import * as fs from 'node:fs';
|
||||
import * as os from 'node:os';
|
||||
import * as path from 'node:path';
|
||||
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
|
||||
|
||||
// Mock cleanup.ts to avoid pulling in @qwen-code/qwen-code-core dependency chain
|
||||
vi.mock('./cleanup.js', () => ({
|
||||
registerCleanup: vi.fn(),
|
||||
}));
|
||||
|
||||
import {
|
||||
_resetCpuProfilerForTest,
|
||||
_setSessionFactoryForTest,
|
||||
clearCpuProfileRateLimit,
|
||||
isCpuProfileRecording,
|
||||
startCpuProfile,
|
||||
stopCpuProfile,
|
||||
} from './cpuProfiler.js';
|
||||
|
||||
function createMockSession() {
|
||||
const mockProfile = {
|
||||
nodes: [
|
||||
{
|
||||
id: 1,
|
||||
callFrame: {
|
||||
functionName: 'test',
|
||||
scriptId: '1',
|
||||
url: '',
|
||||
lineNumber: 0,
|
||||
columnNumber: 0,
|
||||
},
|
||||
hitCount: 10,
|
||||
children: [],
|
||||
},
|
||||
],
|
||||
startTime: 0,
|
||||
endTime: 1000000,
|
||||
samples: [1],
|
||||
timeDeltas: [100],
|
||||
};
|
||||
|
||||
const post = vi.fn().mockImplementation((method: string) => {
|
||||
if (method === 'Profiler.stop') {
|
||||
return Promise.resolve({ profile: mockProfile });
|
||||
}
|
||||
return Promise.resolve(undefined);
|
||||
});
|
||||
const connect = vi.fn();
|
||||
const disconnect = vi.fn();
|
||||
|
||||
return { post, connect, disconnect };
|
||||
}
|
||||
|
||||
describe('cpuProfiler', () => {
|
||||
let tmpDir: string;
|
||||
let mockSession: ReturnType<typeof createMockSession>;
|
||||
|
||||
beforeEach(() => {
|
||||
_resetCpuProfilerForTest();
|
||||
clearCpuProfileRateLimit();
|
||||
|
||||
mockSession = createMockSession();
|
||||
_setSessionFactoryForTest(async () => mockSession);
|
||||
|
||||
tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cpu-profiler-test-'));
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
_resetCpuProfilerForTest();
|
||||
_setSessionFactoryForTest(null);
|
||||
vi.restoreAllMocks();
|
||||
try {
|
||||
fs.rmSync(tmpDir, { recursive: true, force: true });
|
||||
} catch {
|
||||
// ignore
|
||||
}
|
||||
});
|
||||
|
||||
describe('isCpuProfileRecording', () => {
|
||||
it('returns false when not recording', () => {
|
||||
expect(isCpuProfileRecording()).toBe(false);
|
||||
});
|
||||
|
||||
it('returns true when recording', async () => {
|
||||
await startCpuProfile();
|
||||
expect(isCpuProfileRecording()).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('startCpuProfile', () => {
|
||||
it('starts profiling successfully', async () => {
|
||||
const result = await startCpuProfile();
|
||||
expect(result).toEqual({ ok: true });
|
||||
expect(mockSession.post).toHaveBeenCalledWith('Profiler.enable');
|
||||
expect(mockSession.post).toHaveBeenCalledWith(
|
||||
'Profiler.setSamplingInterval',
|
||||
{ interval: 1000 },
|
||||
);
|
||||
expect(mockSession.post).toHaveBeenCalledWith('Profiler.start');
|
||||
});
|
||||
|
||||
it('accepts custom sampling interval', async () => {
|
||||
await startCpuProfile({ samplingInterval: 500 });
|
||||
expect(mockSession.post).toHaveBeenCalledWith(
|
||||
'Profiler.setSamplingInterval',
|
||||
{ interval: 500 },
|
||||
);
|
||||
});
|
||||
|
||||
it('returns error when already recording', async () => {
|
||||
await startCpuProfile();
|
||||
const result = await startCpuProfile();
|
||||
expect(result).toEqual({
|
||||
ok: false,
|
||||
error: 'CPU profiling is already in progress.',
|
||||
});
|
||||
});
|
||||
|
||||
it('returns error and resets state on session failure', async () => {
|
||||
_setSessionFactoryForTest(async () => {
|
||||
throw new Error('Connection refused');
|
||||
});
|
||||
|
||||
const result = await startCpuProfile();
|
||||
expect(result.ok).toBe(false);
|
||||
if (!result.ok) {
|
||||
expect(result.error).toContain('Connection refused');
|
||||
}
|
||||
expect(isCpuProfileRecording()).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('stopCpuProfile', () => {
|
||||
it('stops and writes profile file', async () => {
|
||||
await startCpuProfile();
|
||||
const result = await stopCpuProfile({ outputDir: tmpDir });
|
||||
|
||||
expect(result.ok).toBe(true);
|
||||
if (result.ok) {
|
||||
expect(result.filePath).toMatch(/qwen-code-cpu-\d+-.*\.cpuprofile$/);
|
||||
expect(fs.existsSync(result.filePath)).toBe(true);
|
||||
|
||||
const content = JSON.parse(fs.readFileSync(result.filePath, 'utf8'));
|
||||
expect(content.nodes).toBeDefined();
|
||||
expect(content.startTime).toBeDefined();
|
||||
}
|
||||
});
|
||||
|
||||
it('returns error when not recording', async () => {
|
||||
const result = await stopCpuProfile({ outputDir: tmpDir });
|
||||
expect(result).toEqual({
|
||||
ok: false,
|
||||
error: 'CPU profiler is not recording.',
|
||||
});
|
||||
});
|
||||
|
||||
it('calls Profiler.stop and Profiler.disable', async () => {
|
||||
await startCpuProfile();
|
||||
mockSession.post.mockClear();
|
||||
await stopCpuProfile({ outputDir: tmpDir });
|
||||
|
||||
expect(mockSession.post).toHaveBeenCalledWith('Profiler.stop');
|
||||
expect(mockSession.post).toHaveBeenCalledWith('Profiler.disable');
|
||||
});
|
||||
|
||||
it('sets file permissions to 0o600', async () => {
|
||||
await startCpuProfile();
|
||||
const result = await stopCpuProfile({ outputDir: tmpDir });
|
||||
|
||||
if (result.ok && process.platform !== 'win32') {
|
||||
const stats = fs.statSync(result.filePath);
|
||||
expect(stats.mode & 0o777).toBe(0o600);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('rate limiting', () => {
|
||||
it('enforces rate limit between writes', async () => {
|
||||
const now = new Date('2026-05-29T10:00:00.000Z');
|
||||
|
||||
await startCpuProfile();
|
||||
const first = await stopCpuProfile({ outputDir: tmpDir, now });
|
||||
expect(first.ok).toBe(true);
|
||||
|
||||
// Second write within rate limit window
|
||||
await startCpuProfile();
|
||||
const second = await stopCpuProfile({
|
||||
outputDir: tmpDir,
|
||||
now: new Date(now.getTime() + 5000), // 5s later, within 30s limit
|
||||
});
|
||||
expect(second.ok).toBe(false);
|
||||
if (!second.ok) {
|
||||
expect(second.error).toContain('rate limit');
|
||||
}
|
||||
});
|
||||
|
||||
it('allows write after rate limit expires', async () => {
|
||||
const now = new Date('2026-05-29T10:00:00.000Z');
|
||||
|
||||
await startCpuProfile();
|
||||
await stopCpuProfile({ outputDir: tmpDir, now });
|
||||
|
||||
// After rate limit window
|
||||
await startCpuProfile();
|
||||
const result = await stopCpuProfile({
|
||||
outputDir: tmpDir,
|
||||
now: new Date(now.getTime() + 31000), // 31s later
|
||||
});
|
||||
expect(result.ok).toBe(true);
|
||||
});
|
||||
|
||||
it('resets state to idle when rate-limited so user can retry', async () => {
|
||||
const now = new Date('2026-05-29T10:00:00.000Z');
|
||||
|
||||
await startCpuProfile();
|
||||
await stopCpuProfile({ outputDir: tmpDir, now });
|
||||
|
||||
// Start a new recording, then try to stop within rate limit window
|
||||
await startCpuProfile();
|
||||
const rateLimited = await stopCpuProfile({
|
||||
outputDir: tmpDir,
|
||||
now: new Date(now.getTime() + 5000),
|
||||
});
|
||||
expect(rateLimited.ok).toBe(false);
|
||||
|
||||
// State should be reset — a new startCpuProfile() must succeed
|
||||
const restart = await startCpuProfile();
|
||||
expect(restart.ok).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('old profile cleanup', () => {
|
||||
it('removes old profiles beyond max count', async () => {
|
||||
// Create 5 existing profiles
|
||||
for (let i = 0; i < 5; i++) {
|
||||
const name = `qwen-code-cpu-99999-2026-05-29T0${i}-00-00-000Z.cpuprofile`;
|
||||
fs.writeFileSync(path.join(tmpDir, name), '{}');
|
||||
// Stagger mtime so sort is deterministic
|
||||
const mtime = new Date(Date.now() - (5 - i) * 1000);
|
||||
fs.utimesSync(path.join(tmpDir, name), mtime, mtime);
|
||||
}
|
||||
|
||||
clearCpuProfileRateLimit();
|
||||
await startCpuProfile();
|
||||
const result = await stopCpuProfile({
|
||||
outputDir: tmpDir,
|
||||
maxProfiles: 5,
|
||||
});
|
||||
expect(result.ok).toBe(true);
|
||||
|
||||
const files = fs
|
||||
.readdirSync(tmpDir)
|
||||
.filter((f) => f.endsWith('.cpuprofile'));
|
||||
// Should have at most 5 files (new one replaces oldest)
|
||||
expect(files.length).toBeLessThanOrEqual(5);
|
||||
});
|
||||
});
|
||||
|
||||
describe('conflict handling', () => {
|
||||
it('rejects second start while recording', async () => {
|
||||
const first = await startCpuProfile();
|
||||
expect(first.ok).toBe(true);
|
||||
|
||||
const second = await startCpuProfile();
|
||||
expect(second.ok).toBe(false);
|
||||
if (!second.ok) {
|
||||
expect(second.error).toContain('already in progress');
|
||||
}
|
||||
});
|
||||
|
||||
it('resets state after stop so new recording can start', async () => {
|
||||
await startCpuProfile();
|
||||
await stopCpuProfile({ outputDir: tmpDir });
|
||||
|
||||
clearCpuProfileRateLimit();
|
||||
const result = await startCpuProfile();
|
||||
expect(result.ok).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('initCpuProfiler', () => {
|
||||
it('is idempotent — calling twice does not error', async () => {
|
||||
const { initCpuProfiler } = await import('./cpuProfiler.js');
|
||||
// First call
|
||||
initCpuProfiler();
|
||||
// Second call should be a no-op
|
||||
initCpuProfiler();
|
||||
// No error thrown means success
|
||||
});
|
||||
|
||||
it('does not start recording when env var is unset', async () => {
|
||||
_resetCpuProfilerForTest();
|
||||
delete process.env['QWEN_CODE_CPU_PROFILE'];
|
||||
const { initCpuProfiler } = await import('./cpuProfiler.js');
|
||||
_resetCpuProfilerForTest();
|
||||
initCpuProfiler();
|
||||
expect(isCpuProfileRecording()).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('SIGUSR1 toggle (via start/stop cycle)', () => {
|
||||
it('simulates signal toggle: start then stop', async () => {
|
||||
// Simulate what handleSigusr1 does internally
|
||||
expect(isCpuProfileRecording()).toBe(false);
|
||||
|
||||
// First signal: start
|
||||
const startResult = await startCpuProfile();
|
||||
expect(startResult.ok).toBe(true);
|
||||
expect(isCpuProfileRecording()).toBe(true);
|
||||
|
||||
// Second signal: stop
|
||||
const stopResult = await stopCpuProfile({ outputDir: tmpDir });
|
||||
expect(stopResult.ok).toBe(true);
|
||||
expect(isCpuProfileRecording()).toBe(false);
|
||||
});
|
||||
|
||||
it('ignores stop when in idle state', async () => {
|
||||
const result = await stopCpuProfile({ outputDir: tmpDir });
|
||||
expect(result.ok).toBe(false);
|
||||
if (!result.ok) {
|
||||
expect(result.error).toContain('not recording');
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('empty profile guard', () => {
|
||||
it('returns error when V8 returns empty profile', async () => {
|
||||
_resetCpuProfilerForTest();
|
||||
const emptyMock = {
|
||||
post: vi.fn().mockImplementation((method: string) => {
|
||||
if (method === 'Profiler.stop') {
|
||||
return Promise.resolve({ profile: undefined });
|
||||
}
|
||||
return Promise.resolve(undefined);
|
||||
}),
|
||||
connect: vi.fn(),
|
||||
disconnect: vi.fn(),
|
||||
};
|
||||
_setSessionFactoryForTest(async () => emptyMock);
|
||||
|
||||
await startCpuProfile();
|
||||
const result = await stopCpuProfile({ outputDir: tmpDir });
|
||||
|
||||
expect(result.ok).toBe(false);
|
||||
if (!result.ok) {
|
||||
expect(result.error).toContain('empty profile');
|
||||
}
|
||||
});
|
||||
});
|
||||
});
|
||||
440
packages/cli/src/utils/cpuProfiler.ts
Normal file
440
packages/cli/src/utils/cpuProfiler.ts
Normal file
@ -0,0 +1,440 @@
|
||||
/**
|
||||
* @license
|
||||
* Copyright 2025 Qwen
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
/**
|
||||
* CPU profiling utility that generates .cpuprofile files for Chrome DevTools.
|
||||
*
|
||||
* Three trigger modes:
|
||||
* 1. Environment variable: QWEN_CODE_CPU_PROFILE=1 — records from process start to exit
|
||||
* 2. Signal toggle: SIGUSR1 — first signal starts, second stops and writes
|
||||
* 3. Command: /doctor cpu-profile [--duration N] — records for N seconds
|
||||
*
|
||||
* Output: ~/.qwen/cpu-profiles/qwen-code-cpu-<pid>-<timestamp>.cpuprofile
|
||||
* Zero overhead when disabled (single env var check at init).
|
||||
*/
|
||||
|
||||
import * as fs from 'node:fs';
|
||||
import * as os from 'node:os';
|
||||
import * as path from 'node:path';
|
||||
|
||||
import { registerCleanup } from './cleanup.js';
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Types
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
type ProfilerState = 'idle' | 'recording' | 'stopping';
|
||||
|
||||
export type CpuProfileStartResult = { ok: true } | { ok: false; error: string };
|
||||
|
||||
export type CpuProfileStopResult =
|
||||
| { ok: true; filePath: string }
|
||||
| { ok: false; error: string };
|
||||
|
||||
// Custom interface rather than importing from node:inspector/promises because
|
||||
// the official Session.post() generic overload returns Promise<void>, making
|
||||
// dynamic method dispatch (Profiler.start/stop) cumbersome without per-call casts.
|
||||
interface InspectorSession {
|
||||
connect(): void;
|
||||
disconnect(): void;
|
||||
post(method: string, params?: Record<string, unknown>): Promise<unknown>;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Constants
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const MAX_PROFILES = 5;
|
||||
const RATE_LIMIT_MS = 30_000;
|
||||
const MIN_FREE_BYTES_AFTER_WRITE = 256 * 1024 * 1024;
|
||||
const DEFAULT_SAMPLING_INTERVAL_US = 1000; // 1ms
|
||||
const ESTIMATED_PROFILE_BYTES = 10 * 1024 * 1024; // 10 MiB conservative estimate
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Module state
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
let state: ProfilerState = 'idle';
|
||||
let session: InspectorSession | null = null;
|
||||
let initialized = false;
|
||||
let signalHandlerRegistered = false;
|
||||
const lastWriteByDir = new Map<string, number>();
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public API
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Initialize CPU profiler. Call once at process start.
|
||||
* Always registers SIGUSR1 handler (for ad-hoc profiling).
|
||||
* When QWEN_CODE_CPU_PROFILE=1, also starts recording immediately.
|
||||
*/
|
||||
export function initCpuProfiler(): void {
|
||||
if (initialized) return;
|
||||
initialized = true;
|
||||
|
||||
// Always register signal handler for ad-hoc profiling (non-Windows)
|
||||
registerSignalHandler();
|
||||
|
||||
// Always register cleanup to flush any in-progress profile on exit
|
||||
registerCleanup(async () => {
|
||||
if (state === 'recording') {
|
||||
const result = await stopCpuProfile();
|
||||
if (result.ok) {
|
||||
process.stderr.write(
|
||||
`[cpu-profiler] Profile written: ${result.filePath}\n`,
|
||||
);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
const enabled = process.env['QWEN_CODE_CPU_PROFILE'] === '1';
|
||||
if (!enabled) return;
|
||||
|
||||
// Start recording immediately in env-var mode
|
||||
void startCpuProfile().then((result) => {
|
||||
if (!result.ok) {
|
||||
process.stderr.write(`[cpu-profiler] Failed to start: ${result.error}\n`);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Start CPU profiling.
|
||||
* @param opts.samplingInterval - Sampling interval in microseconds (default 1000 = 1ms)
|
||||
*/
|
||||
export async function startCpuProfile(opts?: {
|
||||
samplingInterval?: number;
|
||||
}): Promise<CpuProfileStartResult> {
|
||||
if (state !== 'idle') {
|
||||
return {
|
||||
ok: false,
|
||||
error:
|
||||
state === 'recording'
|
||||
? 'CPU profiling is already in progress.'
|
||||
: 'CPU profiler is currently stopping. Please wait a moment and try again.',
|
||||
};
|
||||
}
|
||||
|
||||
// Set state eagerly before the first await to prevent concurrent callers
|
||||
// (e.g., rapid SIGUSR1 signals) from both passing the idle guard.
|
||||
state = 'recording';
|
||||
|
||||
try {
|
||||
const inspectorSession = await getOrCreateSession();
|
||||
await inspectorSession.post('Profiler.enable');
|
||||
await inspectorSession.post('Profiler.setSamplingInterval', {
|
||||
interval: opts?.samplingInterval ?? DEFAULT_SAMPLING_INTERVAL_US,
|
||||
});
|
||||
await inspectorSession.post('Profiler.start');
|
||||
return { ok: true };
|
||||
} catch (error) {
|
||||
state = 'idle';
|
||||
disconnectSession();
|
||||
return { ok: false, error: formatError(error) };
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Stop CPU profiling and write the .cpuprofile file.
|
||||
* @returns File path on success.
|
||||
*/
|
||||
export async function stopCpuProfile(options?: {
|
||||
outputDir?: string;
|
||||
now?: Date;
|
||||
rateLimitMs?: number;
|
||||
maxProfiles?: number;
|
||||
}): Promise<CpuProfileStopResult> {
|
||||
if (state !== 'recording') {
|
||||
return {
|
||||
ok: false,
|
||||
error:
|
||||
state === 'idle'
|
||||
? 'CPU profiler is not recording.'
|
||||
: 'CPU profiler is already stopping.',
|
||||
};
|
||||
}
|
||||
|
||||
const outputDir = options?.outputDir ?? defaultOutputDir();
|
||||
const now = options?.now ?? new Date();
|
||||
const rateLimitMs = options?.rateLimitMs ?? RATE_LIMIT_MS;
|
||||
const maxProfiles = options?.maxProfiles ?? MAX_PROFILES;
|
||||
|
||||
// Check rate limit BEFORE writing to avoid excessive output.
|
||||
// If rate-limited, tear down the V8 profiler (data is discarded) and reset
|
||||
// state to 'idle' so the user can start a fresh recording later.
|
||||
try {
|
||||
enforceRateLimit(outputDir, now, rateLimitMs);
|
||||
} catch (error) {
|
||||
state = 'idle';
|
||||
if (session) {
|
||||
session.post('Profiler.stop').catch(() => {});
|
||||
session.post('Profiler.disable').catch(() => {});
|
||||
}
|
||||
disconnectSession();
|
||||
return { ok: false, error: formatError(error) };
|
||||
}
|
||||
|
||||
state = 'stopping';
|
||||
|
||||
try {
|
||||
if (!session) {
|
||||
throw new Error(
|
||||
'Inspector session lost unexpectedly during Profiler.stop; the profile data could not be retrieved.',
|
||||
);
|
||||
}
|
||||
|
||||
const result = (await session.post('Profiler.stop')) as {
|
||||
profile: unknown;
|
||||
};
|
||||
if (!result.profile) {
|
||||
throw new Error(
|
||||
'V8 Profiler.stop returned an empty profile; recording may have been interrupted.',
|
||||
);
|
||||
}
|
||||
await session.post('Profiler.disable');
|
||||
|
||||
fs.mkdirSync(outputDir, { recursive: true, mode: 0o700 });
|
||||
try {
|
||||
fs.chmodSync(outputDir, 0o700);
|
||||
} catch {
|
||||
// Best-effort hardening on filesystems without POSIX chmod.
|
||||
}
|
||||
|
||||
checkDiskSpace(outputDir);
|
||||
|
||||
const filePath = path.join(
|
||||
outputDir,
|
||||
`qwen-code-cpu-${process.pid}-${formatTimestamp(now)}.cpuprofile`,
|
||||
);
|
||||
|
||||
try {
|
||||
fs.writeFileSync(filePath, JSON.stringify(result.profile), {
|
||||
mode: 0o600,
|
||||
});
|
||||
} catch (writeError) {
|
||||
try {
|
||||
fs.rmSync(filePath, { force: true });
|
||||
} catch {
|
||||
// Best-effort cleanup of partial file.
|
||||
}
|
||||
throw writeError;
|
||||
}
|
||||
|
||||
recordWrite(outputDir, now);
|
||||
cleanupOldProfiles(outputDir, maxProfiles);
|
||||
|
||||
state = 'idle';
|
||||
return { ok: true, filePath };
|
||||
} catch (error) {
|
||||
state = 'idle';
|
||||
disconnectSession();
|
||||
return { ok: false, error: formatError(error) };
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether the profiler is currently recording.
|
||||
*/
|
||||
export function isCpuProfileRecording(): boolean {
|
||||
return state === 'recording';
|
||||
}
|
||||
|
||||
/**
|
||||
* Register SIGUSR1 signal handler for toggle mode.
|
||||
* Safe to call multiple times; only registers once.
|
||||
* No-op on Windows (SIGUSR1 does not exist).
|
||||
*/
|
||||
export function registerSignalHandler(): void {
|
||||
if (signalHandlerRegistered) return;
|
||||
if (process.platform === 'win32') return;
|
||||
|
||||
signalHandlerRegistered = true;
|
||||
process.on('SIGUSR1', handleSigusr1);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Test helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/** Reset all module state. Test-only. */
|
||||
export function _resetCpuProfilerForTest(): void {
|
||||
state = 'idle';
|
||||
initialized = false;
|
||||
signalHandlerRegistered = false;
|
||||
disconnectSession();
|
||||
lastWriteByDir.clear();
|
||||
}
|
||||
|
||||
/** Clear rate limit state. Test-only. */
|
||||
export function clearCpuProfileRateLimit(): void {
|
||||
lastWriteByDir.clear();
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Internal helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
function defaultOutputDir(): string {
|
||||
return path.join(os.homedir(), '.qwen', 'cpu-profiles');
|
||||
}
|
||||
|
||||
function formatTimestamp(now: Date): string {
|
||||
return now.toISOString().replace(/[:.]/g, '-');
|
||||
}
|
||||
|
||||
function formatError(error: unknown): string {
|
||||
return error instanceof Error ? error.message : String(error);
|
||||
}
|
||||
|
||||
// Overridable factory for testing (avoids mocking ESM dynamic imports)
|
||||
let sessionFactory: (() => Promise<InspectorSession>) | null = null;
|
||||
|
||||
/** Override session creation for testing. */
|
||||
export function _setSessionFactoryForTest(
|
||||
factory: (() => Promise<InspectorSession>) | null,
|
||||
): void {
|
||||
sessionFactory = factory;
|
||||
}
|
||||
|
||||
async function getOrCreateSession(): Promise<InspectorSession> {
|
||||
if (session) return session;
|
||||
|
||||
if (sessionFactory) {
|
||||
session = await sessionFactory();
|
||||
return session;
|
||||
}
|
||||
|
||||
// Dynamic import to avoid any overhead when profiling is disabled
|
||||
const inspectorModule = await import('node:inspector/promises');
|
||||
const newSession =
|
||||
new inspectorModule.Session() as unknown as InspectorSession;
|
||||
newSession.connect();
|
||||
session = newSession;
|
||||
return session;
|
||||
}
|
||||
|
||||
function disconnectSession(): void {
|
||||
if (session) {
|
||||
try {
|
||||
session.disconnect();
|
||||
} catch {
|
||||
// Ignore disconnect errors during cleanup.
|
||||
}
|
||||
session = null;
|
||||
}
|
||||
}
|
||||
|
||||
function handleSigusr1(): void {
|
||||
if (state === 'idle') {
|
||||
void startCpuProfile().then((result) => {
|
||||
if (result.ok) {
|
||||
process.stderr.write(
|
||||
`[cpu-profiler] Recording started (PID ${process.pid}). Send SIGUSR1 again to stop.\n`,
|
||||
);
|
||||
} else {
|
||||
process.stderr.write(
|
||||
`[cpu-profiler] Failed to start: ${result.error}\n`,
|
||||
);
|
||||
}
|
||||
});
|
||||
} else if (state === 'recording') {
|
||||
void stopCpuProfile().then((result) => {
|
||||
if (result.ok) {
|
||||
process.stderr.write(
|
||||
`[cpu-profiler] Profile written: ${result.filePath}\n`,
|
||||
);
|
||||
} else {
|
||||
process.stderr.write(
|
||||
`[cpu-profiler] Failed to stop: ${result.error}\n`,
|
||||
);
|
||||
}
|
||||
});
|
||||
}
|
||||
// state === 'stopping': ignore, already in progress
|
||||
}
|
||||
|
||||
function enforceRateLimit(
|
||||
outputDir: string,
|
||||
now: Date,
|
||||
rateLimitMs: number,
|
||||
): void {
|
||||
if (rateLimitMs <= 0) return;
|
||||
|
||||
const key = path.resolve(outputDir);
|
||||
const nowMs = now.getTime();
|
||||
const lastWriteMs = lastWriteByDir.get(key);
|
||||
if (lastWriteMs !== undefined && nowMs - lastWriteMs < rateLimitMs) {
|
||||
const waitSeconds = Math.ceil((rateLimitMs - (nowMs - lastWriteMs)) / 1000);
|
||||
throw new Error(
|
||||
`CPU profile rate limit: wait ${waitSeconds}s before writing another profile.`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
function recordWrite(outputDir: string, now: Date): void {
|
||||
lastWriteByDir.set(path.resolve(outputDir), now.getTime());
|
||||
}
|
||||
|
||||
function checkDiskSpace(outputDir: string): void {
|
||||
try {
|
||||
const stats = fs.statfsSync(outputDir);
|
||||
const available = stats.bavail * stats.bsize;
|
||||
if (available - ESTIMATED_PROFILE_BYTES < MIN_FREE_BYTES_AFTER_WRITE) {
|
||||
throw new Error(
|
||||
'Insufficient free disk space for CPU profile; skipping to avoid filling the disk.',
|
||||
);
|
||||
}
|
||||
} catch (error) {
|
||||
if (
|
||||
error instanceof Error &&
|
||||
error.message.includes('Insufficient free disk')
|
||||
) {
|
||||
throw error;
|
||||
}
|
||||
// statfsSync is not available on all platforms (e.g. Windows).
|
||||
// Log a warning so it's not completely silent, but proceed anyway.
|
||||
process.stderr.write(
|
||||
'[cpu-profiler] Disk space check unavailable on this platform; skipping.\n',
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
function cleanupOldProfiles(outputDir: string, maxProfiles: number): void {
|
||||
if (maxProfiles < 1) return;
|
||||
|
||||
let profiles: string[];
|
||||
try {
|
||||
profiles = fs
|
||||
.readdirSync(outputDir)
|
||||
.filter(
|
||||
(name) =>
|
||||
name.startsWith('qwen-code-cpu-') && name.endsWith('.cpuprofile'),
|
||||
)
|
||||
.map((name) => path.join(outputDir, name))
|
||||
.sort((a, b) => {
|
||||
try {
|
||||
return (
|
||||
fs.lstatSync(b).mtimeMs - fs.lstatSync(a).mtimeMs ||
|
||||
path.basename(b).localeCompare(path.basename(a))
|
||||
);
|
||||
} catch {
|
||||
// Fall back to filename comparison if stat fails
|
||||
return path.basename(b).localeCompare(path.basename(a));
|
||||
}
|
||||
});
|
||||
} catch {
|
||||
return;
|
||||
}
|
||||
|
||||
for (const filePath of profiles.slice(maxProfiles)) {
|
||||
try {
|
||||
fs.rmSync(filePath, { force: true });
|
||||
} catch {
|
||||
// Cleanup is best effort.
|
||||
}
|
||||
}
|
||||
}
|
||||
Loading…
x
Reference in New Issue
Block a user