bloomberg / bloomberg/memray

Stabilize temporal allocation records as a public API

Open
#997 0 comments 0 reactions 0 assignees View on GitHub
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?

This is a narrower follow-up to #637. `FileReader.get_temporal_allocation_records()` already exposes the allocation lifetime data used by the temporal flamegraph, and `TemporalAllocationRecord` and `Interval` are declared in `_memray.pyi`. However, the temporal interface is not documented in the public API documentation, and its record types are not exported from the top-level `memray` namespace.

As a result, users who want machine-readable temporal allocation data cannot tell whether this interface is intended to be supported or whether they must depend on private implementation details or parse the generated HTML reports.

### Describe the solution you'd like

Clarify and stabilize the existing temporal allocation interface as a supported public API, without changing the capture format or introducing a new indexing engine.

A narrow first version could include:

- documenting `FileReader.get_temporal_allocation_records()` and the semantics of its snapshot intervals;
- exposing `TemporalAllocationRecord` and `Interval` through an approved public import path, or defining another public representation if that is preferred;
- documenting `merge_threads`, open-ended lifetimes, and the relationship between interval indices and memory snapshots; and
- adding tests that treat the machine-readable temporal records as a supported interface and validate them against the data consumed by the existing temporal flamegraph.

Would you prefer to stabilize the existing record classes directly, or introduce a separate documented wrapper or result type? I would be happy to implement the narrower approach you prefer, including type declarations, API documentation, and regression tests.

This proposal intentionally does not include persistent indexes, a new capture format, module or function grouping, or a higher-level query engine. Those could be considered separately after the underlying temporal data interface is supported.

### Alternatives you considered

Users can currently call the existing method and rely on types from `memray._memray`, but that depends on an underscored implementation module and undocumented semantics. Parsing temporal flamegraph HTML is another workaround, but it couples downstream analysis to a presentation format. Implementing the broader analysis API proposed in #637 all at once would address more use cases, but would require substantially more API and architectural design than this narrower first step.

Contributor guide

Open the contributing guide

Research direction

Start with FileReader.get_temporal_allocation_records(), the declarations in _memray.pyi, and the existing temporal flamegraph consumer. Determine whether the existing record classes or a documented wrapper should be public, then trace the interval and snapshot semantics, merge_threads, and open-ended lifetimes. Done means documented public access, type declarations, and regression tests validating the records against the flamegraph data.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, documentation, testing
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.