[Proposal] JavaScript agent memory API


The full explainer is available on this github page.

JavaScript agent memory API

We propose adding a measureMemory method to the performance API that estimates the amount of memory used by JavaScript objects of the current JavaScript agent. The proposed API improves upon the existing non-standard performance.memory API in the following ways:

  • better security and privacy: only objects that the current JavaScript agent can access are accounted. No size information leaks from foreign origin contexts and resources;
  • promise-based interface: it allows the implementation to do more work on demand without janking the web page. No overhead for web pages that do not use the API;
  • stable results: other JavaScript agents that happen to share the same heap due to implementation details of the browser do not affect the results;
  • optional support for per-frame memory breakdown of the result;

The proposed API is limited to JavaScript memory, but it can be extended to other memory (DOM, GPU, process) retained by the JavaScript agent in future by adding new fields to the result.


As shown in this collection of use cases there is a need for an API that measures memory footprint of web pages in production. The use cases include a) analysis of correlation between memory usage and user metrics, b) detection of memory regressions, c) evaluation of feature launches in A/B tests, d) memory optimization. Currently web developers resort to the non-standard performance.memory API that is used in 20% of page loads in Chrome.

Related Work

Process memory API

There is a proposal for comprehensive memory measurement API that covers different types of memory: JavaScript, DOM, CSS, Web Workers spawned by the page, etc. Effectively the API measures the memory footprint of the whole OS process. The wide scope of the API is problematic for security because it is difficult to precisely specify what the API is allowed to measure. The proposal is currently blocked by information leak of opaque resources.

In contrast to that our proposal is limited to JavaScript memory of the current JavaScript agent. Note that the two proposals are complementary and can share the same interface. For example, the interface proposed here can be extended to include a processMemory field once the process memory proposal is unblocked in future.

Memory pressure API

There is a proposal for memory pressure API that notifies the application about system memory pressure events. This gives the application an opportunity to change its behavior at runtime to reduce its memory usage if possible e.g. by freeing up caches and unused resources. Our proposal has different use cases such as collecting telemetry data and detecting regressions. Thus the two proposals are orthogonal.

1 Like

The explainer was updated after security feedback to restrict the scope of the API from the whole JavaScript agent to same-origin realms in the JavaScript agent.