feat(tools-performance): add subdomains and a Metro perfLoggerFactory implementation (#4090)

Author: JasonVMo

.changeset/heavy-geese-refuse.md

@@ -0,0 +1,5 @@
+---
+"@rnx-kit/tools-performance": patch
+---
+
+Add subdomain support and metro logging integration

incubator/tools-performance/README.md

@@ -108,6 +108,23 @@ const trace = getTrace("metro");
 const myTrace = someCondition ? customTrace : nullTrace;
 ```
 
+### Manual event timing
+
+Use `startEvent` on a domain to manually control the start and end of a timed
+event. This is useful when start and end points don't wrap a single function
+call:
+
+```typescript
+import { getDomain } from "@rnx-kit/tools-performance";
+
+const domain = getDomain("metro");
+if (domain) {
+  const endEvent = domain.startEvent("resolve");
+  // ... do work across multiple steps ...
+  endEvent(); // records the duration
+}
+```
+
 ### Custom trace functions
 
 Use `createTrace` with a `TraceRecorder` to build trace functions backed by
@@ -172,6 +189,27 @@ trackPerformance({ enable: ["resolve", "transform"] });
 // Calls are additive — all three domains above are now enabled
 ```
 
+### Subdomains
+
+Subdomains create a parent–child relationship between domains. When a parent
+domain is enabled, all its registered subdomains are automatically enabled too.
+This is useful for organizing related operations under a single toggle.
+
+```typescript
+import { registerSubdomain, getDomain } from "@rnx-kit/tools-performance";
+
+// Register "metro:resolver" as a subdomain of "metro"
+registerSubdomain("metro", "resolver");
+
+// Enabling "metro" now also enables "metro:resolver"
+trackPerformance({ enable: "metro", strategy: "timing" });
+
+const domain = getDomain("metro:resolver"); // enabled via parent
+```
+
+Subdomains can be registered before or after the parent is enabled — the
+relationship is resolved in either order.
+
 ### Checking if tracing is enabled
 
 `isTraceEnabled` checks domain and frequency without creating a domain as a
@@ -245,40 +283,74 @@ const table = formatAsTable(
 console.log(table);
 ```
 
+## Metro Integration
+
+`createPerfLoggerFactory` returns a factory compatible with Metro's
+`unstable_perfLoggerFactory` config option. It bridges Metro's performance
+logging into the tools-performance domain system under the `"metro"` parent
+domain.
+
+```typescript
+import {
+  createPerfLoggerFactory,
+  trackPerformance,
+} from "@rnx-kit/tools-performance";
+
+// Enable the metro domain
+trackPerformance({ enable: "metro", strategy: "timing" });
+
+// Pass the factory to Metro config
+module.exports = {
+  unstable_perfLoggerFactory: createPerfLoggerFactory(),
+};
+```
+
+When Metro calls the factory, it creates subdomains like `metro:start_up`,
+`metro:bundling_request`, and `metro:hmr`. Metro's `subSpan` calls create deeper
+subdomains (e.g. `metro:start_up:resolver`). Metro's `point` events with
+`_start`/`_end` suffixes are mapped to timed events via `startEvent`.
+
+When the `"metro"` domain is not enabled, the factory returns no-op loggers with
+zero overhead.
+
 ## API Reference
 
 ### Module-Level Functions
 
-| Function                        | Description                                                             |
-| ------------------------------- | ----------------------------------------------------------------------- |
-| `trackPerformance(config?)`     | Enable tracking. Config controls domains, strategy, and report options. |
-| `getTrace(domain, frequency?)`  | Get a trace function for a domain. Returns `nullTrace` if not enabled.  |
-| `getDomain(name)`               | Get the `PerfDomain` for a domain, or `undefined` if not enabled.       |
-| `isTraceEnabled(domain, freq?)` | Check if tracing is enabled for a domain and optional frequency.        |
-| `reportPerfData()`              | Finish tracking and print the performance report.                       |
+| Function                               | Description                                                             |
+| -------------------------------------- | ----------------------------------------------------------------------- |
+| `trackPerformance(config?)`            | Enable tracking. Config controls domains, strategy, and report options. |
+| `getTrace(domain, frequency?)`         | Get a trace function for a domain. Returns `nullTrace` if not enabled.  |
+| `getDomain(name)`                      | Get the `PerfDomain` for a domain, or `undefined` if not enabled.       |
+| `isTraceEnabled(domain, freq?)`        | Check if tracing is enabled for a domain and optional frequency.        |
+| `registerSubdomain(domain, subdomain)` | Register a subdomain under a parent. Enabled when the parent is.        |
+| `reportPerfData()`                     | Finish tracking and print the performance report.                       |
+| `createPerfLoggerFactory()`            | Create a Metro-compatible `unstable_perfLoggerFactory`.                 |
 
 ### PerfTracker
 
-| Member                     | Description                                                            |
-| -------------------------- | ---------------------------------------------------------------------- |
-| `new PerfTracker(config?)` | Create a new tracker. Auto-registers a process exit handler.           |
-| `enable(domain)`           | Enable tracking for `true` (all), a string, or string array.           |
-| `isEnabled(domain, freq?)` | Check if a domain is enabled, optionally at a given frequency.         |
-| `domain(name)`             | Get or create a `PerfDomain` for an enabled domain.                    |
-| `finish(processExit?)`     | Stop all domains, print the report, and unregister. Only reports once. |
-| `updateConfig(config)`     | Merge new configuration values.                                        |
+| Member                           | Description                                                            |
+| -------------------------------- | ---------------------------------------------------------------------- |
+| `new PerfTracker(config?)`       | Create a new tracker. Auto-registers a process exit handler.           |
+| `enable(domain)`                 | Enable tracking for `true` (all), a string, or string array.           |
+| `isEnabled(domain, freq?)`       | Check if a domain is enabled, optionally at a given frequency.         |
+| `domain(name)`                   | Get or create a `PerfDomain` for an enabled domain.                    |
+| `registerSubdomain(domain, sub)` | Register a subdomain. Enabling the parent enables the subdomain.       |
+| `finish(processExit?)`           | Stop all domains, print the report, and unregister. Only reports once. |
+| `updateConfig(config)`           | Merge new configuration values.                                        |
 
 ### PerfDomain
 
-| Member                 | Description                                                            |
-| ---------------------- | ---------------------------------------------------------------------- |
-| `name`                 | Domain name (readonly).                                                |
-| `strategy`             | Tracing strategy: `"timing"` or `"node"` (readonly).                   |
-| `frequency`            | Current frequency level (mutable).                                     |
-| `start()`              | Begin domain-level timing (called automatically unless `waitOnStart`). |
-| `stop(processExit?)`   | End domain-level timing and clean up marks.                            |
-| `enabled(frequency?)`  | Check if a frequency level is active for this domain.                  |
-| `getTrace(frequency?)` | Get a trace function, or `nullTrace` if frequency is not active.       |
+| Member                   | Description                                                            |
+| ------------------------ | ---------------------------------------------------------------------- |
+| `name`                   | Domain name (readonly).                                                |
+| `strategy`               | Tracing strategy: `"timing"` or `"node"` (readonly).                   |
+| `frequency`              | Current frequency level (mutable).                                     |
+| `start()`                | Begin domain-level timing (called automatically unless `waitOnStart`). |
+| `stop(processExit?)`     | End domain-level timing and clean up marks.                            |
+| `startEvent(tag, freq?)` | Start a timed event. Returns a function to call when the event ends.   |
+| `enabled(frequency?)`    | Check if a frequency level is active for this domain.                  |
+| `getTrace(frequency?)`   | Get a trace function, or `nullTrace` if frequency is not active.       |
 
 ### Trace Primitives
 

incubator/tools-performance/package.json

@@ -17,7 +17,7 @@
     "lib/**/*.d.ts",
     "lib/**/*.js"
   ],
-  "type": "module",
+  "type": "commonjs",
   "sideEffects": false,
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -35,7 +35,8 @@
   },
   "devDependencies": {
     "@rnx-kit/scripts": "*",
-    "@rnx-kit/tsconfig": "*"
+    "@rnx-kit/tsconfig": "*",
+    "metro-config": "^0.83.3"
   },
   "engines": {
     "node": ">=22.11"

incubator/tools-performance/src/domain.ts

@@ -1,4 +1,4 @@
-import { createTrace, nullTrace, nullRecordTime } from "./trace.ts";
+import { createTrace, nullTrace, nullFunction } from "./trace.ts";
 import type { TraceRecorder } from "./trace.ts";
 import type {
   EventFrequency,
@@ -52,6 +52,19 @@ export class PerfDomain {
     return this.enabled(requested) ? this.trace : nullTrace;
   }
 
+  /**
+   * Create a wrapper around an event to be able to manually start and stop the timing/marking.
+   * @param tag The tag for the event
+   * @returns A function that stops the event when called
+   */
+  startEvent(tag: string, frequency?: EventFrequency): () => void {
+    if (!this.enabled(frequency)) {
+      return nullFunction;
+    }
+    const startVal = this.record(tag);
+    return () => this.record(tag, startVal);
+  }
+
   /**
    * Start performance tracking for this namespace. This will be called automatically on creation unless
    * the waitOnStart option is set. Trace events will still work without this but you won't get a boundary
@@ -104,7 +117,7 @@ export class PerfDomain {
     } = options;
     this.frequency = frequency;
     this.strategy = recordTime ? "timing" : "node";
-    this.recordTime = recordTime ?? nullRecordTime;
+    this.recordTime = recordTime ?? nullFunction;
     this.record = recordTime
       ? this.timingRecorder.bind(this)
       : this.markingRecorder.bind(this);

incubator/tools-performance/src/index.ts

@@ -4,6 +4,7 @@ export {
   getDomain,
   getTrace,
   isTrackingEnabled,
+  registerSubdomain,
   reportPerfData,
   trackPerformance,
 } from "./perf.ts";
@@ -24,3 +25,5 @@ export type {
   TraceFunction,
   TraceStrategy,
 } from "./types.ts";
+
+export { createPerfLoggerFactory } from "./metro.ts";

incubator/tools-performance/src/metro.ts

@@ -0,0 +1,93 @@
+import type {
+  PerfAnnotations,
+  PerfLogger,
+  RootPerfLogger,
+  PerfLoggerFactoryOptions,
+  PerfLoggerFactory,
+  PerfLoggerPointOptions,
+} from "metro-config";
+import { type PerfDomain } from "./domain.ts";
+import { getDomain, registerSubdomain } from "./perf.ts";
+import { nullFunction } from "./trace.ts";
+
+function createEmptyLogger(): PerfLogger {
+  return {
+    point: nullFunction,
+    annotate: nullFunction,
+    subSpan: createEmptyLogger,
+  };
+}
+
+// metro uses point events with _start and _end to indicate the start and end of events
+const POINT_START_SUFFIX = "_start";
+const POINT_END_SUFFIX = "_end";
+
+function getSubdomainLogger(
+  base: string,
+  key?: string
+): [PerfLogger, PerfDomain | undefined] {
+  key = key != null ? `:${key}` : "";
+  const subdomain = `${base}${key}`;
+  // register the subdomain to ensure the associations are set up correctly in the tracker
+  registerSubdomain("metro", subdomain);
+  // now get the subdomain itself so we can create a logger for it
+  const domain = getDomain(`metro:${subdomain}`);
+  const logger = createLogger(subdomain, domain);
+  return [logger, domain];
+}
+
+function createLogger(subdomainName: string, domain?: PerfDomain): PerfLogger {
+  if (!domain) {
+    return createEmptyLogger();
+  }
+  const openEvents: Record<string, () => void> = {};
+  return {
+    point(name: string, _opts?: PerfLoggerPointOptions) {
+      if (name.endsWith(POINT_START_SUFFIX)) {
+        const eventKey = name.slice(0, -POINT_START_SUFFIX.length);
+        // this shouldn't happen but close any open event with the same name just in case
+        openEvents[eventKey]?.();
+        // now open the event for this point
+        openEvents[eventKey] = domain.startEvent(eventKey);
+      } else if (name.endsWith(POINT_END_SUFFIX)) {
+        const eventKey = name.slice(0, -POINT_END_SUFFIX.length);
+        const endEvent = openEvents[eventKey];
+        if (endEvent) {
+          endEvent();
+          delete openEvents[eventKey];
+        }
+      }
+    },
+    annotate(_annotations: PerfAnnotations) {
+      // do nothing for annotations
+    },
+    subSpan(label: string): PerfLogger {
+      const [logger] = getSubdomainLogger(subdomainName, label);
+      return logger;
+    },
+  };
+}
+
+/**
+ * Create a PerfLoggerFactory that integrates with tools-performance. This will log events
+ * based on the "metro" domain being enabled.
+ */
+export function createPerfLoggerFactory(): PerfLoggerFactory | undefined {
+  return (
+    type: "START_UP" | "BUNDLING_REQUEST" | "HMR",
+    opts?: PerfLoggerFactoryOptions
+  ): RootPerfLogger => {
+    const keyStr = opts?.key != null ? `#${opts.key}` : undefined;
+    const [logger, domain] = getSubdomainLogger(type.toLowerCase(), keyStr);
+
+    return {
+      ...logger,
+      start(_startOpts) {
+        domain?.start();
+      },
+      end(_status, _endOpts) {
+        domain?.stop();
+      },
+    };
+  };
+}

incubator/tools-performance/src/perf.ts

@@ -52,6 +52,14 @@ export function getDomain(name: string) {
   return defaultManager?.domain(name);
 }
 
+/**
+ * Register a subdomain under a parent domain. This domain will be enabled whenever the parent domain is enabled but can
+ * be enabled or tracked separately as well.
+ */
+export function registerSubdomain(domain: string, subdomain: string) {
+  defaultManager?.registerSubdomain(domain, subdomain);
+}
+
 /**
  * Reset the module-level performance tracker, releasing all domains and state.
  * Intended for test isolation — not part of the public API.

incubator/tools-performance/src/trace.ts

@@ -31,8 +31,8 @@ export function nullPassthrough<T>(value: T): T {
   return value;
 }
 
-/** no-op function matching the recordTime signature */
-export function nullRecordTime(_tag: string, _duration?: number): void {
+/** no-op function taking any number of parameters and doing nothing */
+export function nullFunction(..._args: unknown[]): void {
   // intentionally empty
 }