Performance: measureUserAgentSpecificMemory() method
====================================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`measureUserAgentSpecificMemory()`** method is used to estimate the memory usage of a web application including all its iframes and workers.

Description
-----------

The browser automatically allocates memory when objects are created and frees it when they are not reachable anymore (garbage collection). This garbage collection (GC) is an approximation since the general problem of determining whether or not a specific piece of memory is still needed is impossible (see also JavaScript Memory Management). Developers need to make sure that objects are garbage collected, memory isn't leaked, and memory usage doesn't grow unnecessarily over time leading to slow and unresponsive web applications. Memory leaks are typically introduced by forgetting to unregister an event listener, not closing a worker, accumulating objects in arrays, and more.

The `measureUserAgentSpecificMemory()` API aggregates memory usage data to help you find memory leaks. It can be used for memory regression detection or for A/B testing features to evaluate their memory impact. Rather than make single calls to this method, it's better to make periodic calls to track how memory usage changes over the duration of a session.

The `byte` values this API returns aren't comparable across browsers or between different versions of the same browser as these are highly implementation dependent. Also, how `breakdown` and `attribution` arrays are provided is up to the browser as well. It is best to not hardcode any assumptions about this data. This API is rather meant to be called periodically (with a randomized interval) to aggregate data and analyze the difference between the samples.

Syntax
------


```js
measureUserAgentSpecificMemory()
```

### Parameters

None.

### Return value

A `Promise` that resolves to an object containing the following properties:

`bytes`

A number representing the total memory usage.

`breakdown`

An `Array` of objects partitioning the total `bytes` and providing attribution and type information. The object contains the following properties:

`bytes`

The size of the memory that this entry describes.

`attribution`

An `Array` of container elements of the JavaScript realms that use the memory. This object has the following properties:

`url`

If this attribution corresponds to a same-origin JavaScript realm, then this property contains the realm's URL. Otherwise it is the string "cross-origin-url".

`container`

An object describing the DOM element that contains this JavaScript realm. This object has the following properties:

`id`

The `id` attribute of the container element.

`src`

The `src` attribute of the container element. If the container element is an `<object>` element, then this field contains the value of the `data` attribute.


`scope`

A string describing the type of the same-origin JavaScript realm. Either `"Window"`, `"DedicatedWorkerGlobalScope"`, `"SharedWorkerGlobalScope"`, `"ServiceWorkerGlobalScope"` or `"cross-origin-aggregated"` for the cross-origin case.


`types`

An array of implementation-defined memory types associated with the memory.



An example return value looks like this:


```js
{
  bytes: 1500000,
  breakdown: [
    {
      bytes: 1000000,
      attribution: [
        {
          url: "https://example.com",
          scope: "Window",
        },
      ],
      types: ["DOM", "JS"],
    },
    {
      bytes: 0,
      attribution: [],
      types: [],
    },
    {
      bytes: 500000,
      attribution: [
        {
          url: "https://example.com/iframe.html"
          container: {
            id: "example-id",
            src: "redirect.html?target=iframe.html",
          },
          scope: "Window",
        }
      ],
      types: ["JS", "DOM"],
    },
  ],
}
```

### Exceptions

`SecurityError` `DOMException`

Thrown if the security requirements for preventing cross-origin information leaks aren't fulfilled.

Security requirements
---------------------

Your site needs to be in a secure context.

Two headers need to be set to cross-origin isolate your site:

* `Cross-Origin-Opener-Policy` with `same-origin` as value (protects your origin from attackers)
* `Cross-Origin-Embedder-Policy` with `require-corp` or `credentialless` as value (protects victims from your origin)


```http
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
```


To check if cross origin isolation has been successful, you can test against the `crossOriginIsolated` property available to window and worker contexts:


```js
if (crossOriginIsolated) {
  // Use measureUserAgentSpecificMemory
}
```

Examples
--------

### Monitoring memory usage

The following code shows how to call the `measureUserAgentSpecificMemory()` method once every five minutes at a random interval using Exponential distribution.


```js
function runMemoryMeasurements() {
  const interval = -Math.log(Math.random()) \* 5 \* 60 \* 1000;
  console.log(`Next measurement in ${Math.round(interval / 1000)} seconds.`);
  setTimeout(measureMemory, interval);
}

async function measureMemory() {
  const memorySample = await performance.measureUserAgentSpecificMemory();
  console.log(memorySample);
  runMemoryMeasurements();
}

if (crossOriginIsolated) {
  runMemoryMeasurements();
}
```

Specifications
--------------

| Specification |
| --- |
| Measure Memory API # ref-for-dom-performance-measureuseragentspecificmemory⑤ |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `setTimeout()`
* Monitor your web page's total memory usage with measureUserAgentSpecificMemory() - web.dev