Turn glibc Memory Profiles into PNG Graphs with memusagestat

You will turn a glibc memory-profiling data file into a PNG graph, with an optional time axis, 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 are using and whether the input is readable. The installed manual on this system is Linux man-pages 6.7, dated 31 October 2023. The glibc package reported by the local package database is 2.39, but the memusagestat executable is not installed in this environment. That means the command shapes below are checked against the installed manual, while your own machine must provide the executable before you can run them.

$ 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. Do not use sudo merely 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. This avoids guessing where an omitted output name will be written and makes the command easier to audit later. The input is the data file produced by memusage; it is not a source file or a live process identifier.

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

The program creates a PNG containing the profile. The red line represents heap usage, meaning allocated memory, and the green line represents stack usage. Unless you request 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. A non-empty result identified as PNG is the useful checkpoint. 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 useful for comparing allocation activity, but it can hide pauses or 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 changes the graph's x-scale. It does not convert an arbitrary log into a time series, so the input must be a valid memory profile generated by the matching glibc tooling. Compare like with like when reviewing two graphs: changing from call count to time changes what the horizontal distance means.

4. Add total consumption and a useful title

Use -T to draw total memory consumption as well as the heap and stack lines. Use -s to put a title inside the graph. Quote the title so spaces remain 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 remain legible. The title is annotation, not a record of which program produced the data, so retain the original data file and record that context alongside the PNG.

5. Set the graph dimensions deliberately

The default size is not specified by the installed manual. If the image will be placed in a report or compared with other graphs, set both dimensions instead of relying on 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, ...

Do not assume that a larger canvas adds information. It changes the output image size, while the profile data and the plotted measurements remain the same. If a viewer or report has a fixed layout, choose dimensions that fit that layout and verify the resulting file before replacing a previous 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 been checked. 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

mv replaces the destination if it already exists. If the checks fail, do not run it: remove the incomplete /tmp/memory-profile.png.new when you have confirmed it is disposable, and the previous graph remains in place. The source profile is not changed by memusagestat.

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 is not installed or the destination directory is not writable. Check the command and directory separately:

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

A graph that is valid PNG but misleading usually points to 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 are asking. Re-run the producer and graphing steps with a fresh output name rather than editing the PNG by hand. Reserve elevated privileges for the separate case where the input or destination is intentionally protected; sudo does not repair a malformed profile.