bloomberg / bloomberg/memray

Flamegraph report: add buttons to jump to peak RSS or peak memory usage

Open
#954 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
15.2k
Forks
461
Avg merge
5d 3h
Merged PRs (30d)
10

Description

### Is there an existing proposal for this?

- [x] I have searched the existing proposals

### Is your feature request related to a problem?

A common use case for memray is to understand the allocations that contribute to _peak_ heap usage or peak RSS. Application developers may want to diagnose and ultimately reduce peak RSS or peak heap usage, so that their programs can run under a certain memory threshold.

When examining a temporal flamegraph, it can be difficult to "manually" locate the peak RSS usage, especially if the scale of the RSS timeseries is much smaller than the scale of the heap size.

Image

The documentation for [temporal flamegraphs](https://bloomberg.github.io/memray/flamegraph.html#temporal-flame-graphs) says (emphasis added):
> These temporal reports can be used to gain fine grained insight into how your process was using memory **at any point** during its run, which can be invaluable for understanding its memory usage patterns.

In practice, many users care about how the process was using memory _at peak usage_, rather than "any point".

### Describe the solution you'd like

It would be very helpful if the HTML report provided buttons like "Zoom to peak RSS" and "Zoom to peak heap." Each button would set the focused interval (i.e. would move the sliders that control which allocations are displayed) to an interval containing the peak RSS or heap usage, respectively.

There are some decisions that would need to be made to implement this feature.
* The initial duration of the focused interval: minimal (i.e. measurement granularity of ~10 milliseconds), a fixed duration like X milliseconds, or a fraction of the overall run?
* How to handle cases where heap usage or RSS reaches a maximal value at multiple timestamps? For _contiguous_ maximal values, it could expand the focused interval to cover the maximal values; for _non-contiguous_ values, the button could arbitrarily choose the first or last, or cycle through all.

A more general version of this feature would be a button to cycle through _peaks_ in heap usage or RSS. The [documentation of `scipy.find_peaks()`](https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.find_peaks.html) illustrates the kinds of parameters that could be specified to identify peaks, although I'm not sure if one universal set of parameters would be "good enough" for general use.

### Alternatives you considered

Currently, non-temporal flamegraph shows allocations at the peak heap usage. One alternative could be to add a flag like `--peak-rss` to the non-temporal flamegraph that instead focuses on the moment of peak RSS.

Contributor guide

Open the contributing guide

Research direction

Start by locating the temporal flamegraph HTML report and the existing sliders that control the focused interval. Determine how peak RSS and peak heap values are represented, then define button behavior for ties and interval duration; done means the report can focus on each requested peak reliably.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
frontend, web-dev
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.