Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
ProcAn: An Adaptive Process Analysis tool for FreeBSD, OpenBSD, and Linux. (For a detailed description see its project page on http://www.matburt.net) Build instructions: There are no external dependencies for FreeBSD and OpenBSD save the standard C libraries. Linux requires libproc and a version of header files needed to build are included in this source distribution. To build on Linux: make To build on FreeBSD and OpenBSD: gmake (after installing GNU Make) Usage instructions: Procan ships with an example configuration file and will complain if a configuration file is not present. This example file can be used by copying it to: procan.conf Running procan with no options will print out some very brief usage information, but here I'll provide more detail. Currently there are three primary modes: interactive mode (-i), daemon mode (-d), and pipe mode (-p). *Interactive Mode: While running procan in interactive mode it will not detach from the shell, but instead will show a curses-style information display. By pushing q procan will shutdown its threads and quit. While using procan in interactive mode all backends (more on that in a minute) will still be active the only difference is procan will not detatch from the shell and will not respond to SIGTERM, but it will respond to SIGHUP (Re-read the configuration file) and SIGUSR1 (Reset statistics). *Daemon Mode: Daemon mode will cause procan to detach from the shell and continue running in the background. Running procan in the background without using any of the supported backends is rather pointless as you will not be notified of interesting processes in any way. You can shutdown procan by issuing a SIGTERM on the process. SIGHUP will cause it to re-read its configuration file. SIGUSR1 resets the statistics. *Pipe Mode: Pipe Mode does not detatch from the shell, it is meant to have its output piped to another program. The format looks like this: [rss,procan,24927,+1,2,0] The first parameter is what has changed most recently, the second is the process name, the third is the pid, the fourth is the score modifier, the fifth is the overall score, and the sixth is the interest level. There are two preliminary plugins in the ./plugins directory of the source tree to demonstrate the pipe mode but it should be noted that they don't work very well yet. To run the gnuplot plugin you will need the python gnuplot libraries and you could run it like this: procan -p | ./plugins/gnuplot-plugin.py *The configuration file procan requires a configuration file, there is a sample config file provided with the program that you should rename from procan.conf.sample -> procan.conf. The following is the directory order that procan will search looking for a config file: /etc/, /usr/etc/, /usr/local/etc/, /usr/local/etc/procan/, ./ If it can not find the config file it will quit. You should open this and read through it setting the options that you need, it's very simple and each configuration option has a description and example. *Backends procan supports three backends: mail, script, syslog and can use any combination of these three, including all three if that is what you want. Backends work in both interactive and daemon mode. +mail backend: The mail backend will send a digest of the top 5 most interesting processes to the user provided in the configuration file, it will use the MTA also provided in the configuration file. Which defaults to /usr/sbin/sendmail In the event of a process being in the Warned or Alarm state an email will be sent to the administrator +script backend: The script backend will trigger a user-defined script action based on an Alarm and/or Warn event whose tolerance can be configured in the configuration file. The numbers correspond to how interesting a process is in a one-hour period. For instance, heavy firefox usage will frequently trigger a WARN event and will some times trigger an ALARM event on the default settings. You can define your own scripts in the configuration file. procan will pass 4 arguments to this script: 1) The PID of the process 2) The name of the process 3) The "Score" of the process (More on this in a minute) 4) The number of times in one hour that it was interesting +syslog backend: The syslog backend works the same way the mail backend works bu t will send the top 5 most interesting processes to syslog via LOG_NOTICE, note that syslog strips newlines from log messages. Syslog will also be notified of processes that are flagged in the WARN or ALARM state. Other Information and FAQs: "What is the 'Score' and how does it differ from how 'interesting' a process is? The Score of a process is used as a long term benchmark by which you can measure a process. For instance, many times you'll see scores with negative numbers. Whenever a process allocates memory or starts using more processor time, it's score goes up. When it is freeing memory its score will go down. When it is no longer using very much processor time any points it was given while it was using processor time will be repealed. You can use this to look at a process in the long term based on when a process was started. If you start using procan and then several hours later you see that firefox has a score of -12 then you'll know that since procan was started firefox has freed more resources than it has used. Likewise if you see a process with a very high score then that process is constantly consuming more resources and this might be indicative of a memory leak or a race condition. "I'm running (Gnome/KDE/Other Applications that make heavy use of resources) and it is triggering a lot of warnings and alarms, what gives?" After running a lot of tests on my main window manager (Window Maker) I got used to not seeing a lot of interesting processes except the ones I was using frequently (emacs, gcc, gaim, firefox, etc) but if you are using Gnome/KDE you will see their programs and daemons show up a lot. Why is this? you ask. It's simple. These window managers have very strange resource usage patterns, which is evident by how often they show up in procan. Gnome is the absolute worst, especially older versions. It is constantly allocating memory for no apparent reason, and at very random times seldom in response to any user event. KDE is a little different and slightly more effecient but it tends to allocate memory in very large chunks (seemingly preparing for the user). If you do not want these processes to be tracked by procan you can put them in the ignore list in the configuration file and they will be ignored. I strongly recommend you do this with some Gnome and KDE background processes, and also such things as xscreensaver and any very graphical games. "On Linux I see that procan is almost never idle, always running at at least 1% to 5%, why?" On Linux procan uses libproc which is based on procfs. Procfs is a horrible way to do fast reading of the process table. Linux has no way (that I'm aware of) to get process information from the kernel, if you'll look in the sysctl headers you will see that there once was or there is a plan to add them but they just aren't there. In my opinion this is rather silly. I think that procfs has some valid uses but in most cases it seems it is more the product of laziness than any attempt at effeciency. FreeBSD and OpenBSD both have sysctl interfaces to the process tree. "I've found a bug or something that I think is a bug, what should I do?" Please email me, and include any important information, like a backtrace or some description of the behavior that caused the bug. I really appreciate any and all bug reports and I am willing to work very hard to make this an extremely versatile tool.