diff options
| author | Mark Wong <markwkm@gmail.com> | 2013-04-19 20:04:17 -0700 |
|---|---|---|
| committer | Mark Wong <markwkm@gmail.com> | 2013-04-19 20:04:17 -0700 |
| commit | 2f50bc2ffdd48fb4aff79b3c66051fe020837696 (patch) | |
| tree | d11abf3d7ef38ce41e3fe50e037d97e92ebfd009 | |
| parent | fb92cdd1c70b527ccb6091f327e0e75a0b194eea (diff) | |
Update docs and man pages
| -rw-r--r-- | FAQ | 218 | ||||
| -rw-r--r-- | HISTORY | 4 | ||||
| -rw-r--r-- | LICENSE | 2 | ||||
| -rw-r--r-- | Porting | 2 | ||||
| -rw-r--r-- | README | 16 | ||||
| -rw-r--r-- | TODO | 10 | ||||
| -rw-r--r-- | machine/m_freebsd.man | 2 | ||||
| -rw-r--r-- | pg_top.1.in | 8 |
8 files changed, 46 insertions, 216 deletions
@@ -1,9 +1,8 @@ - pg_top - Version 3.7.0 + pg_top + Version 3.7.0 - Mark Wong - Frequently Asked Questions and their Answers + Frequently Asked Questions and their Answers @@ -11,8 +10,8 @@ 1. What is pg_top? - pg_top is 'top' for PostgreSQL. It is derived from Unix Top. Similar to top, - pg_top allows you to monitor PostgreSQL processes. It also allows you to: + pg_top is 'top' for PostgreSQL. It is derived from Unix Top. Similar to top, + pg_top allows you to monitor PostgreSQL processes. It also allows you to: * View currently running SQL statement of a process. * View query plan of a currently running SELECT statement. @@ -22,39 +21,31 @@ 2. Where do I get the latest version of pg_top? - If you have mercurial, you can download the latest version from - SourceForge: - - hg clone http://ptop.sourceforge.net/cgi-bin/hgwebdir.cgi/pg_top + If you have git, you can checkout the latest at: + + git clone git://git.postgresql.org/git/pg_top.git 3. Is there a web page for pg_top? - http://ptop.projects.postgresql.org/ + http://ptop.projects.postgresql.org/ 4. Is there a mailing list or on-line bulletin board for pg_top? - Subscribe or browse the archives of ptop-hackers at: + Subscribe or browse the archives of ptop-hackers at: - http://lists.pgfoundry.org/mailman/listinfo/ptop-hackers + http://lists.pgfoundry.org/mailman/listinfo/ptop-hackers 5. What about Y2K/Year 2038 compliance? - A full statement concerning top and the year 2000 can be found in the file - "Y2K" included with the distribution. + A full statement concerning top and the year 2000 can be found in the file + "Y2K" included with the distribution. 6. Will there be another major release of pg_top? Will there be a pg_top version 4? We hope so! Depends on how much fun we have. :) - 7. Is top under CVS control? Can I access the sources via SourceForge - CVS or Subversion? - - I maintain top using mercurial, not CVS. See FAQ #2. - - COMPILING - - 8. We just upgraded our operating system to a new version and pg_top broke. + 7. We just upgraded our operating system to a new version and pg_top broke. What should we do? Recompile it. pg_top is very sensitive to changes in internal kernel @@ -64,7 +55,7 @@ RUNNING -10. I just finished compiling top and it works fine for root, but when I + 8. I just finished compiling top and it works fine for root, but when I try to run it as a regular user it either complains about files it can't open or it doesn't display all the information it should. Did I do something wrong? @@ -77,193 +68,26 @@ However, you have to *install* it first. Do this with the command "make install". -11. pg_top is (not) displaying idle processes and I don't (do) want it to. + 9. pg_top is (not) displaying idle processes and I don't (do) want it to. This default has only changed about a dozen times, and I finally got tired of people whining about it. Go read the manual page for the current version and pay special attention to the description of the "PG_TOP" environment variable. -12. We have so much memory in our machine that the memory status display - (the fourth line) ends up being longer than 80 characters. This - completely messes up top's output. Is there a patch? - - Most modules have been changed to use new memory formatting functions - which will display large values in terms of megabytes instead of - kilobytes. This should fix all occurences of this problem. Also note - that newer versions of top can use columns beyond 79, and understand - window resizes. So you can always make your window wider. - -13. I tried to compile top with gcc and it doesn't work. I get - compilation errors in the include files, or I get an executable that - dumps core, or top displays incorrect numbers in some of the - displays. What's wrong? - - Gnu CC likes very much to use its own include files. Not being a gcc - expert, I can't explain why it does this. But I can tell you that if - you upgrade your operating system (say from Solaris 2.6 to Solaris - 2.7) after installing gcc, then the include files that gcc uses will - be incorrect, especially those found in the "sys" directory. Your - choices are: (1) rebuild and reinstall the "standard" include files - for gcc (look for scripts in the distribution called "fixincludes" - and "fixinc.svr4"), (2) compile machine.c with - "CFLAGS=-I/usr/include" then make the rest of the object files - normally, or (3) use a different compiler. - -14. The cpu state percentages are all wrong, indicating that my machine +10. The cpu state percentages are all wrong, indicating that my machine is using 95% system time when it is clearly idle. What's wrong? This can happen if you compiled with gcc using the wrong include files. See the previous question. - SUNOS PROBLEMS - -15. I tried compiling top under SunOS version 4.1.x and it got compile - time errors or run time errors. Is there a patch? - - If you try compiling top in a "System V environment" under SunOS - (that is, /usr/5bin is before /usr/bin on your path) then the - compilation may fail. This is mostly due to the fact that top thinks - its being compiled on a System V machine when it really isn't. The - only solution is to put /usr/bin and /usr/ucb before /usr/5bin on - your path and try again. - - - SOLARIS PROBLEMS - - - NOTE: the most common source of problems with top under Solaris is - the result of compiling it with the wrong front end. Make sure that - /usr/ucb is not on your path before attempting to compile top under - Solaris. - -16. Is there somewhere I can get a pre-compiled package? - - Yes. Although I don't provide pre-compiled binaries, you can get a - Sun-style package from www.sunfreeware.com. - -17. Under Solaris 2, when I type "make", the system says "language - optional software package not installed." What's going on? - - You tried to compile with /usr/ucb/cc. Make sure /usr/ucb is not on - your path. Furthermore, you do not have a Sun compiler installed on - your system. You need a compiler to make top. Either Sun's C compiler - or the Gnu C compiler will work fine. - -18. Under Solaris 2, when I run top as root it only shows root processes, - or it only shows processes with a PID less than 1000. It refuses to - show anything else. What do I do? - - You probably compiled it with /usr/ucb/cc instead of the real C - compiler. /usr/ucb/cc is a cc front end that compiles programs in BSD - source-level compatability mode. You do not want that. Make sure that - /usr/ucb is not on your path and try compiling top again. - -19. Under Solaris 2, I compiled top using what I am sure is the correct - compiler but when I try to run it it complains about missing dynamic - libraries. What is wrong? - - Check to see if you have LD_LIBRARY_PATH defined in your shell. If - you do, make sure that /usr/ucblib is not on the path anywhere. Then - try compiling top again. - -20. Under Solaris 2, when I try to run top it complains that it can't - open the library "libucb.so.1". So I changed the LIBS line in - m_sunos5.c to include -R/usr/ucblib to make sure that the dynamic - linker will look there when top runs. I figured this was just an - oversight. Was I right? - - No, you were not right. As distributed, top requires no alterations - for successful compilation and operations under any release of - Solaris 2. You probably compiled top with /usr/ucb/cc instead of the - real C compiler. See FAQ 22 for more details. - -21. On my 64-bit system some processes show up with incorrect information - (such as zero memory). - - If you are running a 64-bit system, then you will want to make a - 64-bit top binary. pg_top's configure script attempts to detect 64-bit - systems, and will adjust the compilation options accordingly. If you - configure and make a binary on a 32-bit system it will still run on a - 64-bit system, but may not produce the correct results. The same will - happen if you configure your distribution on a 32-bit system then - compile with that configuration on a 64-bit system. You must - configure and compile on the same system. - -22. Can I install both 32-bit and 64-bit binaries on a central file - server and have machines which mount it automatically use the correct - one? - - Yes. First, compile a 32-bit version and name it top32. Then compile - a 64-bit version (see FAQ #22) and name it top64. Make sure each - binary has the correct ownership and mode. Choose your bin directory - (we will refer to that as $BIN). In $BIN make sure there are - subdirectories named "sparcv7" and "sparcv9". If they don't exist - then create them. Copy "top32" to "$BIN/sparcv7/top" and "top64" to - "$BIN/sparcv9/top". Finally copy (do not link) the binary - /usr/lib/isaexec to "$BIN/top". When a user runs "top" she will - actually be running a copy of isaexec. This tool will automatically - determine the kernel type and run the top "binary" out of the correct - subdirectory. - -23. This version of top show less available swap space than previous - versions. Why does it no longer match the output of the swap summary - produced with "swap -s"? - - Starting with version 3.6 of top, the amount of swap space reported - by top has been changed to reflect only disk-based swap space. The - swap summary produced with "swap -s" also include memory-based swap - space. This changed was mae for several reasons. It makes the display - under Solaris more like those of other operating systems. The display - is more what users expect (except those used to previous versions of - top). Most importantly, "swap -s" gets its data via an undocumented - system interface. Now that top no longer displays that data it can - use publically documented and maintained system interfaces to - retrieve its data. - - - SVR4-DERIVED PROBLEMS - -24. When I run top on my SVR4-derived operating system, it displays all - the system information at the top but does not display any process - information (or only displays process information for my own - processes). Yet when I run it as root, everything works fine. What's - wrong? - - Your system probably uses the pseudo file system "/proc", which is by - default only accessible by root. pg_top needs to be installed setuid - root on such systems if it is going to function correctly for normal - users. - - - SVR42 PROBLEMS - -25. The memory display doesn't work right. Why? - - This is a known bug with the svr42 module. The problem has been - traced down to a potential bug in the "mem" driver. The author of the - svr42 module is working on a fix. - - STILL STUCK -26. I'm still stuck. To whom do I report problems with top? - - The most common problems are caused by top's sensitivity to internal - kernel data structures. So make sure that you are using the right - include files, and make sure that you test out top on the same - machine where you compiled it. Sun's BSD Source Compatability Mode is - also a common culprit. Make sure you aren't using either /usr/ucb/cc - or any of the libraries in /usr/ucblib. Finally, make sure you are - using the correct module. If there does not appear to be one - appropriate for your computer, then top probably will not work on - your system. +11. I'm still stuck. To whom do I report problems with top? If after reading all of this file and checking everything you can you - are still stuck, then please use SourceForge to submit a support - request or a bug. pg_top is supported by the SourceForge project named - "unixtop". On SourceForge you will find defect tracking, a mailing - list, and on-line forums. You can also contact the author through - SourceForge. + are still stuck, then please refer to the mailing to ask further + questions: + http://lists.pgfoundry.org/mailman/listinfo/ptop-hackers @@ -4,6 +4,10 @@ Release 3.7.0 * Added support for monitoring databases on remote systems. * Added support for monitoring i/o statistics on Linux. + * Updated for changed introduced in PostgreSQL 9.2. + * Updated for OpenBSD 5.2. + * Updated for FreeBSD 9.1. + * Updated for OS X Mountain Lion (10.8). Release 3.6.2 @@ -1,5 +1,5 @@ Copyright (c) 2005, William LeFebvre -Copyright (c) 2007-2008, Mark Wong +Copyright (c) 2007-2013, Mark Wong All rights reserved. @@ -225,5 +225,3 @@ If there is no support for multiple keys: Leave statics->order_names alone and call the comparison function of your choice in get_process_info, ignoring the third argument. - - @@ -5,9 +5,6 @@ and a cast of ... a few -If you are having any problems getting pg_top to work, please read the -file "FAQ" *before* contacting me. Thank you. - pg_top is 'top' for PostgreSQL. It is derived from Unix Top. Similar to top, pg_top allows you to monitor PostgreSQL processes. It also allows you to: @@ -30,7 +27,14 @@ directions and advice contained therein. If you make any kind of change to "pg_top" that you feel would be beneficial to others who use this program, or if you find and fix a bug, -please send me the change. +please send the change to the pg_top mailing list. + +In order to monitor a remote database, the pg_proctab extension needs to be +created on the database to be monitored. Any operating system that pg_proctab +supports can be monitored remotely on any operating system. See details for +pg_protab here: + +http://pgxn.org/dist/pg_proctab/ Be sure to read the FAQ enclosed with the distrubution. It contains answers to the most commonly asked questions about the configuration, @@ -43,9 +47,9 @@ Project home page: http://ptop.projects.postgresql.org/ -If you have mercurial, you can download the source code from SourceForge: +If you have git, you can download the source code: -hg clone http://ptop.sourceforge.net/cgi-bin/hgwebdir.cgi/pg_top +git clone git://git.postgresql.org/git/pg_top.git GRATITUDE @@ -1,11 +1,5 @@ * Test on more platforms. Development has primarily been on Linux and some - attempts have been made on FreeBSD and Solaris. - -* Use a stored procedure to get system statistics so that pg_top can be run - remotely, as opposed to running pg_top locally in order to access the - operating systems process table. - - Linux is done, more operating systems to go... + attempts have been made on FreeBSD, OpenBSD, and OS X. * Display status in the executor using pstack/dtract/gstack. @@ -17,8 +11,6 @@ * Display summary statistics for queries per second, average query cpu time, average query elapsed time, etc. -* Display i/o statistics per process. - * Renamed number of processs to be number of connections since that is more accurate: diff --git a/machine/m_freebsd.man b/machine/m_freebsd.man index e57208f..0730089 100644 --- a/machine/m_freebsd.man +++ b/machine/m_freebsd.man @@ -46,4 +46,4 @@ See /usr/include/sys/vmmeter.h and /sys/vm/vm_meter.c. Christos Zoulas, Steven Wallace, Wolfram Schneider, Monte Mitzelfelt. .PP -This module was retrofitted from FreeBSD 4.6.2 sources. +This module was retrofitted from FreeBSD 9.1 sources. diff --git a/pg_top.1.in b/pg_top.1.in index e6659fd..4e666e0 100644 --- a/pg_top.1.in +++ b/pg_top.1.in @@ -19,6 +19,8 @@ pg_top \- display and update information about the top cpu PostgreSQL processes ] [ .BI \-p PORT ] [ +.BI \-r +] [ .BI \-s time ] [ .BI \-U USER @@ -109,6 +111,12 @@ to \-20 so that it will run faster. This can be used when the system is being very sluggish to improve the possibility of discovering the problem. This option can only be used by root. .TP +.B \-r +Monitor a remote database where the database is on a system other than where +pg_top is running from. +.I pg_top +will monitor a remote database if it has the pg_proctab extension installed. +.TP .B \-u Do not take the time to map uid numbers to usernames. Normally, .I pg_top |