The main goal of this project is to add the lost documentation.
This website no longer exists : http://sigar.hyperic.com/
Get the documentation from old web site archived:
http://web.archive.org/web/20170201073935/http://support.hyperic.com/display/SIGAR/PTQL
This project is a fork from project that correct Sigar on Windows 64 bits : https://github.com/cnstar9988/sigar
The Sigar Windows DLL for 64 bits is available from project cnstar9988 at : https://github.com/cnstar9988/sigar/blob/master/sigar-amd64-winnt.dll
Extract from ChangeLog :
2010-04-28 Doug MacEachern <dougm@hyperic.com>
* 1.6.4 release
* GPL v2 license -> Apache 2 license
* (SIGAR-188) implement mem actual free/used on Windows
2010-04-27 Doug MacEachern <dougm@hyperic.com>
* (SIGAR-215) use swapctl SC_LIST for Solaris swap_get impl
2010-04-15 Doug MacEachern <dougm@hyperic.com>
* osf1 no longer supported
* netware no longer supported
* (SIGAR-201) JNIEnv->ExceptionCheck to avoid possible SEGV on OutOfMemoryError
SIGAR provides a mechanism to identify processes called "Process Table Query Language".
All operating systems assign a unique id (PID) to each running process.
However, the PID is a random number that may also change at any point in time when a process is restarted.
PTQL uses process attributes that will persist over time to identify a process.
PTQL Queries must be in the following format:
Class.Attribute.operator=value
Enclose the query in quotes if it contains any spaces. For example:
sigar> ps "Exe.Name.ct=Program Files"
Where:
- Class is the name of the Sigar class minus the Proc prefix.
- Attribute is an attribute of the given Class, index into an array or key in a Map class.
- operator is one of the following for String values:
- eq - Equal to value
- ne - Not Equal to value
- ew - Ends with value
- sw - Starts with value
- ct - Contains value (substring)
- re - Regular expression value matches
- operator is one of the following for numeric values:
- eq - Equal to value
- ne - Not Equal to value
- gt - Greater than value
- ge - Greater than or equal value
- lt - Less than value
- le - Less than or equal value Multiple queries must delimited by a comma.
The attributes used in PTQL are directly from the sigar.Proc* classes. This document will outline the attributes most commonly used for identifying processes, the complete set of Proc* classes and attributes can be found in the SIGAR javadocs.
- Pid.Pid - The process ID
- Pid.PidFile - File containing the process ID
- Pid.Service - Windows Service name used to pid from the service manager
- State.Name - Base name of the process executable
- CredName.User - User Name of the process owner
- CredName.Group - Group Name of the process owner
- Cred.Uid - User ID of the process owner
- Cred.Gid - Group ID of the process owner
- Cred.Euid - Effective User ID of the process owner
- Cred.Egid - Effective Group ID of the process owner
- Exe.Name - Full path name of the process executable
- Exe.Cwd - Current Working Directory of the process
- Args.* - Command line argument passed to the process
- Env.* - Environment variable within the process
- Modules.* - Shared library loaded within the process
The process of building a process query will vary depending on the application and the need to identify a unique process or group of processes. For these examples, we will use the sigar shell.
The sigar shell is started using the following command:
java -jar sigar.jar
The sigar.jar file is located in the agent/pdk/lib directory within HQ and sigar-bin/lib within the standalone SIGAR distribution.
When the shell is started, you'll be given a prompt:
sigar>
The help command will show the complete list of top-level commands. We will focus on the handful that are useful for building PTQL queries:
- ps - Process Status
- pargs - Process Arguments
- penv - Process Environment
- pfile - Process File Information
- pinfo - Other Process Info Each of the commands listed above require an argument of either a process ID or PTQL query. For certain commands like ps you can use tab completion in the shell to see the possible values.
The simplest of queries can use 'State.Name', the basename of the process executable, to identify a process. For example, the cron daemon on a Linux system:
sigar> ps "State.Name.eq=crond" 560 root 13:03 536K 536K 456K S 0:0 syslogd
This approach works to uniquely identify other daemons, such as 'syslogd', 'dhclient' and others where there should only be 1 process with the given name. However, in the case of a daemon such as sshd, there will likely be multiple instances:
sigar> ps "State.Name.eq=sshd" 729 root 13:05 1.4M 1.4M 1.3M S 0:0 /usr/sbin/sshd 1124 root 13:53 2.0M 2.0M 1.8M S 0:0 /usr/sbin/sshd 1126 dougm 13:53 2.2M 2.2M 2.0M R 0:2 /usr/sbin/sshd
The easiest way to find the listening sshd server is to use the pid file:
sigar> ps "Pid.PidFile.eq=/var/run/sshd.pid" 729 root 13:05 1.4M 1.4M 1.3M S 0:0 /usr/sbin/sshd
While this will also work on Windows platforms, it is less common to find a pid files, especially for Windows specific products. It is very common however, for a server process to be registered as Windows Service. Example for the Windows Event Log service:
sigar> ps "Pid.Service.eq=Eventlog" 1308 SYSTEM 16:02 5.0M 2.1M - R 0:39 C:\WINDOWS\system32\services.exe
If you happen to be running Cygwin sshd:
sigar> ps "Pid.Service.eq=sshd" 4408 SYSTEM 15:58 2.1M 1.2M - R 0:0 C:\cygwin\bin\cygrunsrv.exe
Certain server applications, such as Apache, may have a different 'State.Name' depending on platform, vendor or configuration:
- httpd - The standard name on unix platforms
- Apache - The standard name on windows platforms
- httpsd - Apache-SSL
- httpsd.prefork, httpsd.worker - Covalent's Apache ERS product
- apache2 - gentoo A regular expression can be used to match any of these flavors. Example on a Linux system:
sigar> ps "State.Name.re=^(https?d.*|[Aa]pache2?)$" 6807 dougm 15:10 2.6M 2.6M 1.5M S 0:0 /local0/dougm/apps/httpd-2.0.54/bin/httpd 6808 dougm 15:10 3.0M 3.0M 1.6M S 0:0 /local0/dougm/apps/httpd-2.0.54/bin/httpd 6809 dougm 15:10 2.6M 2.6M 1.5M S 0:0 /local0/dougm/apps/httpd-2.0.54/bin/httpd 6810 dougm 15:10 2.6M 2.6M 1.5M S 0:0 /local0/dougm/apps/httpd-2.0.54/bin/httpd 6811 dougm 15:10 2.6M 2.6M 1.5M S 0:0 /local0/dougm/apps/httpd-2.0.54/bin/httpd 6812 dougm 15:10 2.6M 2.6M 1.5M S 0:0 /local0/dougm/apps/httpd-2.0.54/bin/httpd 6813 dougm 15:10 2.6M 2.6M 1.5M S 0:0 /local0/dougm/apps/httpd-2.0.54/bin/httpd
Example on a Windows system:
sigar> ps "State.Name.re=^(https?d.*|[Aa]pache2?)$" 5124 SYSTEM 15:11 5.7M 2.6M - R 0:0 c:\Program Files\Apache Group\Apache2\bin\Apache.exe 6016 SYSTEM 15:12 10M 8.9M - R 0:0 C:\Program Files\Apache Group\Apache2\bin\Apache.exe
In the apache examples above, we were able to use a regular expression to find Apache server processes with different names. However, the examples returned a process listing for the parent process as well as its children. PTQL operators support the notion of a parent flag, 'P', which converts the given query branch to get the attribute of the parent process. For example:
sigar> ps "State.Name.eq=httpd,State.Name.Pne=httpd" 6807 dougm 15:10 2.6M 2.6M 1.5M S 0:0 /local0/dougm/apps/httpd-2.0.54/bin/httpd
In this example, the first branch of the query, 'State.Name.eq=httpd' will match several processes. The second branch, 'State.Name.Pne=httpd', only matches if the State.Name of the parent process is NOT equal to httpd.
The hardcoded string 'httpd' in the second branch can be replaced with the special variable $1, which is the return value of the attribute (State.Name) in the first branch of the query:
sigar> ps "State.Name.eq=httpd,State.Name.Pne=$1" 6807 dougm 15:10 2.6M 2.6M 1.5M S 0:0 /local0/dougm/apps/httpd-2.0.54/bin/httpd
Let's say we change the query to where the first branch matches a certain username (CredName.User), with State.Name moving to the second branch, we then need to use '$2' to get the return value of State.Name:
sigar> ps "CredName.User.eq=dougm,State.Name.eq=httpd,State.Name.Pne=$2" 6807 dougm 15:10 2.6M 2.6M 1.5M S 0:0 /local0/dougm/apps/httpd-2.0.54/bin/httpd
Use of these variables is particularly useful when combined with our regex to find the parent process of any Apache flavor:
sigar> ps "State.Name.re=^(https?d.*|[Aa]pache2?)$,State.Name.Pne=$1" 6807 dougm 15:10 2.6M 2.6M 1.5M S 0:0 /local0/dougm/apps/httpd-2.0.54/bin/httpd
'State.Name' may be enough to identify certain processes, but this is almost never the case with java applications, where the executable basename is 'java' for all applications:
sigar> ps "State.Name.eq=java" 3872 dougm 16:12 241M 330M - R 6:8 java:org.jboss.Main 3888 dougm 16:15 211M 208M - R 7:33 java:com.ibm.ws.bootstrap.WSLauncher 6060 dougm 11:24 12M 12M - R 0:0 java:net.hyperic.sigar.cmd.Runner
The results are 3 processes: a JBoss server, a WebSphere server and the sigar shell itself.
Hey, why didn't eclipse show up in the listing? If you are on windows, certain java applications will use 'javaw' rather than 'java', simply adjust the query to use the 'sw' operator to match both:
sigar> ps "State.Name.sw=java" 3872 dougm 16:12 241M 330M - R 8:28 java:org.jboss.Main 3888 dougm 16:15 211M 208M - R 2:51 java:com.ibm.ws.bootstrap.WSLauncher 4232 dougm 09:26 154M 150M - R 3:13 javaw:org.eclipse.core.launcher.Main 3772 dougm 13:38 12M 12M - R 0:0 java:net.hyperic.sigar.cmd.Runner
To view the command line arguments for a specific process:
sigar> pargs 3872 pid=3872 exe=C:\j2sdk1.4.2_04\bin\java.exe cwd=D:\jboss\bin 0=>C:\j2sdk1.4.2_04\bin\java<= 1=>-Dprogram.name=run.bat<= 2=>-Xms128m<= 3=>-Xmx512m<= 4=>-Djava.endorsed.dirs=d:\jboss\bin\..\lib\endorsed<= 5=>-classpath<= 6=>C:\j2sdk1.4.2_04\lib\tools.jar;d:\jboss\bin\run.jar<= 7=>org.jboss.Main<=
For most java applications, the main class name can be used to uniquely identify the process, in this case argument 7 is the JBoss main class name:
sigar> ps "State.Name.eq=java,Args.7.eq=org.jboss.Main" 3872 dougm 16:12 241M 330M - R 6:27 java:org.jboss.Main
Using the exact argument may not work depending on how the server is configured. Another alternative is to use -1, which means the last argument:
sigar> ps "State.Name.eq=java,Args.-1.eq=org.jboss.Main" ...
Again, this approach can also fall apart if there are arguments after the main class, using * will match any of the command line arguments:
sigar> ps "State.Name.eq=java,Args.*.eq=org.jboss.Main" ...