heapprof: A Logging Heap Profiler

heapprof is a logging, sampling heap profiler for Python 3.7+.

• “Logging” means that as the program runs, it steadily generates a log of memory allocation and release events. This means that you can easily look at memory usage as a function of time.

• “Sampling” means that it can record only a statistically random sample of memory events. This improves performance dramatically while writing logs, and (with the right parameters) sacrifices almost no accuracy.

It comes with a suite of visualization and analysis tools (including time plots, flame graphs, and flow graphs), as well as an API for doing your own analyses of the results.

heapprof is complementary to tracemalloc, which is a snapshotting heap profiler. The difference is that tracemalloc keeps track of live memory internally, and only writes snapshots when its snapshot() function is called; this means it has slightly lower overhead, but you have to know the moments at which you’ll want a snapshot before the program starts. This makes it particularly useful for finding leaks (from the snapshot at program exit), but not as good for understanding events like memory spikes.

Contents:

• heapprof quickstart
• Using heapprof
  • Installation and system requirements
  • Running your code
  • Making a digest
• Visualizing and interpreting results
  • Time Plots
  • Flow Graphs
  • Flame Graphs
  • API Access to Data
• Advanced heapprof
  • Controlling Sampling
• The heapprof API
  • The top-level heapprof package
  • heapprof.reader: The high-level API
  • heapprof.types: Common definitions
  • heapprof.flow_graph: The FlowGraph class
  • heapprof.lowlevel: The low-level API
• Contributing to heapprof
  • Code of Conduct
  • Desiderata
• MIT License