Skip to content

profiler.md

Latest commit

 

History

History
255 lines (195 loc) · 6.68 KB

profiler.md

File metadata and controls

255 lines (195 loc) · 6.68 KB

@code-pushup/utils - Profiler

npm downloads dependencies

⏱️ High-performance profiling utility for structured timing measurements with Chrome DevTools Extensibility API payloads. 📊

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.

Getting started

  1. If you haven't already, install @code-pushup/utils.

  2. Install as a dependency with your package manager:

    npm install @code-pushup/utils
    yarn add @code-pushup/utils
    pnpm add @code-pushup/utils

  3. Import and create a profiler instance:

    import { Profiler } from '@code-pushup/utils';

const profiler = new Profiler({
  prefix: 'cp',
  track: 'CLI',
  trackGroup: 'Code Pushup',
  color: 'primary-dark',
  tracks: {
    utils: { track: 'Utils', color: 'primary' },
    core: { track: 'Core', color: 'primary-light' },
  },
  enabled: true,
});

  4. Start measuring performance:

    // Measure synchronous operations
const result = profiler.measure('data-processing', () => {
  return processData(data);
});

// Measure asynchronous operations
const asyncResult = await profiler.measureAsync('api-call', async () => {
  return await fetch('/api/data').then(r => r.json());
});

Configuration

new Profiler<T>(options: ProfilerOptions<T>)

Parameters:

  • options - Configuration options for the profiler instance

Options:

Property Type Default Description
tracks object undefined Custom track configurations merged with defaults
prefix string undefined Prefix for all measurement names
track string undefined Default track name for measurements
trackGroup string undefined Default track group for organization
color string undefined Default color for track entries
enabled boolean env var Whether profiling is enabled (defaults to CP_PROFILING env var)

Environment Variables

  • CP_PROFILING - Enables or disables profiling globally (boolean)
# Enable profiling in development
CP_PROFILING=true npm run dev

# Disable profiling in production
CP_PROFILING=false npm run build

API Methods

The profiler provides several methods for different types of performance measurements:

Synchronous measurements

profiler.measure<R>(event: string, work: () => R, options?: MeasureOptions<R>): R

Measures the execution time of a synchronous operation. Creates performance start/end marks and a final measure with Chrome DevTools Extensibility API payloads.

const result = profiler.measure(
  'file-processing',
  () => {
    return fs.readFileSync('large-file.txt', 'utf8');
  },
  {
    track: 'io-operations',
    color: 'warning',
  },
);

Asynchronous measurements

profiler.measureAsync<R>(event: string, work: () => Promise<R>, options?: MeasureOptions<R>): Promise<R>

Measures the execution time of an asynchronous operation.

const data = await profiler.measureAsync(
  'api-request',
  async () => {
    const response = await fetch('/api/data');
    return response.json();
  },
  {
    track: 'network',
    trackGroup: 'external',
  },
);

Performance markers

profiler.marker(name: string, options?: EntryMeta & { color?: DevToolsColor }): void

Creates a performance mark with Chrome DevTools marker visualization. Markers appear as vertical lines spanning all tracks and can include custom metadata.

profiler.marker('user-action', {
  color: 'secondary',
  tooltipText: 'User clicked save button',
  properties: [
    ['action', 'save'],
    ['elementId', 'save-btn'],
  ],
});

Runtime control

profiler.setEnabled(enabled: boolean): void
profiler.isEnabled(): boolean

Control profiling at runtime and check current status.

// Disable profiling temporarily
profiler.setEnabled(false);

// Check if profiling is active
if (profiler.isEnabled()) {
  console.log('Performance monitoring is active');
}

Examples

Basic usage

import { Profiler } from '@code-pushup/utils';

const profiler = new Profiler({
  prefix: 'cp',
  track: 'CLI',
  trackGroup: 'Code Pushup',
  color: 'primary-dark',
  tracks: {
    utils: { track: 'Utils', color: 'primary' },
    core: { track: 'Core', color: 'primary-light' },
  },
  enabled: true,
});

// Simple measurement
const result = profiler.measure('data-transform', () => {
  return transformData(input);
});

// Async measurement with custom options
const data = await profiler.measureAsync(
  'fetch-user',
  async () => {
    return await api.getUser(userId);
  },
  {
    track: 'api',
    color: 'info',
  },
);

// Add a marker for important events
profiler.marker('user-login', {
  tooltipText: 'User authentication completed',
});

Custom tracks

Define custom track configurations for better organization:

interface AppTracks {
  api: ActionTrackEntryPayload;
  db: ActionTrackEntryPayload;
  cache: ActionTrackEntryPayload;
}

const profiler = new Profiler<AppTracks>({
  tracks: {
    api: { track: 'api', trackGroup: 'network', color: 'primary' },
    db: { track: 'database', trackGroup: 'data', color: 'warning' },
    cache: { track: 'cache', trackGroup: 'data', color: 'success' },
  },
});

// Use predefined tracks
const users = await profiler.measureAsync('fetch-users', fetchUsers, {
  track: 'api',
});

const saved = profiler.measure('save-user', () => saveToDb(user), {
  track: 'db',
});

Resources