# How to Monitor Apache Maka Performance: A Complete Guide to the CDP-Based Profiling Harness > Learn to monitor Apache Maka performance using its CDP-based profiling harness. Collect key metrics like React commit counts and JS self-time for deeper insights. - Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka) - Tags: performance - Published: 2026-09-13 --- **Apache Maka provides a Chrome DevTools Protocol (CDP) based performance monitoring harness in `scripts/perf` that attaches to running Desktop instances to collect React commit counts, busy-JS self-time, and geometry layout timings through lightweight probe scripts.** The `apache/maka` repository includes a sophisticated profiling system designed for pinpoint diagnostics of UI interactions. Located in the `scripts/perf` directory, this harness enables developers to monitor Apache Maka performance by injecting probes into a live Electron/Chromium process via remote debugging connections. ## Understanding the Performance Monitoring Architecture The monitoring system consists of three coordinated components that work together to capture telemetry without contaminating runtime measurements. ### The CDP Client (`cdp-client.mjs`) At the core of the harness, `scripts/perf/cdp-client.mjs` establishes a WebSocket connection to the target Desktop instance. This client enables remote-debugging commands such as `Input.dispatchMouseEvent` and `Runtime.evaluate`, allowing Node.js drivers to control application state programmatically during measurement sessions. ### In-Page Probe Helpers Tiny instrumentation scripts injected into the page context capture specific metrics. The [`react-commit-probe.js`](https://github.com/apache/maka/blob/main/react-commit-probe.js) instruments React to count component commits, while `geometry-ablation.mjs` captures renderer geometry data. These helpers expose a global `__MAKA_PROBE__` object that the Node driver can arm and disarm via `globalThis` flags, ensuring probe overhead does not affect baseline measurements. ### Node.js Driver Scripts The orchestration layer resides in `session-switch-commits.mjs`, `session-switch-busy-js.mjs`, `geometry-ablation.mjs`, and `report.mjs`. These drivers manage the measurement workflow, invoke the CDP client, control the probe lifecycle, and aggregate raw samples into JSON or Markdown reports. ## Running Performance Probes in Apache Maka To monitor Apache Maka performance effectively, you must execute probes against a live Desktop instance with remote debugging enabled. ### Prerequisites: Enable Remote Debugging First, launch the Desktop application with the remote debugging port exposed: ```bash npm run dev -w @maka/desktop -- --remote-debugging-port=9334 ``` This starts the Electron/Chromium process on port 9334, allowing `cdp-client.mjs` to attach and dispatch commands. ### Measure React Commit Counts To quantify the rendering cost of session switches, execute the commit probe with a baseline argument: ```bash node scripts/perf/session-switch-commits.mjs before ``` This command captures React commit counts per session switch, recording the "before" configuration for later comparison. ### Capture Busy-JS Self-Time For JavaScript execution profiling during session transitions, run the busy-JS probe: ```bash node scripts/perf/session-switch-busy-js.mjs ``` This script isolates self-time for JavaScript execution during the switch operation, helping identify synchronous blocking code. ### Geometry Layout Workloads To measure layout calculation costs during geometry navigation, execute the geometry ablation probe with stability assertions: ```bash GEOMETRY_REPETITIONS=3 node scripts/perf/geometry-ablation.mjs --assert-stable ``` The `GEOMETRY_REPETITIONS` environment variable controls iterations (defaulting to 3), while `--assert-stable` validates measurement consistency across runs. ### Generate Consolidated Reports Aggregate individual probe outputs into human-readable Markdown reports: ```bash node scripts/perf/report.mjs frontend-geometry-ablation.json > performance-report.md ``` ## Design Principles and Constraints The Apache Maka performance harness follows specific constraints that dictate how measurements must be interpreted: - **Ad-hoc diagnostics**: Scripts target specific interactions like session switches or scroll operations rather than serving as a continuous regression test suite. - **Single-instance measurement**: Only compare numbers captured within the same running process. Restarting the app creates a new runtime environment that invalidates direct numerical comparisons. - **Explicit repeatability**: Each probe runs multiple repetitions with a global flag toggle (`globalThis.__MAKA_PROBE__`) to alternate configurations without rebuilding the application. - **CI integration**: GitHub Actions execute these scripts in `Performance frontend` and `Performance protocol` jobs to produce reproducible artifacts for automated regression detection. ## Automating Performance Monitoring in CI The same probe scripts used in local development execute within GitHub Actions workflows. As documented in [`scripts/perf/CI.md`](https://github.com/apache/maka/blob/main/scripts/perf/CI.md), the `Performance frontend` and `Performance protocol` jobs start the Desktop with remote debugging enabled, invoke the Node.js drivers, and archive JSON reports for every pull request. This integration ensures code changes are evaluated against baseline metrics captured under identical runtime conditions. ## Summary - **Apache Maka performance monitoring** relies on a CDP-based harness in `scripts/perf` that attaches to running Desktop instances via WebSocket connections managed by `cdp-client.mjs`. - **Probe scripts** like `session-switch-commits.mjs` and `geometry-ablation.mjs` measure React commits, busy-JS self-time, and layout calculations through the global `__MAKA_PROBE__` instrumentation interface. - **Single-process measurement** is mandatory—never compare metrics collected across different application launches due to runtime variability in JavaScript engine states. - **CI automation** uses identical scripts in GitHub Actions workflows, enabling reproducible performance regression detection for every code change. ## Frequently Asked Questions ### What is the Chrome DevTools Protocol (CDP) used for in Apache Maka performance monitoring? The CDP provides the communication layer between Node.js probe drivers and the running Electron/Chromium Desktop instance. As implemented in `scripts/perf/cdp-client.mjs`, it enables remote execution of browser commands, event dispatching, and runtime evaluation necessary to control UI state and extract performance metrics programmatically. ### Why can't I compare performance numbers from different app launches? Apache Maka's timing characteristics vary significantly between process lifecycles due to JavaScript engine warm-up, cache states, and garbage collection patterns. The harness enforces single-instance measurement rules because restarting the app creates a new runtime environment that invalidates direct numerical comparison with previous sessions. ### How do I enable remote debugging for Apache Maka Desktop? Launch the application with the `--remote-debugging-port=9334` flag passed through the npm script: `npm run dev -w @maka/desktop -- --remote-debugging-port=9334`. This exposes the CDP WebSocket endpoint that `cdp-client.mjs` requires to attach probes and control the browser instance. ### Can I integrate Apache Maka performance probes into my CI pipeline? Yes. The repository includes GitHub Actions jobs (`Performance frontend` and `Performance protocol`) that execute the same probe scripts used locally. Configure your CI environment to start the Desktop with remote debugging enabled, then invoke the Node.js drivers to capture metrics and generate reports automatically for every pull request.