@devries-cameron20 / t3code Mirror · read-only / commits / 0bc95fcdea
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 22, 08:15 UTC

feat(dev): add startup profiling for cold-start diagnosis (#28566)

Yash Singh committed Nov 1, 2026 at 03:56 UTC 0bc95fcdea918e2d155c53ab21e5beefdaa59733
11 files changed +715 -19
apps/server/src/bin.ts
+4
@@ -40,7 +40,11 @@ if (
40 // Windows desktop launches without stdin; attach before reading, except on fast paths using pipes.
41 const { attachConsoleStdin } = await import("./cli/consoleStdin.ts");
42 attachConsoleStdin();
43 + const importStart = performance.now();
44 const { runCli } = await import("./binCli.ts");
45 + if (process.env.T3CODE_STARTUP_PROFILE_DIR) {
46 + performance.measure("server.import.binCli", { start: importStart });
47 + }
48 runCli();
49 }
50 }
apps/server/src/persistence/Sqlite.ts
+1 -1
@@ -41,7 +41,7 @@ const layerSetup = Layer.effectDiscard(
41 yield* sql`DELETE FROM sqlite_stat1;`;
42 yield* sql`ANALYZE sqlite_schema;`;
43 }
44 - }),
44 + }).pipe(Effect.withSpan("Sqlite.setup")),
45 );
46
47 export const layerFromPath = Effect.fn("makeSqlitePersistenceLive")(function* (dbPath: string) {
apps/server/src/ws.test.ts
+50 -12
@@ -21,6 +21,7 @@ import {
21 import * as Deferred from "effect/Deferred";
22 import * as DateTime from "effect/DateTime";
23 import * as Effect from "effect/Effect";
24 +import * as Fiber from "effect/Fiber";
25 import * as Layer from "effect/Layer";
26 import * as PubSub from "effect/PubSub";
27 import * as Queue from "effect/Queue";
@@ -127,7 +128,7 @@ import {
128 subscribeOrchestrationV2Shell,
129 subscribeOrchestrationV2Thread,
130 WS_RPC_SERVER_OPTIONS,
130 - withLateEditorConfig,
131 + withLateConfigDiscovery,
132 } from "./ws.ts";
133
134 const snapshotConfig = (fields: Partial<ServerConfig>) =>
@@ -142,7 +143,7 @@ const settingsUpdated = (settings: object): ServerConfigStreamEvent => ({
143 it.effect("resends late editors without rolling back updates already sent", () =>
144 Effect.gen(function* () {
145 const settingsSent = yield* Deferred.make<void>();
145 - const events = yield* withLateEditorConfig(
146 + const events = yield* withLateConfigDiscovery(
147 snapshotConfig({ settings: { enableProviderUpdateChecks: true } as never }),
148 Stream.make(settingsUpdated({ enableProviderUpdateChecks: false })),
149 {
@@ -150,6 +151,7 @@ it.effect("resends late editors without rolling back updates already sent", () =
151 resolveFileManagerRevealKind: () =>
152 Deferred.await(settingsSent).pipe(Effect.as("file-explorer" as const)),
153 },
154 + { resolveTargets: () => Effect.succeed([]) },
155 ).pipe(
156 Stream.tap((event) =>
157 event.type === "settingsUpdated" ? Deferred.succeed(settingsSent, undefined) : Effect.void,
@@ -169,24 +171,35 @@ it.effect("resends late editors without rolling back updates already sent", () =
171 }),
172 );
173
172 -it.effect("resends a file manager reveal kind that missed the snapshot", () =>
174 +it.effect("resends a reveal kind and remote targets that outlast the snapshot timeout", () =>
175 Effect.gen(function* () {
174 - const events = yield* withLateEditorConfig(
176 + const targets = [{ kind: "mdns" as const, host: "test.local" }];
177 + const finishDiscovery = yield* Deferred.make<typeof targets>();
178 + const collecting = yield* withLateConfigDiscovery(
179 snapshotConfig({ availableEditors: ["file-manager"] }),
180 Stream.empty,
181 {
182 resolveAvailableEditors: () => Effect.succeed(["file-manager"]),
183 resolveFileManagerRevealKind: () => Effect.succeed("file-explorer"),
184 },
181 - ).pipe(Stream.runCollect);
185 + { resolveTargets: () => Deferred.await(finishDiscovery) },
186 + ).pipe(Stream.runCollect, Effect.forkScoped({ startImmediately: true }));
187 + yield* TestClock.adjust("6 seconds");
188 + yield* Deferred.succeed(finishDiscovery, targets);
189 + const events = yield* Fiber.join(collecting);
190
183 - const [late] = Array.from(events);
184 - assert.equal(events.length, 1);
191 + const [late, remote] = Array.from(events);
192 + assert.equal(events.length, 2);
193 assert.equal(late?.type, "snapshot");
194 if (late?.type === "snapshot") {
195 assert.equal(late.config.shellRevealInFileManagerKind, "file-explorer");
196 }
189 - }),
197 + assert.equal(remote?.type, "snapshot");
198 + if (remote?.type === "snapshot") {
199 + assert.deepEqual(remote.config.remoteOpenTargets, targets);
200 + assert.equal(remote.config.shellRevealInFileManagerKind, "file-explorer");
201 + }
202 + }).pipe(Effect.scoped),
203 );
204
205 it.effect("runs editor, remote open target and direct endpoint discovery side by side", () =>
@@ -600,9 +613,9 @@ const layerConfigSources = Layer.mergeAll(
613 Layer.provideMerge(NodeServices.layer),
614 );
615
603 -it.effect(
604 - "preserves settings during discovery and keybindings during snapshot ACK at the config RPC boundary",
605 - () =>
616 +it.effect.each(["pending", "cached"] as const)(
617 + "%s remote discovery preserves initial config and updates through discovery and ACK",
618 + (discovery) =>
619 Effect.gen(function* () {
620 const keybindings = yield* Keybindings.Keybindings;
621 const settings = yield* ServerSettings.ServerSettingsService;
@@ -617,6 +630,9 @@ it.effect(
630 const initialKeybindings = (yield* keybindings.getSnapshot).keybindings;
631 const discoveryStarted = yield* Deferred.make<void>();
632 const finishDiscovery = yield* Deferred.make<void>();
633 + const remoteDiscoveryStarted = yield* Deferred.make<void>();
634 + const finishRemoteDiscovery = yield* Deferred.make<void>();
635 + const targets = [{ kind: "mdns" as const, host: "test.local" }];
636 const responses = yield* Queue.unbounded<ServerConfigStreamEvent>();
637 const configRpcServices = Layer.mergeAll(
638 layerUnusedConfigRpcServices,
@@ -635,7 +651,13 @@ it.effect(
651 }),
652 Layer.mock(UsageLimitSources.UsageLimitSources)({ streamChanges: Stream.make([]) }),
653 Layer.mock(RemoteOpenTargets.RemoteOpenTargets)({
638 - resolveTargets: () => Effect.succeed([]),
654 + resolveTargets: () =>
655 + Deferred.succeed(remoteDiscoveryStarted, undefined).pipe(
656 + Effect.andThen(
657 + discovery === "cached" ? Effect.void : Deferred.await(finishRemoteDiscovery),
658 + ),
659 + Effect.as(targets),
660 + ),
661 }),
662 Layer.mock(DirectEndpoints.DirectEndpoints)({ resolve: () => Effect.succeed([]) }),
663 Layer.mock(ManagedProjectFolders.ManagedProjectFolders)({
@@ -710,12 +732,14 @@ it.effect(
732 headers: Headers.empty,
733 });
734 yield* Deferred.await(discoveryStarted);
735 + assert.isTrue(yield* Deferred.isDone(remoteDiscoveryStarted));
736
737 const duringDiscovery = yield* settings.updateSettings({ defaultAutoPull: true });
738 yield* Deferred.succeed(finishDiscovery, undefined);
739 const snapshot = yield* Queue.take(responses);
740 assert.equal(snapshot.type, "snapshot");
741 if (snapshot.type !== "snapshot") return yield* Effect.die("Missing initial snapshot");
742 + assert.deepEqual(snapshot.config.remoteOpenTargets, discovery === "cached" ? targets : []);
743 assert.isFalse(snapshot.config.settings.defaultAutoPull);
744 assert.deepEqual(snapshot.config.keybindings, initialKeybindings);
745 const duringAck = yield* keybindings.upsertKeybindingRule({
@@ -752,6 +776,20 @@ it.effect(
776 }
777 assert.isEmpty(expectedSettings);
778 assert.isEmpty(expectedKeybindings);
779 + if (discovery === "pending") {
780 + yield* Deferred.await(remoteDiscoveryStarted);
781 + yield* Deferred.succeed(finishRemoteDiscovery, undefined);
782 + const resolved = yield* Queue.take(responses);
783 + assert.equal(resolved.type, "snapshot");
784 + if (resolved.type !== "snapshot") return yield* Effect.die("Missing remote targets");
785 + assert.deepEqual(resolved.config.remoteOpenTargets, targets);
786 + assert.deepEqual(
787 + resolved.config.settings,
788 + ServerSettings.redactServerSettingsForClient(latestSettings),
789 + );
790 + assert.deepEqual(resolved.config.keybindings, latestKeybindings);
791 + yield* acknowledge;
792 + }
793 yield* server.write(0, { _tag: "Interrupt", requestId, interruptors: [] });
794 }).pipe(
795 Effect.provide(
apps/server/src/ws.ts
+39 -6
@@ -9,6 +9,7 @@ import * as DateTime from "effect/DateTime";
9 import * as Duration from "effect/Duration";
10 import * as Base64 from "effect/encoding/Base64";
11 import * as Effect from "effect/Effect";
12 +import * as Fiber from "effect/Fiber";
13 import * as FileSystem from "effect/FileSystem";
14 import * as Layer from "effect/Layer";
15 import * as Option from "effect/Option";
@@ -313,10 +314,11 @@ const resolveEditorConfig = Effect.fn("ws.resolveEditorConfig")(function* <E, R>
314 };
315 });
316
316 -export const withLateEditorConfig = <E, R>(
317 +export const withLateConfigDiscovery = <E, R>(
318 config: ClientServerConfig,
319 liveUpdates: Stream.Stream<ServerConfigStreamEvent, E, R>,
320 launcher: EditorDiscovery,
321 + remoteOpenTargets: RemoteOpenTargets.RemoteOpenTargets["Service"],
322 ) => {
323 const lateEditorConfig = Stream.fromEffect(launcher.resolveAvailableEditors()).pipe(
324 Stream.filter(
@@ -337,7 +339,14 @@ export const withLateEditorConfig = <E, R>(
339 Stream.map((editorConfig) => ({ type: "editorsResolved" as const, editorConfig })),
340 );
341
340 - return Stream.merge(liveUpdates, lateEditorConfig).pipe(
342 + const lateRemoteOpenTargets = Stream.fromEffect(remoteOpenTargets.resolveTargets()).pipe(
343 + Stream.filter(
344 + (targets) => JSON.stringify(targets) !== JSON.stringify(config.remoteOpenTargets ?? []),
345 + ),
346 + Stream.map((targets) => ({ type: "remoteOpenTargetsResolved" as const, targets })),
347 + );
348 +
349 + return Stream.merge(liveUpdates, Stream.merge(lateEditorConfig, lateRemoteOpenTargets)).pipe(
350 Stream.mapAccum(
351 (): ClientServerConfig => config,
352 (current, event): readonly [ClientServerConfig, ReadonlyArray<ServerConfigStreamEvent>] => {
@@ -352,6 +361,10 @@ export const withLateEditorConfig = <E, R>(
361 const next = { ...rest, ...event.editorConfig };
362 return [next, [{ version: 1, type: "snapshot", config: next }]];
363 }
364 + case "remoteOpenTargetsResolved": {
365 + const next = { ...current, remoteOpenTargets: event.targets };
366 + return [next, [{ version: 1, type: "snapshot", config: next }]];
367 + }
368 case "keybindingsUpdated":
369 return [{ ...current, ...event.payload }, [event]];
370 case "providerStatuses":
@@ -1754,6 +1767,7 @@ export const layerWsRpc = (
1767 const loadServerConfig = Effect.fn("ws.loadServerConfig")(function* (options: {
1768 readonly usageLimitsCommand: boolean;
1769 readonly workspaceSnapshotsOnDemand: boolean;
1770 + readonly deferRemoteOpenTargets: boolean;
1771 }) {
1772 const keybindingsConfig = yield* keybindings.loadConfigState;
1773 const currentProviders = yield* providerRegistry.getProviders;
@@ -1773,7 +1787,9 @@ export const layerWsRpc = (
1787 const discovery = yield* resolveOpenDiscoveryForConfig({
1788 editors: externalLauncher.resolveAvailableEditors(),
1789 fileManagerRevealKind: externalLauncher.resolveFileManagerRevealKind(),
1776 - remoteOpenTargets: remoteOpenTargets.resolveTargets(),
1790 + remoteOpenTargets: options.deferRemoteOpenTargets
1791 + ? Effect.succeed([])
1792 + : remoteOpenTargets.resolveTargets(),
1793 directEndpoints: directEndpoints.resolve(),
1794 });
1795
@@ -2203,7 +2219,11 @@ export const layerWsRpc = (
2219 ),
2220 [WS_METHODS.serverProbe]: (_input) => Effect.succeed({}),
2221 [WS_METHODS.serverGetConfig]: (_input) =>
2206 - loadServerConfig({ usageLimitsCommand: false, workspaceSnapshotsOnDemand: false }),
2222 + loadServerConfig({
2223 + usageLimitsCommand: false,
2224 + workspaceSnapshotsOnDemand: false,
2225 + deferRemoteOpenTargets: false,
2226 + }),
2227 [WS_METHODS.serverSearchAcpRegistry]: (input) =>
2228 acpRegistryCatalog
2229 .search(input)
@@ -3126,9 +3146,13 @@ export const layerWsRpc = (
3146 // Buffer changes through discovery and the initial snapshot's RPC ACK wait.
3147 const keybindingsChanges = yield* keybindings.subscribeChanges;
3148 const settingsChanges = yield* serverSettings.subscribeChanges;
3149 + const remoteTargets = yield* Effect.forkScoped(remoteOpenTargets.resolveTargets(), {
3150 + startImmediately: true,
3151 + });
3152 const config = yield* loadServerConfig({
3153 usageLimitsCommand,
3154 workspaceSnapshotsOnDemand,
3155 + deferRemoteOpenTargets: true,
3156 });
3157 const keybindingsUpdates = keybindingsChanges.pipe(
3158 Stream.map((event) => ({
@@ -3215,9 +3239,18 @@ export const layerWsRpc = (
3239 ),
3240 );
3241
3242 + const remoteResult = yield* Effect.sync(() => remoteTargets.pollUnsafe());
3243 + const initialConfig =
3244 + remoteResult?._tag === "Success"
3245 + ? { ...config, remoteOpenTargets: remoteResult.value }
3246 + : config;
3247 return Stream.concat(
3219 - rpcInitialItems([{ version: 1 as const, type: "snapshot" as const, config }]),
3220 - withLateEditorConfig(config, liveUpdates, externalLauncher),
3248 + rpcInitialItems([
3249 + { version: 1 as const, type: "snapshot" as const, config: initialConfig },
3250 + ]),
3251 + withLateConfigDiscovery(initialConfig, liveUpdates, externalLauncher, {
3252 + resolveTargets: () => Fiber.join(remoteTargets),
3253 + }),
3254 );
3255 }),
3256 ),
apps/web/scripts/warm-dep-cache.ts
+8
@@ -10,6 +10,14 @@ import { optimizeDeps, resolveConfig } from "vite";
10
11 const webRoot = NodePath.dirname(NodePath.dirname(NodeURL.fileURLToPath(import.meta.url)));
12
13 +const configStart = performance.now();
14 const config = await resolveConfig({ root: webRoot, logLevel: "error" }, "serve");
15 +if (process.env.T3CODE_STARTUP_PROFILE_DIR) {
16 + performance.measure("web.warmDepCache.resolveConfig", { start: configStart });
17 +}
18 +const optimizeStart = performance.now();
19 await optimizeDeps(config);
20 +if (process.env.T3CODE_STARTUP_PROFILE_DIR) {
21 + performance.measure("web.warmDepCache.optimizeDeps", { start: optimizeStart });
22 +}
23 console.log("[warm-dep-cache] web dependency cache is warm");
docs/operations/development.md
+28
@@ -86,6 +86,34 @@ To add a scenario, point a `SCENARIOS` entry at a generic ACP replay fixture
86 The agent replays session updates, permission requests, and questions. It drops session setup
87 and vendor frames, so Grok and fx recordings lose their vendor-only behavior.
88
89 +### Profiling dev startup
90 +
91 +Run `vp run profile:startup` to capture the first 20 seconds of inherited Node processes under
92 +`.t3/startup-profiles/<timestamp>`. Workers that execute the preload get separate profiles.
93 +It starts the normal dev runner and accepts its flags.
94 +Stop it with Ctrl+C after the capture. Set `T3CODE_STARTUP_PROFILE_DIR` to choose another output
95 +directory. Profiling adds overhead, so compare readiness with an ordinary `vp run dev` run.
96 +
97 +Open a `.cpuprofile` in Chrome DevTools' Performance panel for sampled function stacks and source
98 +lines. Each `.modules.json` is a Chrome trace containing timed module resolution, loading,
99 +synchronous subprocess calls, and startup measures. Per-file records include importer URLs,
100 +source loading, preparation, recursive dependency linking, and top-level evaluation. Preparation
101 +uses synchronous loader boundaries; linking includes dependencies, and CommonJS evaluation can
102 +include nested `require` calls. Some ESM/CommonJS interop reports a combined stage. `.process.json` records the process, Node version, and capture window.
103 +The server's nested Effect and SQL spans remain in `.t3/userdata/logs/server.trace.ndjson`.
104 +
105 +The preload temporarily adds module-body timing markers and uses one automatic debugger pause
106 +to instrument the live Node loader. The launcher adds `--no-node-snapshot` to inherited
107 +`NODE_OPTIONS` because Node 26's snapshotted loader cannot accept that breakpoint. Include the
108 +same flag when using the preload directly. This disables Node's built-in startup snapshot,
109 +can change compilation-cache hits, and adds overhead.
110 +Treat per-file captures as diagnostic runs; use uninstrumented runs for baseline startup latency.
111 +The first entry module can compile before loader instrumentation is installed.
112 +
113 +A fresh process still uses filesystem, Node compilation, provider, and Vite dependency caches.
114 +Measure a missing Vite dependency cache separately from a restart with an existing database.
115 +Neither the Vite ready message nor the HTTP listener proves that a browser has rendered the app.
116 +
117 ### Sharing and remote debugging
118
119 `vp run dev --share` publishes the web port over the machine's tailnet and prints a pairing URL
package.json
+1
@@ -5,6 +5,7 @@
5 "scripts": {
6 "prepare": "vp config --no-agent",
7 "dev": "node scripts/dev-runner.ts dev",
8 + "profile:startup": "node scripts/profile-startup.mjs",
9 "dev:share": "node scripts/dev-runner.ts dev --share",
10 "dev:server": "node scripts/dev-runner.ts dev:server",
11 "dev:web": "node scripts/dev-runner.ts dev:web",
packages/provider-cursor/src/server/sdk.ts
+8
@@ -3,6 +3,7 @@ import * as NodeModule from "node:module";
3
4 // createRequire loads the disk-backed SDK and adjacent chunks even from a Node SEA executable.
5 const requireCursorSdk = NodeModule.createRequire(import.meta.url);
6 +const sdkImportStart = performance.now();
7 export const {
8 Agent,
9 AuthenticationError,
@@ -12,6 +13,13 @@ export const {
13 CursorSdkError,
14 InMemoryCredentialStore,
15 } = requireCursorSdk("@cursor/sdk") as typeof import("@cursor/sdk");
16 +if (process.env.T3CODE_STARTUP_PROFILE_DIR) {
17 + performance.measure("provider.cursor.importSdk", { start: sdkImportStart });
18 +}
19 +const sqliteImportStart = performance.now();
20 export const { SqliteLocalAgentStore } = requireCursorSdk(
21 "@cursor/sdk/sqlite",
22 ) as typeof import("@cursor/sdk/sqlite");
23 +if (process.env.T3CODE_STARTUP_PROFILE_DIR) {
24 + performance.measure("provider.cursor.importSqliteStore", { start: sqliteImportStart });
25 +}
scripts/profile-startup-modules.mjs new
+262
@@ -0,0 +1,262 @@
1 +import * as NodeFS from "node:fs";
2 +import * as NodeModule from "node:module";
3 +import * as NodePerfHooks from "node:perf_hooks";
4 +import * as NodeURL from "node:url";
5 +
6 +export function profileStartupModules(session, events, threadId) {
7 + const now = () => NodePerfHooks.performance.now();
8 + const origin = NodePerfHooks.performance.timeOrigin;
9 + const loaded = new Map();
10 + const compiling = new Map();
11 + const evaluating = new Map();
12 + const registryKey = "__t3codeStartupModuleProfiler";
13 + const previousRegistry = globalThis[registryKey];
14 + const previousModuleRegistry = NodeModule.default[registryKey];
15 + const restorers = [];
16 + let active = true;
17 + let installed = false;
18 + let breakpoint;
19 + let currentLink;
20 + let nextLink = 0;
21 +
22 + const record = (stage, url, start, end, attributes = {}) => {
23 + if (!active) return;
24 + events.push({
25 + name: `${stage} ${url}`,
26 + cat: "module.detail",
27 + ph: "X",
28 + pid: process.pid,
29 + tid: threadId,
30 + ts: (origin + start) * 1000,
31 + dur: (end - start) * 1000,
32 + args: { stage, url, ...attributes },
33 + });
34 + };
35 + const toUrl = (file) =>
36 + file instanceof URL
37 + ? file.href
38 + : typeof file === "string"
39 + ? file.startsWith("file:")
40 + ? file
41 + : NodeURL.pathToFileURL(file).href
42 + : undefined;
43 + const inject = (source, statement, preserveDirectives) => {
44 + let offset = source.startsWith("#!") ? source.indexOf("\n") + 1 : 0;
45 + if (preserveDirectives) {
46 + for (;;) {
47 + const trivia = /^(?:\s+|\/\/[^\n]*(?:\n|$)|\/\*[\s\S]*?\*\/)*/.exec(
48 + source.slice(offset),
49 + )[0];
50 + offset += trivia.length;
51 + if (!/^["']/.test(source.slice(offset))) break;
52 + const directive = /^(?:"(?:\\.|[^"\\\r\n])*"|'(?:\\.|[^'\\\r\n])*')\s*;/.exec(
53 + source.slice(offset),
54 + );
55 + // Leave ambiguous semicolon-free prologues untouched rather than changing strict-mode semantics.
56 + if (!directive) return undefined;
57 + offset += directive[0].length;
58 + }
59 + }
60 + return source.slice(0, offset) + statement + source.slice(offset);
61 + };
62 + const registry = {
63 + begin(url) {
64 + if (active) evaluating.set(url, now());
65 + },
66 + end(url) {
67 + const start = evaluating.get(url);
68 + if (start === undefined) return;
69 + record("evaluate", url, start, now(), {
70 + format: "esm",
71 + boundary: "module body; top-level await included",
72 + });
73 + evaluating.delete(url);
74 + },
75 + cjsBegin(filename) {
76 + const url = toUrl(filename),
77 + pending = compiling.get(url);
78 + if (!pending) return;
79 + pending.evaluationStart = now();
80 + record("prepare", url, pending.start, pending.evaluationStart, {
81 + format: "commonjs",
82 + boundary: "_compile entry to module-body entry",
83 + });
84 + },
85 + install(job) {
86 + if (installed) return;
87 + installed = true;
88 + const loader = Object.getPrototypeOf(job.loader);
89 + for (const method of [
90 + "loadAndTranslate",
91 + "loadAndTranslateForRequireInImportedCJS",
92 + "loadAndTranslateForImportInRequiredESM",
93 + ]) {
94 + const original = loader[method];
95 + if (typeof original !== "function") continue;
96 + loader[method] = function (url, ...args) {
97 + const start = now();
98 + try {
99 + return original.call(this, url, ...args);
100 + } finally {
101 + const moduleUrl = typeof url === "string" ? url : url.url;
102 + const pending = loaded.get(moduleUrl);
103 + if (pending && pending.start >= start)
104 + record("prepare", moduleUrl, pending.start, now(), {
105 + format: pending.format,
106 + boundary:
107 + "source-ready to loadAndTranslate return; compilation and format preparation",
108 + });
109 + }
110 + };
111 + restorers.push(() => {
112 + loader[method] = original;
113 + });
114 + }
115 + const prototype = Object.getPrototypeOf(Object.getPrototypeOf(job)),
116 + link = prototype.syncLink;
117 + prototype.syncLink = function (...args) {
118 + const start = now(),
119 + parent = currentLink,
120 + id = ++nextLink;
121 + currentLink = { id, url: this.url };
122 + try {
123 + return link.apply(this, args);
124 + } finally {
125 + record("link", this.url, start, now(), {
126 + id,
127 + parentId: parent?.id,
128 + importedBy: parent?.url,
129 + boundary: "ModuleJob.syncLink; includes recursive dependency loading",
130 + });
131 + currentLink = parent;
132 + }
133 + };
134 + restorers.push(() => {
135 + prototype.syncLink = link;
136 + });
137 + },
138 + };
139 + globalThis[registryKey] = registry;
140 + NodeModule.default[registryKey] = registry;
141 +
142 + session.post("Debugger.enable");
143 + // One pause obtains the live loader; subsequent measurements use synchronous method boundaries.
144 + const source = process.binding("natives")["internal/modules/esm/module_job"].split("\n");
145 + const classLine = source.findIndex((line) => line.includes("class ModuleJob extends"));
146 + const lineNumber = source.findIndex(
147 + (line, index) => index > classLine && line.includes("this.linked = this.link("),
148 + );
149 + const paused = ({ params }) => {
150 + if (!breakpoint || !params.hitBreakpoints?.includes(breakpoint)) return;
151 + const start = now();
152 + session.post("Debugger.removeBreakpoint", { breakpointId: breakpoint });
153 + breakpoint = undefined;
154 + session.post(
155 + "Debugger.evaluateOnCallFrame",
156 + {
157 + callFrameId: params.callFrames[0].callFrameId,
158 + expression: `globalThis.${registryKey}.install(this)`,
159 + silent: true,
160 + },
161 + (error, result) => {
162 + if (error || result?.exceptionDetails)
163 + record("instrumentation-error", "node:esm-loader", start, now());
164 + },
165 + );
166 + record("instrumentation-setup", "node:esm-loader", start, now());
167 + session.post("Debugger.resume");
168 + };
169 + session.on("Debugger.paused", paused);
170 + if (lineNumber >= 0)
171 + session.post(
172 + "Debugger.setBreakpointByUrl",
173 + {
174 + url: "node:internal/modules/esm/module_job",
175 + lineNumber,
176 + },
177 + (error, result) => {
178 + if (!error) breakpoint = result.breakpointId;
179 + },
180 + );
181 +
182 + const readFileSync = NodeFS.default.readFileSync;
183 + NodeFS.default.readFileSync = function (file, ...args) {
184 + const url = toUrl(file);
185 + if (!url || !/\.[cm]?[jt]sx?(?:$|\?)/.test(url)) return readFileSync.call(this, file, ...args);
186 + const start = now();
187 + try {
188 + return readFileSync.call(this, file, ...args);
189 + } finally {
190 + record("read", url, start, now());
191 + }
192 + };
193 + const compile = NodeModule.default.prototype._compile;
194 + NodeModule.default.prototype._compile = function (source, filename, ...args) {
195 + const url = toUrl(filename),
196 + pending = { start: now() };
197 + const format = args[0] ?? loaded.get(url)?.format;
198 + const isEsm =
199 + format === "module" ||
200 + format === "module-typescript" ||
201 + /(^|[;\n])\s*(?:import[\s.]|export\s)/.test(source);
202 + const annotated = isEsm
203 + ? undefined
204 + : inject(source, `module.constructor.${registryKey}?.cjsBegin(__filename);`, true);
205 + compiling.set(url, pending);
206 + try {
207 + return compile.call(this, annotated ?? source, filename, ...args);
208 + } finally {
209 + const end = now();
210 + record(isEsm ? "require-esm" : "commonjs", url, pending.start, end, {
211 + importedBy: this.parent?.filename ? toUrl(this.parent.filename) : undefined,
212 + sourceBytes: Buffer.byteLength(source),
213 + });
214 + if (pending.evaluationStart !== undefined)
215 + record("evaluate", url, pending.evaluationStart, end, {
216 + format: "commonjs",
217 + includesNestedRequires: true,
218 + });
219 + compiling.delete(url);
220 + }
221 + };
222 + NodeModule.syncBuiltinESMExports();
223 +
224 + return {
225 + sourceReady(url, result) {
226 + if (!url.startsWith("file:")) return result;
227 + const format = result.format;
228 + let source = result.source;
229 + if (typeof source !== "string" && ArrayBuffer.isView(source))
230 + source = Buffer.from(source.buffer, source.byteOffset, source.byteLength).toString("utf8");
231 + if (typeof source === "string" && (format === "module" || format === "module-typescript")) {
232 + // A module-local globalThis binding would put the injected access in its temporal dead zone.
233 + if (!/\b(?:const|let|var|class|function|as)\s+globalThis\b/.test(source)) {
234 + source =
235 + inject(source, `globalThis.${registryKey}?.begin(import.meta.url);`, false) +
236 + `\n;globalThis.${registryKey}?.end(import.meta.url);\n`;
237 + result = { ...result, source };
238 + }
239 + }
240 + loaded.set(url, { start: now(), format });
241 + return result;
242 + },
243 + finish() {
244 + const end = now();
245 + for (const [url, start] of evaluating)
246 + record("evaluate", url, start, end, { incomplete: true });
247 + record("instrumentation-status", "node:esm-loader", end, end, { installed });
248 + active = false;
249 + if (breakpoint) session.post("Debugger.removeBreakpoint", { breakpointId: breakpoint });
250 + session.off("Debugger.paused", paused);
251 + session.post("Debugger.disable");
252 + for (const restore of restorers.reverse()) restore();
253 + NodeFS.default.readFileSync = readFileSync;
254 + NodeModule.default.prototype._compile = compile;
255 + NodeModule.syncBuiltinESMExports();
256 + if (previousRegistry === undefined) delete globalThis[registryKey];
257 + else globalThis[registryKey] = previousRegistry;
258 + if (previousModuleRegistry === undefined) delete NodeModule.default[registryKey];
259 + else NodeModule.default[registryKey] = previousModuleRegistry;
260 + },
261 + };
262 +}
scripts/profile-startup.mjs new
+165
@@ -0,0 +1,165 @@
1 +// Opt in with T3CODE_STARTUP_PROFILE_DIR=/absolute/path NODE_OPTIONS="--no-node-snapshot --import=/absolute/path/to/this/file".
2 +import * as NodeFS from "node:fs";
3 +import * as NodeInspector from "node:inspector";
4 +import * as NodeChildProcess from "node:child_process";
5 +import * as NodeModule from "node:module";
6 +import * as NodePath from "node:path";
7 +import * as NodePerfHooks from "node:perf_hooks";
8 +import * as NodeWorkerThreads from "node:worker_threads";
9 +import * as NodeURL from "node:url";
10 +
11 +import { profileStartupModules } from "./profile-startup-modules.mjs";
12 +
13 +const directory = process.env.T3CODE_STARTUP_PROFILE_DIR;
14 +const isLauncher = process.argv[1] === NodeURL.fileURLToPath(import.meta.url);
15 +if (directory && !isLauncher) {
16 + NodeFS.mkdirSync(directory, { recursive: true });
17 + const { threadId } = NodeWorkerThreads;
18 + const prefix = NodePath.join(directory, `${process.pid}-${threadId}`);
19 + const origin = NodePerfHooks.performance.timeOrigin;
20 + const events = [];
21 + const session = new NodeInspector.Session();
22 + session.connect();
23 + session.post("Profiler.setSamplingInterval", { interval: 1000 });
24 + session.post("Profiler.enable");
25 + const profileStartTimeUnixMs = origin + NodePerfHooks.performance.now();
26 + session.post("Profiler.start");
27 +
28 + const moduleDetails = profileStartupModules(session, events, threadId);
29 +
30 + const measure = (name, operation, cat = "module", attributes = {}) => {
31 + const start = NodePerfHooks.performance.now();
32 + try {
33 + return operation();
34 + } finally {
35 + events.push({
36 + name,
37 + cat,
38 + ph: "X",
39 + pid: process.pid,
40 + tid: threadId,
41 + ts: (origin + start) * 1000,
42 + dur: (NodePerfHooks.performance.now() - start) * 1000,
43 + args: attributes,
44 + });
45 + }
46 + };
47 +
48 + const recordMeasures = (entries) => {
49 + for (const entry of entries) {
50 + events.push({
51 + name: entry.name,
52 + cat: "startup",
53 + ph: "X",
54 + pid: process.pid,
55 + tid: threadId,
56 + ts: (origin + entry.startTime) * 1000,
57 + dur: entry.duration * 1000,
58 + });
59 + }
60 + };
61 + const observer = new NodePerfHooks.PerformanceObserver((list) =>
62 + recordMeasures(list.getEntries()),
63 + );
64 + observer.observe({ entryTypes: ["measure"] });
65 + const execFileSync = NodeChildProcess.default.execFileSync;
66 + NodeChildProcess.default.execFileSync = function (file, ...args) {
67 + return measure(
68 + `execFileSync ${file}`,
69 + () => execFileSync.call(this, file, ...args),
70 + "subprocess",
71 + );
72 + };
73 + NodeModule.syncBuiltinESMExports();
74 +
75 + const hooks = NodeModule.registerHooks({
76 + resolve(specifier, context, next) {
77 + const attributes = { specifier, parentURL: context.parentURL };
78 + return measure(
79 + `resolve ${specifier}`,
80 + () => {
81 + const result = next(specifier, context);
82 + attributes.url = result.url;
83 + attributes.format = result.format;
84 + return result;
85 + },
86 + "module",
87 + attributes,
88 + );
89 + },
90 + load(url, context, next) {
91 + const result = measure(`load ${url}`, () => next(url, context), "module", {
92 + url,
93 + format: context.format,
94 + });
95 + return moduleDetails.sourceReady(url, result);
96 + },
97 + });
98 +
99 + let finished = false;
100 + const finish = () => {
101 + if (finished) return;
102 + finished = true;
103 + hooks.deregister();
104 + moduleDetails.finish();
105 + recordMeasures(observer.takeRecords());
106 + observer.disconnect();
107 + NodeChildProcess.default.execFileSync = execFileSync;
108 + NodeModule.syncBuiltinESMExports();
109 + session.post("Profiler.stop", (error, result) => {
110 + if (!error) NodeFS.writeFileSync(`${prefix}.cpuprofile`, JSON.stringify(result.profile));
111 + session.disconnect();
112 + });
113 + NodeFS.writeFileSync(`${prefix}.modules.json`, JSON.stringify({ traceEvents: events }));
114 + NodeFS.writeFileSync(
115 + `${prefix}.process.json`,
116 + JSON.stringify({
117 + pid: process.pid,
118 + parentPid: process.ppid,
119 + threadId,
120 + nodeVersion: process.version,
121 + executable: process.execPath,
122 + entry: process.argv[1],
123 + timeOrigin: origin,
124 + profileStartTimeUnixMs,
125 + captureEnd: origin + NodePerfHooks.performance.now(),
126 + cpu: process.cpuUsage(),
127 + memory: process.memoryUsage(),
128 + }),
129 + );
130 + };
131 + // Bound the capture without keeping dev servers or short-lived helpers alive.
132 + setTimeout(finish, 20_000).unref();
133 + process.once("exit", finish);
134 +}
135 +
136 +if (isLauncher) {
137 + const output = NodePath.resolve(
138 + directory ??
139 + NodePath.join(".t3/startup-profiles", new Date().toISOString().replaceAll(":", "-")),
140 + );
141 + console.log(`[profile-startup] Writing CPU profiles and timeline events to ${output}`);
142 + const child = NodeChildProcess.spawn(
143 + process.execPath,
144 + ["scripts/dev-runner.ts", "dev", ...process.argv.slice(2)],
145 + {
146 + stdio: "inherit",
147 + env: {
148 + ...process.env,
149 + T3CODE_STARTUP_PROFILE_DIR: output,
150 + // Node 26's snapshotted loader cannot accept the debugger breakpoint used by this profiler.
151 + NODE_OPTIONS:
152 + `${process.env.NODE_OPTIONS ?? ""} --no-node-snapshot --import=${import.meta.url}`.trim(),
153 + },
154 + },
155 + );
156 + process.on("SIGINT", () => child.kill("SIGINT"));
157 + process.on("SIGTERM", () => child.kill("SIGTERM"));
158 + child.on("error", (error) => {
159 + console.error(error);
160 + process.exitCode = 1;
161 + });
162 + child.on("exit", (code) => {
163 + process.exitCode = code ?? 1;
164 + });
165 +}
scripts/profile-startup.test.ts new
+149
@@ -0,0 +1,149 @@
1 +// @effect-diagnostics nodeBuiltinImport:off -- Runs the profiling preload in a real Node subprocess.
2 +import * as NodeChildProcess from "node:child_process";
3 +import * as NodeFS from "node:fs";
4 +import * as NodeOS from "node:os";
5 +import * as NodePath from "node:path";
6 +import * as NodeURL from "node:url";
7 +import * as Schema from "effect/Schema";
8 +import { expect, it } from "vite-plus/test";
9 +
10 +const decodeTrace = Schema.decodeUnknownSync(
11 + Schema.fromJsonString(
12 + Schema.Struct({
13 + traceEvents: Schema.Array(
14 + Schema.Struct({
15 + name: Schema.String,
16 + ts: Schema.Number,
17 + dur: Schema.Number,
18 + args: Schema.optional(
19 + Schema.Struct({
20 + stage: Schema.optional(Schema.String),
21 + url: Schema.optional(Schema.String),
22 + parentURL: Schema.optional(Schema.String),
23 + importedBy: Schema.optional(Schema.String),
24 + installed: Schema.optional(Schema.Boolean),
25 + }),
26 + ),
27 + }),
28 + ),
29 + }),
30 + ),
31 +);
32 +
33 +const decodeRunner = Schema.decodeUnknownSync(
34 + Schema.fromJsonString(Schema.Struct({ pid: Schema.Number, args: Schema.Array(Schema.String) })),
35 +);
36 +
37 +it("attributes ESM and CommonJS imports without changing module execution", () => {
38 + const directory = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-startup-profile-"));
39 + try {
40 + NodeFS.writeFileSync(NodePath.join(directory, "package.json"), '{"type":"module"}');
41 + const fixtures = {
42 + "root.mjs": `
43 + import { value } from './dependency.mjs';
44 + import strict from './strict.cjs';
45 + import loose from './loose.cjs';
46 + import interop from './interop.cjs';
47 + if (value !== 42 || strict !== undefined || loose !== true || interop !== 9) {
48 + throw Error('Profiling changed module semantics');
49 + }
50 + `,
51 + "dependency.mjs": "export const value = 42;",
52 + "strict.cjs": `/* retain the directive */\n"use strict"; module.exports = (function () { return this; })();`,
53 + "loose.cjs": "module.exports = (function () { return this; })() === globalThis;",
54 + "interop.cjs": "module.exports = require('./required.js').value;",
55 + "required.js": "export const value = 9;",
56 + };
57 + for (const [name, source] of Object.entries(fixtures)) {
58 + NodeFS.writeFileSync(NodePath.join(directory, name), source);
59 + }
60 + const output = NodePath.join(directory, "capture");
61 + const root = NodeURL.pathToFileURL(
62 + NodeFS.realpathSync(NodePath.join(directory, "root.mjs")),
63 + ).href;
64 + NodeChildProcess.execFileSync(
65 + process.execPath,
66 + [
67 + "--no-node-snapshot",
68 + "--import",
69 + NodeURL.pathToFileURL(NodePath.join(import.meta.dirname, "profile-startup.mjs")).href,
70 + "--input-type=module",
71 + "-e",
72 + `await import(${JSON.stringify(root)})`,
73 + ],
74 + { env: { ...process.env, NODE_OPTIONS: "", T3CODE_STARTUP_PROFILE_DIR: output } },
75 + );
76 + const spans = NodeFS.readdirSync(output)
77 + .filter((name) => name.endsWith(".modules.json"))
78 + .flatMap(
79 + (name) => decodeTrace(NodeFS.readFileSync(NodePath.join(output, name), "utf8")).traceEvents,
80 + );
81 + expect(spans.some((span) => span.args?.installed === true)).toBe(true);
82 + for (const name of Object.keys(fixtures)) {
83 + const url = NodeURL.pathToFileURL(NodeFS.realpathSync(NodePath.join(directory, name))).href;
84 + const stages = spans.filter((span) => span.args?.url === url).map((span) => span.args?.stage);
85 + expect(stages, name).toEqual(
86 + expect.arrayContaining(
87 + name === "required.js" ? ["link", "require-esm"] : ["prepare", "evaluate"],
88 + ),
89 + );
90 + }
91 + const prepared = spans.find(
92 + (span) => span.args?.url === root && span.args?.stage === "prepare",
93 + );
94 + const linked = spans.find((span) => span.args?.url === root && span.args?.stage === "link");
95 + if (!prepared || !linked) throw Error("Missing root module preparation/link boundaries");
96 + expect(prepared.ts + prepared.dur).toBeLessThanOrEqual(linked.ts);
97 + const dependency = NodeURL.pathToFileURL(
98 + NodeFS.realpathSync(NodePath.join(directory, "dependency.mjs")),
99 + ).href;
100 + expect(
101 + spans.find((span) => span.args?.url === dependency && span.args?.stage === "link")?.args
102 + ?.importedBy,
103 + ).toBe(root);
104 + } finally {
105 + NodeFS.rmSync(directory, { recursive: true, force: true });
106 + }
107 +});
108 +
109 +it("captures only the dev runner and preserves its exit status", () => {
110 + const directory = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-startup-launcher-"));
111 + try {
112 + NodeFS.mkdirSync(NodePath.join(directory, "scripts"));
113 + NodeFS.writeFileSync(
114 + NodePath.join(directory, "scripts/dev-runner.ts"),
115 + "console.log(JSON.stringify({ pid: process.pid, args: process.argv.slice(2) }));",
116 + );
117 + const output = NodePath.join(directory, "capture");
118 + const stdout = NodeChildProcess.execFileSync(
119 + process.execPath,
120 + [NodePath.join(import.meta.dirname, "profile-startup.mjs"), "--no-seed"],
121 + {
122 + cwd: directory,
123 + env: { ...process.env, NODE_OPTIONS: "", T3CODE_STARTUP_PROFILE_DIR: output },
124 + encoding: "utf8",
125 + },
126 + );
127 + const runner = decodeRunner(stdout.trim().split("\n").at(-1));
128 + expect(runner.args).toEqual(["dev", "--no-seed"]);
129 + expect(NodeFS.readdirSync(output).sort()).toEqual(
130 + ["cpuprofile", "modules.json", "process.json"].map((suffix) => `${runner.pid}-0.${suffix}`),
131 + );
132 + NodeFS.writeFileSync(
133 + NodePath.join(directory, "scripts/dev-runner.ts"),
134 + "process.kill(process.pid, 'SIGTERM');",
135 + );
136 + const interrupted = NodeChildProcess.spawnSync(
137 + process.execPath,
138 + [NodePath.join(import.meta.dirname, "profile-startup.mjs")],
139 + {
140 + cwd: directory,
141 + env: { ...process.env, NODE_OPTIONS: "", T3CODE_STARTUP_PROFILE_DIR: output },
142 + },
143 + );
144 + expect(interrupted.error).toBeUndefined();
145 + expect(interrupted.status).toBe(1);
146 + } finally {
147 + NodeFS.rmSync(directory, { recursive: true, force: true });
148 + }
149 +});