SYSTEM MEMORY USAGE UTILITIES

Contents:
1. mem-monitor
2. mem-monitor-smaps
3. mem-smaps-private
4. mem-dirty-code-pages
5. mallinfo
6. run-with-memusage
7. mem-cpu-monitor
8. mem-cpu-plot

This package contains several small utilities for reporting and
monitoring process memory usage from the system point of view.
These are documented more in detail in their own manual pages.

Mallinfo is a library so it doesn't have a manual page and
is documented in detail below.


1. mem-monitor

Shows system memory usage at requested intervals.


2. mem-monitor-smaps

Shows either system memory usage at requested intervals in fairly
similar fashion as mem-monitor, or the memory usage of an individual
process.


3. mem-smaps-private

Sum the given processes private dirty memory usage from SMAPS data.
This is more relevant from the system point of view than what "top"
reports as RSS or VMSIZE usage.


4. mem-dirty-code-pages

Sum the given processes private dirty code page usage from SMAPS data.
Any processes having such use code use dynamic libraries that have been
improperly built without -fPIC as shared libraries.

The more comprohensive "sp-smaps" and "sp-endurance" packages can be
also used for processing SMAPS data, but their postprocessing tools
require Python which is not installed to the device by default. The
SMAPS scripts in this package need only POSIX shell and Awk which are
provided by Busybox.


5. mallinfo

Mallinfo is a library for for dumping statistics from mallinfo() and
sbrk() calls into $HOME/mallinfo-PID.trace file.

This can be used to monitor the difference between how much process
uses memory from the system and how much of that memory is allocated
by the C-library is re-usable by the process. If this difference grows,
the process memory is fragmented (heap grows and decreases only from
the top) and fairly certainly it's leaking.  If this is the case,
"valgrind" can be used to find out and fix the leaks.  If this doesn't
fix the fragmentation, "sp-libleaks" package (and its "allocmap" tool)
can be used to investigate the issue further.

Mallinfo library can be linked dynamically or statically (only shared
version is provided by default) or as LD_PRELOAD library.  In
Scratchbox "run-with-mallinfo" helper script is needed for LD_PRELOAD.


To enable tracing you have to set MALLINFO variable:
   export MALLINFO="yes"        -- use 5 seconds timeout and SIGALRM
   export MALLINFO="signal=10"  -- use SIGUSR1 to generate the report
   export MALLINFO="period=10"  -- periodic report for 10 seconds

The report format is the following:
   time    - time of report since application started
   arena   - size of non-mmapped space allocated from system
   ordblks - number of free chunks
   smblks  - number of fastbin blocks
   hblks   - number of mmapped regions
   hblkhd  - space in mmapped regions
   usmblks -  maximum total allocated space
   fsmblks - space available in freed fastbin blocks
   uordblks - total allocated space
   fordblks - total free space
   keepcost - top-most, releasable (via malloc_trim) space
   total    - mi.uordblks + mi.fordblks + mi.hblkhd,
   sbrk     - sbrk pointer at the specified time

6. run-with-memusage

A convenience wrapper similar to run-with-mallinfo (i.e. user does not have to
care about preloading differences between Scratchbox and other environments),
but wraps libmemusage library instead.  When run with this script,
statistics about application memory allocations will be displayed when
the application exits.

7. mem-cpu-monitor

mem-cpu-monitor outputs (one-liner) system and process memory, CPU usage and
frequency information at intervals defined by -i option (three seconds by
default).

The processes to be monitored are specified by their process ID numbers (PIDs).
Any number of PIDs may be specified. For processes their clean, dirty memory,
dirty memory change and CPU usage is monitored.

Monitoring is continued until explicitly interrupted, for example by issuing
SIGTERM via Ctrl-C.

8. mem-cpu-plot

Visualize mem-cpu-monitor output by creating memory and CPU usage graphs with
gnuplot.