Turn glibc Memory Profiles into PNG Graphs with memusagestat

Staring at raw memusage numbers tells you less than a picture, and memusagestat turns a glibc memory-profiling data file into a PNG graph. You can add a time axis, a total-memory line and explicit dimensions. Allow about ten minutes if the data file already exists. You need a Linux shell, a readable file produced by memusage with its -d or --data option, and a working memusagestat installation.

1. Check the local manual and input file

Start by checking which implementation you've got and whether the input is even readable. The installed manual here is Linux man-pages 6.7, dated 31 October 2023. The local package database reports glibc 2.39, but the memusagestat executable itself is not installed in this environment, so the command shapes below are checked against the manual while your own machine still has to supply the binary.

$ man memusagestat
$ command -v memusagestat
/usr/bin/memusagestat
$ test -r /path/to/profile.data && echo 'profile is readable'
profile is readable

Replace /path/to/profile.data with the real file. If command -v prints nothing, install the package that supplies the glibc memory diagnostic tools through your normal distribution process. There's no need for sudo just to read a profile in your own directory.

2. Generate a basic graph with an explicit output path

Use -o to name the PNG explicitly. That avoids guessing where an omitted output name lands and makes the command easier to audit later. The input is the data file produced by memusage, not a source file or a live process ID.

$ memusagestat -o /tmp/memory-profile.png /path/to/profile.data

The program creates a PNG containing the profile: the red line is heap usage (allocated memory), the green line is stack usage. Unless you ask for time on the horizontal axis, the x-scale is the number of memory-handling function calls.

Check the result without opening an untrusted file in a graphical application:

$ file /tmp/memory-profile.png
/tmp/memory-profile.png: PNG image data, ...
$ test -s /tmp/memory-profile.png && echo 'PNG is non-empty'
PNG is non-empty

The exact wording from file varies. The checkpoint that matters is a non-empty result identified as PNG. If the command fails, preserve the original data file and read the error before trying different options.

3. Make the horizontal axis represent time

Function-call count is fine for comparing allocation activity, but it hides pauses and changes in workload duration. Add -t when elapsed profiling time is the more meaningful x-axis:

$ memusagestat -t -o /tmp/memory-profile-time.png /path/to/profile.data
$ file /tmp/memory-profile-time.png
/tmp/memory-profile-time.png: PNG image data, ...

This only changes the graph's x-scale; it doesn't convert an arbitrary log into a time series, so the input still has to be a valid memory profile from the matching glibc tooling. Compare like with like: switching from call count to time changes what the horizontal distance actually means.

4. Add total consumption and a useful title

Use -T to draw total memory consumption alongside the heap and stack lines, and -s to put a title inside the graph. Quote the title so the spaces stay part of one argument:

$ memusagestat -t -T \
    -s 'worker run, time axis' \
    -o /tmp/worker-memory.png \
    /path/to/profile.data

Keep the title short enough to stay legible. It's annotation, not a record of which program produced the data, so keep the original data file and note that context alongside the PNG separately.

5. Set the graph dimensions deliberately

The installed manual doesn't specify a default size. If the image is going into a report or being compared against other graphs, set both dimensions rather than trust an implementation default. The values are pixel dimensions:

$ memusagestat -x 1600 -y 900 \
    -o /tmp/memory-profile-large.png \
    /path/to/profile.data
$ file /tmp/memory-profile-large.png
/tmp/memory-profile-large.png: PNG image data, ...

A larger canvas doesn't add information: it changes the output image size while the profile data and plotted measurements stay the same. If a viewer or report has a fixed layout, choose dimensions that fit it and check the resulting file before replacing an older graph.

6. Avoid overwriting a graph you may need

The output option points at a file path. Treat an existing destination as valuable evidence until the new graph has passed inspection: write to a new temporary name first, then replace the old file only after verification:

$ memusagestat -t -T \
    -o /tmp/memory-profile.png.new \
    /path/to/profile.data
$ test -s /tmp/memory-profile.png.new
$ file /tmp/memory-profile.png.new
/tmp/memory-profile.png.new: PNG image data, ...
$ mv /tmp/memory-profile.png.new /tmp/memory-profile.png

7. Match failures to the right layer

A missing input error is a path or permission problem. Check it without changing anything:

$ ls -l /path/to/profile.data
$ test -r /path/to/profile.data && echo readable

A missing output usually means the command isn't installed or the destination directory isn't writable. Check the command and directory separately:

$ command -v memusagestat
$ test -w /tmp && echo 'output directory is writable'

A graph that's valid PNG but misleading almost always points back at the profiling stage: the profile may have been generated with the wrong data-file choice, or the x-axis may not match the question you're asking. Re-run the producer and graphing steps with a fresh output name rather than editing the PNG by hand. Save elevated privileges for the separate case where the input or destination is deliberately protected; sudo does nothing to repair a malformed profile.