Skip to content

Commit ea196f9

Browse files
BioPhotonBioPhoton
authored
feat(utils): add NodeJS profiler (#1219)
1 parent bb28746 commit ea196f9

File tree

12 files changed

+2860
-451
lines changed

12 files changed

+2860
-451
lines changed

‎packages/utils/docs/profiler.md‎

Lines changed: 360 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,360 @@
1+
# User Timing Profiler
2+
3+
⏱️ **High-performance profiling utility for structured timing measurements with Chrome DevTools Extensibility API payloads.** 📊
4+
5+
---
6+
7+
The `Profiler` class provides a clean, type-safe API for performance monitoring that integrates seamlessly with Chrome DevTools. It supports both synchronous and asynchronous operations with smart defaults for custom track visualization, enabling developers to track performance bottlenecks and optimize application speed.
8+
9+
## Getting started
10+
11+
1. If you haven't already, install [@code-pushup/utils](../../README.md).
12+
13+
2. Install as a dependency with your package manager:
14+
15+
```sh
16+
npm install @code-pushup/utils
17+
```
18+
19+
```sh
20+
yarn add @code-pushup/utils
21+
```
22+
23+
```sh
24+
pnpm add @code-pushup/utils
25+
```
26+
27+
3. Import and create a profiler instance:
28+
29+
```ts
30+
import { Profiler } from '@code-pushup/utils';
31+
32+
const profiler = new Profiler({
33+
prefix: 'cp',
34+
track: 'CLI',
35+
trackGroup: 'Code Pushup',
36+
color: 'primary-dark',
37+
tracks: {
38+
utils: { track: 'Utils', color: 'primary' },
39+
core: { track: 'Core', color: 'primary-light' },
40+
},
41+
enabled: true,
42+
});
43+
```
44+
45+
4. Start measuring performance:
46+
47+
```ts
48+
// Measure synchronous operations
49+
const result = profiler.measure('data-processing', () => {
50+
return processData(data);
51+
});
52+
53+
// Measure asynchronous operations
54+
const asyncResult = await profiler.measureAsync('api-call', async () => {
55+
return await fetch('/api/data').then(r => r.json());
56+
});
57+
```
58+
59+
## Configuration
60+
61+
```ts
62+
new Profiler<T>(options: ProfilerOptions<T>)
63+
```
64+
65+
**Parameters:**
66+
67+
- `options` - Configuration options for the profiler instance
68+
69+
**Options:**
70+
71+
| Property | Type | Default | Description |
72+
| ------------ | --------- | ----------- | --------------------------------------------------------------- |
73+
| `tracks` | `object` | `undefined` | Custom track configurations merged with defaults |
74+
| `prefix` | `string` | `undefined` | Prefix for all measurement names |
75+
| `track` | `string` | `undefined` | Default track name for measurements |
76+
| `trackGroup` | `string` | `undefined` | Default track group for organization |
77+
| `color` | `string` | `undefined` | Default color for track entries |
78+
| `enabled` | `boolean` | `env var` | Whether profiling is enabled (defaults to CP_PROFILING env var) |
79+
80+
### Environment Variables
81+
82+
- `CP_PROFILING` - Enables or disables profiling globally (boolean)
83+
84+
```bash
85+
# Enable profiling in development
86+
CP_PROFILING=true npm run dev
87+
88+
# Disable profiling in production
89+
CP_PROFILING=false npm run build
90+
```
91+
92+
## API Methods
93+
94+
The profiler provides several methods for different types of performance measurements:
95+
96+
| Method | Description |
97+
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
98+
| `measure<R>(event: string, work: () => R, options?: MeasureOptions<R>): R` | Measures synchronous operation execution time with DevTools payloads. Noop when profiling is disabled. |
99+
| `measureAsync<R>(event: string, work: () => Promise<R>, options?: MeasureOptions<R>): Promise<R>` | Measures asynchronous operation execution time with DevTools payloads. Noop when profiling is disabled. |
100+
| `marker(name: string, opt?: MarkerOptions): void` | Creates performance markers as vertical lines in DevTools timeline. Noop when profiling is disabled. |
101+
| `setEnabled(enabled: boolean): void` | Controls profiling at runtime. |
102+
| `isEnabled(): boolean` | Returns whether profiling is currently enabled. |
103+
104+
### Synchronous measurements
105+
106+
```ts
107+
profiler.measure<R>(event: string, work: () => R, options?: MeasureOptions<R>): R
108+
```
109+
110+
Measures the execution time of a synchronous operation. Creates performance start/end marks and a final measure with Chrome DevTools Extensibility API payloads.
111+
112+
```ts
113+
const result = profiler.measure(
114+
'file-processing',
115+
() => {
116+
return fs.readFileSync('large-file.txt', 'utf8');
117+
},
118+
{
119+
track: 'io-operations',
120+
color: 'warning',
121+
},
122+
);
123+
```
124+
125+
### Asynchronous measurements
126+
127+
```ts
128+
profiler.measureAsync<R>(event: string, work: () => Promise<R>, options?: MeasureOptions<R>): Promise<R>
129+
```
130+
131+
Measures the execution time of an asynchronous operation.
132+
133+
```ts
134+
const data = await profiler.measureAsync(
135+
'api-request',
136+
async () => {
137+
const response = await fetch('/api/data');
138+
return response.json();
139+
},
140+
{
141+
track: 'network',
142+
trackGroup: 'external',
143+
},
144+
);
145+
```
146+
147+
### Performance markers
148+
149+
```ts
150+
profiler.marker(name: string, options?: EntryMeta & { color?: DevToolsColor }): void
151+
```
152+
153+
Creates a performance mark with Chrome DevTools marker visualization. Markers appear as vertical lines spanning all tracks and can include custom metadata.
154+
155+
```ts
156+
profiler.marker('user-action', {
157+
color: 'secondary',
158+
tooltipText: 'User clicked save button',
159+
properties: [
160+
['action', 'save'],
161+
['elementId', 'save-btn'],
162+
],
163+
});
164+
```
165+
166+
### Runtime control
167+
168+
```ts
169+
profiler.setEnabled(enabled: boolean): void
170+
profiler.isEnabled(): boolean
171+
```
172+
173+
Control profiling at runtime and check current status.
174+
175+
```ts
176+
// Disable profiling temporarily
177+
profiler.setEnabled(false);
178+
179+
// Check if profiling is active
180+
if (profiler.isEnabled()) {
181+
console.log('Performance monitoring is active');
182+
}
183+
```
184+
185+
## Examples
186+
187+
### Basic usage
188+
189+
```ts
190+
import { Profiler } from '@code-pushup/utils';
191+
192+
const profiler = new Profiler({
193+
prefix: 'cp',
194+
track: 'CLI',
195+
trackGroup: 'Code Pushup',
196+
color: 'primary-dark',
197+
tracks: {
198+
utils: { track: 'Utils', color: 'primary' },
199+
core: { track: 'Core', color: 'primary-light' },
200+
},
201+
enabled: true,
202+
});
203+
204+
// Simple measurement
205+
const result = profiler.measure('data-transform', () => {
206+
return transformData(input);
207+
});
208+
209+
// Async measurement with custom options
210+
const data = await profiler.measureAsync(
211+
'fetch-user',
212+
async () => {
213+
return await api.getUser(userId);
214+
},
215+
{
216+
track: 'api',
217+
color: 'info',
218+
},
219+
);
220+
221+
// Add a marker for important events
222+
profiler.marker('user-login', {
223+
tooltipText: 'User authentication completed',
224+
});
225+
```
226+
227+
### Custom tracks
228+
229+
Define custom track configurations for better organization:
230+
231+
```ts
232+
interface AppTracks {
233+
api: ActionTrackEntryPayload;
234+
db: ActionTrackEntryPayload;
235+
cache: ActionTrackEntryPayload;
236+
}
237+
238+
const profiler = new Profiler<AppTracks>({
239+
track: 'API',
240+
trackGroup: 'Server',
241+
color: 'primary-dark',
242+
tracks: {
243+
api: { color: 'primary' },
244+
db: { track: 'database', color: 'warning' },
245+
cache: { track: 'cache', color: 'success' },
246+
},
247+
});
248+
249+
// Use predefined tracks
250+
const users = await profiler.measureAsync('fetch-users', fetchUsers, profiler.tracks.api);
251+
252+
const saved = profiler.measure('save-user', () => saveToDb(user), {
253+
...profiler.tracks.db,
254+
color: 'primary',
255+
});
256+
```
257+
258+
## NodeJSProfiler
259+
260+
This profiler extends all options and API from Profiler with automatic process exit handling for buffered performance data.
261+
262+
The NodeJSProfiler automatically subscribes to performance observation and installs exit handlers that flush buffered data on process termination (signals, fatal errors, or normal exit).
263+
264+
## Configuration
265+
266+
```ts
267+
new NodejsProfiler<DomainEvents, Tracks>(options: NodejsProfilerOptions<DomainEvents, Tracks>)
268+
```
269+
270+
**Parameters:**
271+
272+
- `options` - Configuration options for the profiler instance
273+
274+
**Options:**
275+
276+
| Property | Type | Default | Description |
277+
| ------------------------ | --------------------------------------- | ---------- | ------------------------------------------------------------------------------- |
278+
| `encodePerfEntry` | `PerformanceEntryEncoder<DomainEvents>` | _required_ | Function that encodes raw PerformanceEntry objects into domain-specific types |
279+
| `captureBufferedEntries` | `boolean` | `true` | Whether to capture performance entries that occurred before observation started |
280+
| `flushThreshold` | `number` | `20` | Threshold for triggering queue flushes based on queue length |
281+
| `maxQueueSize` | `number` | `10_000` | Maximum number of items allowed in the queue before new entries are dropped |
282+
283+
## API Methods
284+
285+
The NodeJSProfiler inherits all API methods from the base Profiler class and adds additional methods for queue management and WAL lifecycle control.
286+
287+
| Method | Description |
288+
| ------------------------------------ | ------------------------------------------------------------------------------- |
289+
| `getStats()` | Returns comprehensive queue statistics for monitoring and debugging. |
290+
| `flush()` | Forces immediate writing of all queued performance entries to the WAL. |
291+
| `setEnabled(enabled: boolean): void` | Controls profiling at runtime with automatic WAL/observer lifecycle management. |
292+
293+
### Runtime control with Write Ahead Log lifecycle management
294+
295+
```ts
296+
profiler.setEnabled(enabled: boolean): void
297+
```
298+
299+
Controls profiling at runtime and manages the WAL/observer lifecycle. Unlike the base Profiler class, this method ensures that when profiling is enabled, the WAL is opened and the performance observer is subscribed. When disabled, the WAL is closed and the observer is unsubscribed.
300+
301+
```ts
302+
// Temporarily disable profiling to reduce overhead during heavy operations
303+
profiler.setEnabled(false);
304+
await performHeavyOperation();
305+
profiler.setEnabled(true); // WAL reopens and observer resubscribes
306+
```
307+
308+
### Queue statistics
309+
310+
```ts
311+
profiler.getStats(): {
312+
enabled: boolean;
313+
observing: boolean;
314+
walOpen: boolean;
315+
isSubscribed: boolean;
316+
queued: number;
317+
dropped: number;
318+
written: number;
319+
maxQueueSize: number;
320+
flushThreshold: number;
321+
addedSinceLastFlush: number;
322+
buffered: boolean;
323+
}
324+
```
325+
326+
Returns comprehensive queue statistics for monitoring and debugging. Provides insight into the current state of the performance entry queue, useful for monitoring memory usage and processing throughput.
327+
328+
```ts
329+
const stats = profiler.getStats();
330+
console.log(`Enabled: ${stats.enabled}, WAL Open: ${stats.walOpen}, Observing: ${stats.observing}, Subscribed: ${stats.isSubscribed}, Queued: ${stats.queued}`);
331+
if (stats.enabled && stats.walOpen && stats.observing && stats.isSubscribed && stats.queued > stats.flushThreshold) {
332+
console.log('Queue nearing capacity, consider manual flush');
333+
}
334+
```
335+
336+
### Manual flushing
337+
338+
```ts
339+
profiler.flush(): void
340+
```
341+
342+
Forces immediate writing of all queued performance entries to the write ahead log, ensuring no performance data is lost. This method is useful for manual control over when buffered data is written, complementing the automatic flushing that occurs during process exit or when thresholds are reached.
343+
344+
```ts
345+
// Flush periodically in long-running applications to prevent memory buildup
346+
setInterval(() => {
347+
profiler.flush();
348+
}, 60000); // Flush every minute
349+
350+
// Ensure all measurements are saved before critical operations
351+
await profiler.measureAsync('database-migration', async () => {
352+
await runMigration();
353+
profiler.flush(); // Ensure migration timing is recorded immediately
354+
});
355+
```
356+
357+
## Resources
358+
359+
- **[Chrome DevTools Extensibility API](https://developer.chrome.com/docs/devtools/performance/extension)** - Official documentation for performance profiling
360+
- **[User Timing API](https://developer.mozilla.org/en-US/docs/Web/API/User_Timing_API)** - Web Performance API reference

0 commit comments

Comments
 (0)