git.itanic.dy.fi Git - scan-pagemap/blob - README

   1 NAME
   2
   3 scan-pagemap - display process memory consumption information
   4
   5
   6 SYNOPSIS
   7
   8 scan-pagemap [options] processes.. pids..
   9
  10
  11 DESCRIPTION
  12
  13 This is a tool that can analyze in detail the actual memory usage of
  14 processes. The /proc/pid/maps intrface is used to gather information
  15 about the files mapped in the process address space. The
  16 /proc/pid/pagemap interface is used to gather further information
  17 about the real physical page frame numbers allocated for the memory of
  18 process'es address space.
  19
  20  -p, --pid
  21                 Scan process with given pid numer
  22
  23  -P, --process
  24                 Scan processes with given name
  25
  26  -m, --map
  27                 When scanning processes, ignore all mapping names
  28                 which don't cntain the given string in their name.
  29
  30  -d, --dump
  31                 Dump all mappings that belong to a process. The dump
  32                 will contain following columns:
  33
  34                 size:   The logical size of the mapping in process
  35                         address space
  36
  37                 RSS:    Resident Set Sise, the amount of allocated bytes
  38                         in ram
  39
  40                 swapped: The amount of bytes residing in swap
  41
  42                 total:  RSS + swapped
  43
  44                 name:   Name of the mapping as in /proc/pid/maps file
  45
  46
  47  -s, --shared-mappings
  48                 Only dump mappings that are shared with all the
  49                 processes given as an argument. This option implies -d
  50                 option. When -s option is given, all columns except
  51                 'size' will count only the pages that appear in the
  52                 address space off all the processes given as an
  53                 argumet to scan-pagemap.
  54
  55  --with-threads
  56                 Gather the data individually for each thread. This is
  57                 usually not needed, as most threads are created with
  58                 clone() syscall with CLONE_VM set. Therefore, all
  59                 threads contain the same physical address space.
  60
  61 EXAMPLES
  62
  63 1. The default mode of operation
  64
  65 This mode consists of two phase scan. The first phase will scan
  66 through the processes user has given as an command line argument.  The
  67 processes can be given as a list of names or pid numers. Each
  68 non-option argument is first tested if a matching pid numer is found
  69 on the system. If no pids are found for the argument, all running
  70 processes are scanned through and the argument is tested against the
  71 name of the process. All processes with a matching name are added to
  72 the list of processes to be scanned.
  73
  74 For each of the processes, the file /proc/pid/maps is used to gather
  75 information about the mappings in its address space. Then the file
  76 /proc/pid/pagemaps is used to find out the physical page frame numbers
  77 used for each 4k page in the process address space. After this, in the
  78 second phase, all other processes in the system are scanned similar
  79 way.
  80
  81 On this second scan only the references to the already known page
  82 frame numbers are recorded. When all processes are scanned through,
  83 the list of processes is then printed out. On this list, the processes
  84 marked with asterisk (*) are the ones which have been scanned fully
  85 during the initial scanning phase. The amount of memory printed for
  86 these processes reflect to their actual memory consumption. The rest
  87 of the processes which have not been marked only count the amount of
  88 memry they share with at least one of the marked processes.
  89
  90 Example output:
  91
  92 $ scan-pagemap emacs
  93
  94      RSS  swapped      USS    total   pid   name
  95 29080 kB    80 kB 20964 kB 29160 kB  7343 * emacs
  96 11472 kB     8 kB  7528 kB 11480 kB  9468 * emacs
  97  4508 kB     0  B     0  B  4508 kB  3080   gkrellm
  98  3212 kB     0  B     0  B  3212 kB  5020   evolution
  99  3016 kB     0  B     0  B  3016 kB 27315   /usr/bin/python2.6
 100  2580 kB     0  B     0  B  2580 kB  3039   kwin
 101  1952 kB     0  B     0  B  1952 kB  3533   /usr/bin/urxvt
 102 Total 163 processes
 103    referenced pages:   2136,  8544 kB
 104      uptodate pages:   9165, 36660 kB
 105         dirty pages:    376,  1504 kB
 106           lru pages:   9165, 36660 kB
 107        active pages:   8720, 34880 kB
 108          mmap pages:   9159, 36636 kB
 109          anon pages:   7032, 28128 kB
 110     swapcache pages:     11,    44 kB
 111    swapbacked pages:   7176, 28704 kB
 112       present pages:   9155, 36620 kB
 113       swapped pages:     22,    88 kB
 114        unique pages:   7124, 28496 kB
 115         total pages:   9178, 36712 kB
 116
 117
 118 [the amount pf processes on the output has been shrinked]
 119
 120 On this example, there were two processes which match the given
 121 arguments. They are marked with asterisk * in the beginning of the
 122 process name. For these processes, the columns reflect the entire
 123 process memory consumption. Every process without the mark only show
 124 the memory consumption they share with at least one of the processes
 125 marked with asterisk.
 126
 127 The columns have following meaning:
 128
 129 RSS:    Resident set size. The amount of process memory currently in
 130         ram.
 131
 132 swapped: The amount of bytes residing in swap
 133
 134 USS:    Unique Set Size. The amount of ram which has the reference
 135         count in kernel set to one. This means the data is not shared
 136         between the processes.
 137
 138 total:  RSS + swapped
 139
 140 pid:    The process ID number
 141
 142 name:   Name and the entire process command line
 143
 144 In the end of the output there is some statistical information about
 145 the pages gathered during the initial scan. The /proc/kpageflags file
 146 is used to gather information about the kernel page flags for each
 147 recorded page reference. The occurrance of each page flag is counted
 148 and printed in the summary. The listed page flags is provided by the
 149 kernel. Documentation for the given page flags can be found in the
 150 Documentation/vm/pagemap.txt file in the linux kernel source tree.
 151
 152 The last four entries on the summary listing are counted differently:
 153
 154 present pages
 155         Total number of pages (among the initially scanned processes)
 156         that reside currently in ram.
 157
 158 swapped pages
 159         Similarly to above, but pages in the swap
 160
 161 unique pages:
 162         This is the number of pages that have kernel reference count
 163         set to 1. The value is obtained by reading file
 164         /proc/kpagecount
 165
 166 total pages:
 167         The total number of physical page frames belonging to the
 168         processes scanned with the given arguments
 169
 170
 171 2. Dump mode
 172
 173 In this mode, only the processes listed in command line arguments are
 174 scanned through. After the initial scan, the mappings for each process
 175 are dumped out. The output is similar to the process listing, but each
 176 line represent a single mapping found in /proc/pid/maps file.
 177
 178 This mode can be altered with the -s option. When that option is
 179 implied, the output is altered so that the memory consumption figures
 180 for each mapping reflect to the amount of pages shared between all of
 181 the processes given in the command line argument list. This option is
 182 useful for figuring out how two or more processes share memory between
 183 each others.
 184
 185 Example output:
 186
 187 scan-pagemap emacs -s
 188 make: `scan-pagemap' is up to date.
 189 process: [7343] emacs
 190     size      RSS  swapped    total name
 191  8424 kB  2092 kB     0  B  2092 kB /usr/bin/emacs-23
 192  1392 kB   548 kB     0  B   548 kB /lib64/libc-2.12.1.so
 193  1300 kB   172 kB     0  B   172 kB /usr/lib64/libxml2.so.2.7.7
 194  1240 kB   116 kB     0  B   116 kB /usr/lib64/libX11.so.6.3.0
 195   120 kB    92 kB     0  B    92 kB /lib64/ld-2.12.1.so
 196   988 kB    88 kB     0  B    88 kB /usr/lib64/libglib-2.0.so.0.2400.1
 197   288 kB    68 kB     0  B    68 kB /usr/lib64/libpango-1.0.so.0.2800.1
 198   588 kB    56 kB     0  B    56 kB /usr/lib64/libfreetype.so.6.6.0
 199   304 kB    56 kB     0  B    56 kB /lib64/libncurses.so.5.7
 200    92 kB    56 kB     0  B    56 kB /lib64/libpthread-2.12.1.so
 201   116 kB    36 kB     0  B    36 kB /usr/lib64/libxcb.so.1.1.0
 202 [clip]
 203
 204 On this example, all processe on the system with name 'emacs' were
 205 scanned. The list of mappings they all share has been printed. The
 206 'size' column shows the logical size of the mapping in the process
 207 address space. The rest of the columns show only the amount of pages
 208 shared between all of the given processes.
 209
 210 NOTES
 211
 212 The scan-pagemap tool generally requires root permissions to run
 213 correctly. It will be able to scan the users' own processes even
 214 without root priviledges. But then it will not be able to get system
 215 wide process memory consumption statistics. Also the /proc/kpageflags
 216 and /proc/kpagecount files are inaccessible, thus the page statistics
 217 printed in the end are inaccurate or unavailable.