How to Monitor Apache Maka Performance: A Complete Guide to the CDP-Based Profiling Harness

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 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:

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:

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:

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:

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:

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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}