Native profiling (#892)

Author: marcins

.changeset/weak-beds-happen.md

@@ -0,0 +1,9 @@
+---
+'@atlaspack/types-internal': minor
+'@atlaspack/profiler': minor
+'@atlaspack/utils': minor
+'@atlaspack/core': minor
+'@atlaspack/cli': minor
+---
+
+Added a new `shouldProfileNative` option that provides a way to pause and connect a native profiler to Atlaspack.

docs/Atlaspack-API/Configuration-Guide.md

@@ -63,6 +63,7 @@ interface InitialAtlaspackOptions {
   shouldAutoInstall?: boolean;
   logLevel?: LogLevel;
   shouldProfile?: boolean;
+  nativeProfiler?: 'instruments' | 'samply';
   shouldTrace?: boolean;
   shouldPatchConsole?: boolean;
   additionalReporters?: Array<{
@@ -681,6 +682,42 @@ const atlaspack = new Atlaspack({
 });
 ```
 
+### `nativeProfiler`
+
+**Type**: `'instruments' | 'samply' | undefined`
+
+**Default**: `undefined`
+
+**Description**: Enable native build profiling. When enabled, Atlaspack will display a banner with the PID and command to run the profiler. The profiler type can be:
+
+- `'instruments'` - Use Instruments (macOS only, uses `xcrun xctrace`)
+- `'samply'` - Use samply profiler (cross-platform)
+
+If `--profile-native` is provided on the CLI without a profiler name, defaults to `'samply'`.
+
+**Examples**:
+
+```javascript
+// Enable native profiling with instruments (macOS)
+const atlaspack = new Atlaspack({
+  entries: ['src/index.html'],
+  nativeProfiler: 'instruments',
+});
+
+// Enable native profiling with samply
+const atlaspack = new Atlaspack({
+  entries: ['src/index.html'],
+  nativeProfiler: 'samply',
+});
+
+// Environment-based native profiling
+const atlaspack = new Atlaspack({
+  entries: ['src/index.html'],
+  nativeProfiler:
+    process.env.NATIVE_PROFILE === 'samply' ? 'samply' : 'instruments',
+});
+```
+
 ### `shouldTrace`
 
 **Type**: `boolean`

docs/cli/build-commands.md

@@ -16,6 +16,7 @@ These options are available for `atlaspack serve`, `atlaspack watch`, and `atlas
 - `--dist-dir <dir>` - Output directory when unspecified by targets
 - `--no-autoinstall` - Disable autoinstall
 - `--profile` - Enable sampling build profiling
+- `--profile-native [instruments|samply]` - Enable native build profiling (defaults to samply if no profiler name is provided)
 - `--trace` - Enable build tracing
 - `-V, --version` - Output the version number
 - `--detailed-report [count]` - Print asset timings and sizes in the build report

packages/core/cli/src/normalizeOptions.ts

@@ -6,6 +6,7 @@ import type {FeatureFlags} from '@atlaspack/feature-flags';
 import type {InitialAtlaspackOptions, LogLevel} from '@atlaspack/types';
 import {INTERNAL_ORIGINAL_CONSOLE} from '@atlaspack/logger';
 import path from 'path';
+import os from 'os';
 
 function parsePort(portValue: string): number {
   let parsedPort = Number(portValue);
@@ -47,6 +48,7 @@ export interface Options {
   config?: string;
   logLevel?: LogLevel;
   profile?: boolean;
+  profileNative?: string | boolean;
   contentHash?: boolean;
   featureFlag?: Partial<FeatureFlags>;
   optimize?: boolean;
@@ -175,6 +177,22 @@ export async function normalizeOptions(
     return input.split(',').map((value) => value.trim());
   };
 
+  let nativeProfiler: 'instruments' | 'samply' | undefined;
+  if (typeof command.profileNative === 'string') {
+    if (
+      command.profileNative === 'instruments' ||
+      command.profileNative === 'samply'
+    ) {
+      nativeProfiler = command.profileNative as 'instruments' | 'samply';
+    } else {
+      nativeProfiler = undefined;
+    }
+  } else if (command.profileNative) {
+    nativeProfiler = os.platform() === 'darwin' ? 'instruments' : 'samply';
+  } else {
+    nativeProfiler = undefined;
+  }
+
   return {
     shouldDisableCache: command.cache === false,
     cacheDir: command.cacheDir,
@@ -192,6 +210,7 @@ export async function normalizeOptions(
     shouldAutoInstall: command.autoinstall ?? true,
     logLevel: command.logLevel,
     shouldProfile: command.profile,
+    nativeProfiler,
     shouldTrace: command.trace,
     shouldBuildLazily: typeof command.lazy !== 'undefined',
     lazyIncludes: normalizeIncludeExcludeList(command.lazy),

packages/core/cli/src/options.ts

@@ -60,6 +60,8 @@ export const commonOptions: OptionsDefinition = {
     'output directory to write to when unspecified by targets',
   '--no-autoinstall': 'disable autoinstall',
   '--profile': 'enable sampling build profiling',
+  '--profile-native [instruments|samply]':
+    'enable native build profiling (defaults to instruments on macOS, samply otherwise)',
   '--trace': 'enable build tracing',
   '-V, --version': 'output the version number',
   '--detailed-report [count]': [

packages/core/core/src/Atlaspack.ts

@@ -57,7 +57,7 @@ import {
   toProjectPath,
   fromProjectPathRelative,
 } from './projectPath';
-import {tracer} from '@atlaspack/profiler';
+import {tracer, NativeProfiler} from '@atlaspack/profiler';
 import {setFeatureFlags, DEFAULT_FEATURE_FLAGS} from '@atlaspack/feature-flags';
 import {AtlaspackV3, FileSystemV3} from './atlaspack-v3';
 import createAssetGraphRequestJS from './requests/AssetGraphRequest';
@@ -407,6 +407,10 @@ export default class Atlaspack {
       if (options.shouldProfile) {
         await this.startProfiling();
       }
+      if (options.nativeProfiler) {
+        const nativeProfiler = new NativeProfiler();
+        await nativeProfiler.startProfiling(options.nativeProfiler);
+      }
       if (options.shouldTrace) {
         tracer.enable();
         // We need to ensure the tracer is disabled when Atlaspack is disposed as it is a module level object.

packages/core/core/src/resolveOptions.ts

@@ -269,6 +269,7 @@ export default async function resolveOptions(
       : false,
     shouldDisableCache: initialOptions.shouldDisableCache ?? false,
     shouldProfile: initialOptions.shouldProfile ?? false,
+    nativeProfiler: initialOptions.nativeProfiler,
     shouldTrace: initialOptions.shouldTrace ?? false,
     cacheDir,
     watchDir,

packages/core/core/src/types.ts

@@ -335,6 +335,7 @@ export type AtlaspackOptions = {
   logLevel: LogLevel;
   projectRoot: FilePath;
   shouldProfile: boolean;
+  nativeProfiler: 'instruments' | 'samply' | undefined;
   shouldTrace: boolean;
   shouldPatchConsole: boolean;
   detailedReport?: DetailedReportOptions | null | undefined;

packages/core/profiler/package.json

@@ -23,6 +23,9 @@
     "@atlaspack/diagnostic": "2.14.4",
     "@atlaspack/events": "2.14.4",
     "@atlaspack/types-internal": "2.20.8",
+    "@atlaspack/logger": "2.14.30",
+    "@atlaspack/utils": "3.1.2",
+    "chalk": "^4.1.2",
     "chrome-trace-event": "^1.0.2"
   },
   "type": "commonjs"