# DevTools — Performance

Canonical page: https://www.adaptabletools.com/docs/dev-guide-support-devtools-performance

- **Performance** is the profiling section in [AdapTable DevTools](https://www.adaptabletools.com/docs/dev-guide-support-devtools/index.md) for the selected Grid instance
- One recording at a time — **Record** controls above five tabs: **Overview**, **Hot Paths**, **Timeline**, **Advisor**, and **Memory**
- Use it to see what is slow and why, and what to change — without adding diagnostic code

- The Performance section is not available in versions earlier than AdapTable v24.0.2
- Set `localStorage.adaptableProfileTracks = 'true'`, reload and record in the [Chrome Performance panel](https://www.adaptabletools.com/docs/dev-guide-support-profiling/index.md) instead

## Topics on this Page

| Topic                                             | Summary                                                 |
| ------------------------------------------------- | ------------------------------------------------------- |
| [Open Performance](#open-performance)             | AdapTable tab → Performance                             |
| [Recording Rontrols](#recording-controls)         | Record, Hot Paths, Clear                                |
| [Recording Tabs](#recording-tabs)                 | Overview, Hot Paths, Timeline, Advisor, Memory          |
| [What is Measured](#what-is-measured)             | Start-up timings, recording scope, State timeline pause |
| [Support Exports](#support-exports)               | Advisor and memory exports for tickets                  |
| [Heap Snapshot Analysis](#heap-snapshot-analysis) | Real sizes from a `.heapsnapshot` file                  |

## Open Performance

### Performance

Choose the correct **`adaptableId`** in the DevTools header.

In the **AdapTable** tab, select the **Performance** section.

## Recording controls

- Nothing is measured until you record (except the start-up timings), like the Chrome Performance panel
- There is one recording, and its controls sit once, above the 5 tabs

There are 5 recording controls provided:

### Record

This measures until you click **Stop**, and includes:
- AdapTable operations (Layout changes, column model refreshes, Redux actions)
- long animation frames
- memory (the JS heap every 2 seconds and the size of AdapTable's structures about every 30 seconds)
- every cell callback (with **Hot Paths** ticked)

### Record & Reload

Reloads the page and records from its very start, so the start-up and the first render are included

### Hot Paths

Times every cell style, Display Format, Expression, Calculated Column, filter pass and data change.

It attributes the time to the AdapTable object that caused it

This makes the other timings slightly higher, so untick it to time operations alone

This is ticked by default

### Keep Recording after Close

This is used for long unattended runs, e.g. to watch memory for hours.

Without it a recording stops about 10 seconds after DevTools is closed, so a forgotten one does not keep slowing the page. 

It can be ticked or unticked while the recording runs.

This is not ticked by default.

### Clear

This drops the recording results (i.e. the start-up timings stay)

- While recording, AdapTable's operations are also written to Chrome Performance panel as "AdapTable" track group
- This means that a Chrome recording made at the same time shows them (see [Profiling](https://www.adaptabletools.com/docs/dev-guide-support-profiling/index.md))

## Recording Tabs

The 5 tabs show the last recording:

| Tab                            | What it Shows                                                                                                                                                                                                                                                                                                                                                          |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Overview**  | Start-up timings, the slowest operations, long frames and the JS heap                                                                                                                                                                                                                                                                                                  |
| **Hot Paths** | Where the time went, per cell callback and per AdapTable object (Format Column, Alert, Calculated Column, filter), with the data change rates (cell changes, re-filters and flashes per second)                                                                                                                                                                        |
| **Timeline**  | The AdapTable operations (start-up, Layout changes, column model refreshes, Redux actions) and long animation frames (over 50 ms), each with the scripts and AdapTable operations that ran in it                                                                                                                                                                       |
| **Advisor**   | Checks the live configuration against what is known to cost performance (e.g. Quick Search filtering without AG Grid's Quick Filter Cache, Data Change History without a limit, Badges on flashing columns) and explains what to change; see [Performance Advisor rules](https://www.adaptabletools.com/docs/dev-guide-support-adaptable-performance/index.md#performance-advisor-rules) |
| **Memory**    | The JS heap for the whole recording, the size of AdapTable's structures (State sections, Data Change History, expression caches, ...) as the recording last read them and how each changed since it started, and the real sizes from a heap snapshot. Without a recording, **Refresh** reads the sizes now                                                             |

The tabs show what is going on for the selected Grid, whichever tab is open: a red dot on **Performance** while a recording runs, a pause icon on **State** while the timeline is paused.

## What is Measured

What is measured depends on what you ask for, so DevTools never slows the Grid down unasked:

- Start-up timings are always kept (4 timings per page load, taken before DevTools can ask for anything)
- Everything else only during a recording; while nothing records, each timed spot in AdapTable checks one number and does nothing else
- A recording started from DevTools stops by itself about 10 seconds after DevTools is closed, unless **Keep recording when DevTools closes** is ticked
- Reading the size of AdapTable's structures is DevTools' own work: it runs between AdapTable's operations, so it is not part of their timings or of Hot Paths, and the Memory tab shows what it cost. When a read is slow, the recording reads less often
- A recording keeps the JS heap for its whole run, however long: after 20 minutes it merges neighbouring readings, keeping the lowest and highest of each. Operations and long frames are counted for the whole run, and the newest 500 operations and 200 long frames are listed
- The State timeline is paused for the Grid while a recording runs (see [DevTools — Manage State](https://www.adaptabletools.com/docs/dev-guide-support-devtools-manage-state/index.md#state-timeline)), so a long recording leaves a gap in it

## Support Exports

- Both the Advisor report and the heap snapshot summary can be downloaded for a support ticket
- They hold versions, counts, timings and object names, but no row data

## Heap Snapshot Analysis

The Memory tab can break a heap snapshot down by AdapTable structure:

1. Open the **Memory** tab: AdapTable tags its structures with weak references, which change no size
2. In Chrome DevTools open **Memory**, choose **Heap snapshot** and click **Take snapshot** (the page pauses while it is taken)
3. Save the snapshot and drop the `.heapsnapshot` file onto the Memory tab

It shows how much AdapTable keeps alive (and its share of the page's heap) and, for every structure, its size and what would be freed if it went away.

- The file is analysed in the browser and never uploaded
- Large snapshots need about twice their size in memory to analyse

### FAQ

**Performance vs the Profiling handbook?**
Use this section for AdapTable-linked timings, Hot Paths, Advisor, and structure sizes on a live Grid. Use [Profiling](https://www.adaptabletools.com/docs/dev-guide-support-profiling/index.md) when you need Chrome Performance tracks alone or AdapTable on an older version.

**Can I record without the extension UI?**
Yes — `startPerfRecording`, `getPerfData`, and `getPerformanceContext` on the [DevTools In-page API](https://www.adaptabletools.com/docs/dev-guide-support-devtools-api/index.md).
