From aac12528195347ec025f70e4527ee4f5a035b831 Mon Sep 17 00:00:00 2001 From: Timo Kokkonen Date: Sun, 19 Sep 2010 18:36:03 +0300 Subject: [PATCH] Add README file This file contains some description on how this tool works and how it can be used. Signed-off-by: Timo Kokkonen --- README | 217 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 README diff --git a/README b/README new file mode 100644 index 0000000..2661c52 --- /dev/null +++ b/README @@ -0,0 +1,217 @@ +NAME + +scan-pagemap - display process memory consumption information + + +SYNOPSIS + +scan-pagemap [options] processes.. pids.. + + +DESCRIPTION + +This is a tool that can analyze in detail the actual memory usage of +processes. The /proc/pid/maps intrface is used to gather information +about the files mapped in the process address space. The +/proc/pid/pagemap interface is used to gather further information +about the real physical page frame numbers allocated for the memory of +process'es address space. + + -p, --pid + Scan process with given pid numer + + -P, --process + Scan processes with given name + + -m, --map + When scanning processes, ignore all mapping names + which don't cntain the given string in their name. + + -d, --dump + Dump all mappings that belong to a process. The dump + will contain following columns: + + size: The logical size of the mapping in process + address space + + RSS: Resident Set Sise, the amount of allocated bytes + in ram + + swapped: The amount of bytes residing in swap + + total: RSS + swapped + + name: Name of the mapping as in /proc/pid/maps file + + + -s, --shared-mappings + Only dump mappings that are shared with all the + processes given as an argument. This option implies -d + option. When -s option is given, all columns except + 'size' will count only the pages that appear in the + address space off all the processes given as an + argumet to scan-pagemap. + + --with-threads + Gather the data individually for each thread. This is + usually not needed, as most threads are created with + clone() syscall with CLONE_VM set. Therefore, all + threads contain the same physical address space. + +EXAMPLES + +1. The default mode of operation + +This mode consists of two phase scan. The first phase will scan +through the processes user has given as an command line argument. The +processes can be given as a list of names or pid numers. Each +non-option argument is first tested if a matching pid numer is found +on the system. If no pids are found for the argument, all running +processes are scanned through and the argument is tested against the +name of the process. All processes with a matching name are added to +the list of processes to be scanned. + +For each of the processes, the file /proc/pid/maps is used to gather +information about the mappings in its address space. Then the file +/proc/pid/pagemaps is used to find out the physical page frame numbers +used for each 4k page in the process address space. After this, in the +second phase, all other processes in the system are scanned similar +way. + +On this second scan only the references to the already known page +frame numbers are recorded. When all processes are scanned through, +the list of processes is then printed out. On this list, the processes +marked with asterisk (*) are the ones which have been scanned fully +during the initial scanning phase. The amount of memory printed for +these processes reflect to their actual memory consumption. The rest +of the processes which have not been marked only count the amount of +memry they share with at least one of the marked processes. + +Example output: + +$ scan-pagemap emacs + + RSS swapped USS total pid name +29080 kB 80 kB 20964 kB 29160 kB 7343 * emacs +11472 kB 8 kB 7528 kB 11480 kB 9468 * emacs + 4508 kB 0 B 0 B 4508 kB 3080 gkrellm + 3212 kB 0 B 0 B 3212 kB 5020 evolution + 3016 kB 0 B 0 B 3016 kB 27315 /usr/bin/python2.6 + 2580 kB 0 B 0 B 2580 kB 3039 kwin + 1952 kB 0 B 0 B 1952 kB 3533 /usr/bin/urxvt +Total 163 processes + referenced pages: 2136, 8544 kB + uptodate pages: 9165, 36660 kB + dirty pages: 376, 1504 kB + lru pages: 9165, 36660 kB + active pages: 8720, 34880 kB + mmap pages: 9159, 36636 kB + anon pages: 7032, 28128 kB + swapcache pages: 11, 44 kB + swapbacked pages: 7176, 28704 kB + present pages: 9155, 36620 kB + swapped pages: 22, 88 kB + unique pages: 7124, 28496 kB + total pages: 9178, 36712 kB + + +[the amount pf processes on the output has been shrinked] + +On this example, there were two processes which match the given +arguments. They are marked with asterisk * in the beginning of the +process name. For these processes, the columns reflect the entire +process memory consumption. Every process without the mark only show +the memory consumption they share with at least one of the processes +marked with asterisk. + +The columns have following meaning: + +RSS: Resident set size. The amount of process memory currently in + ram. + +swapped: The amount of bytes residing in swap + +USS: Unique Set Size. The amount of ram which has the reference + count in kernel set to one. This means the data is not shared + between the processes. + +total: RSS + swapped + +pid: The process ID number + +name: Name and the entire process command line + +In the end of the output there is some statistical information about +the pages gathered during the initial scan. The /proc/kpageflags file +is used to gather information about the kernel page flags for each +recorded page reference. The occurrance of each page flag is counted +and printed in the summary. The listed page flags is provided by the +kernel. Documentation for the given page flags can be found in the +Documentation/vm/pagemap.txt file in the linux kernel source tree. + +The last four entries on the summary listing are counted differently: + +present pages + Total number of pages (among the initially scanned processes) + that reside currently in ram. + +swapped pages + Similarly to above, but pages in the swap + +unique pages: + This is the number of pages that have kernel reference count + set to 1. The value is obtained by reading file + /proc/kpagecount + +total pages: + The total number of physical page frames belonging to the + processes scanned with the given arguments + + +2. Dump mode + +In this mode, only the processes listed in command line arguments are +scanned through. After the initial scan, the mappings for each process +are dumped out. The output is similar to the process listing, but each +line represent a single mapping found in /proc/pid/maps file. + +This mode can be altered with the -s option. When that option is +implied, the output is altered so that the memory consumption figures +for each mapping reflect to the amount of pages shared between all of +the processes given in the command line argument list. This option is +useful for figuring out how two or more processes share memory between +each others. + +Example output: + +scan-pagemap emacs -s +make: `scan-pagemap' is up to date. +process: [7343] emacs + size RSS swapped total name + 8424 kB 2092 kB 0 B 2092 kB /usr/bin/emacs-23 + 1392 kB 548 kB 0 B 548 kB /lib64/libc-2.12.1.so + 1300 kB 172 kB 0 B 172 kB /usr/lib64/libxml2.so.2.7.7 + 1240 kB 116 kB 0 B 116 kB /usr/lib64/libX11.so.6.3.0 + 120 kB 92 kB 0 B 92 kB /lib64/ld-2.12.1.so + 988 kB 88 kB 0 B 88 kB /usr/lib64/libglib-2.0.so.0.2400.1 + 288 kB 68 kB 0 B 68 kB /usr/lib64/libpango-1.0.so.0.2800.1 + 588 kB 56 kB 0 B 56 kB /usr/lib64/libfreetype.so.6.6.0 + 304 kB 56 kB 0 B 56 kB /lib64/libncurses.so.5.7 + 92 kB 56 kB 0 B 56 kB /lib64/libpthread-2.12.1.so + 116 kB 36 kB 0 B 36 kB /usr/lib64/libxcb.so.1.1.0 +[clip] + +On this example, all processe on the system with name 'emacs' were +scanned. The list of mappings they all share has been printed. The +'size' column shows the logical size of the mapping in the process +address space. The rest of the columns show only the amount of pages +shared between all of the given processes. + +NOTES + +The scan-pagemap tool generally requires root permissions to run +correctly. It will be able to scan the users' own processes even +without root priviledges. But then it will not be able to get system +wide process memory consumption statistics. Also the /proc/kpageflags +and /proc/kpagecount files are inaccessible, thus the page statistics +printed in the end are inaccurate or unavailable. -- 2.45.0