Hyperic 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:
Enclose the query in quotes if it contains any spaces. For example:
- 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:
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:
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:
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:
The easiest way to find the listening sshd server is to use the pid file:
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:
If you happen to be running Cygwin sshd:
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:
Example on a Windows system:
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:
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:
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:
Use of these variables is particularly useful when combined with our regex to find the parent process of any Apache flavor:
'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:
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:
To view the command line arguments for a specific process:
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:
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:
Again, this approach can also fall apart if there are arguments after the main class, using * will match any of the command line arguments: