Introduction
GENEOS UNIVERSAL Processes Plug-in monitors instances of running processes.
This plug-in allows a configurable list of processes to be monitored. Options exist to manually stop or start a process, automatically restart the process, and to view an associated 'LOG' file. It is possible to restrict this functionality to specific user groups.
Views
The GENEOS UNIVERSAL Processes Plug-in produces a single view. This will always show the process name and instance count, and if the monitored host is running Solaris 2.6 or higher, can display additional process details.
Standard view
The standard view shows each name that has been defined within the PROCESS_LIST section for that host, and the number of occurrences found that match the string specified in the PROC_DESCRIPTOR section - see the "Plug-in configuration " section of this manual.
Rules need to be applied to the processes instance count to check that the required number of instances are running, and can be set to alert if more or less than the expected number of instances are found, see the "Suggested Rules" section of this manual.
Note: An alert will NOT be raised if a process fails unless a rule has been set to watch for process instance counts - in this case the instanceCount column will remain grey.
Expanded view
The Expanded view will display a default set of expanded details, as shown, and can be further configured to display additional details as described in the table below:
| Name | Description | |
|---|---|---|
| processName |
The name of the proc_descriptor. Note If there is more than one instance of a process, then the view will also show numbered instances, e.g.process_name#002, process_name#003 etc. |
Standard |
| instanceCount | The number of instances of each monitored proc_descriptor. | Standard |
| percentCPU | % of recent cpu used by this process instance. | Basic expanded option |
| percentMemory | % of system memory used by this process instance. | Basic expanded option |
| residentSetSize | Resident size set of this process instance. | Basic expanded option |
| virtualMemory | Virtual memory size of this process instance. | Basic expanded option |
| startTime | The time this process instance started. | Basic expanded option |
| user | The Unix Userid that started this process instance. | Additional expanded option |
| groupId |
The Unix Groupid of this process instance. Note If an error occured while acquiring the groupId of this process, 'N/A' will be displayed. |
Additional expanded option |
| processId | The Unix PID number of this process instance. | Basic expanded option |
| parentProcessId | The PID number of the parent process. | Additional expanded option |
| args | The command line arguments of this process instance. | Basic expanded option |
| numThreads | Number of threads being used by this process instance. | Basic expanded option |
| state | The current state of this process instance e.g Running, Sleeping etc. | Additional expanded option |
| ageHours | The number of hours that the process has been running. | Additional expanded option |
| ageDays | The number of days that the process has been running. A process started at one minute to midnight will show as as 1 day at one minute past midnight, even though AgeHours will be 0. | Additional expanded option |
| solarisZone | The zone in which the process is running. | Additional expanded option |
| latency | CPU latency or wait time. The percentage of time the process spent waiting for CPU. | Additional expanded option |
Plug-in Configuration
var-displayMode
If set to 'summary', each process will have a single row summarising the process, showing number of instances, CPU and memory usage only. If set to 'details', the process will show all the instances. If set to 'summary+details' then both will be shown
displayMode
Deprecated - use var-displayMode
If set to 'summary', each process will have a single row summarising the process, showing number of instances, CPU and memory usage only. If set to 'details', the process will show all the instances. If set to 'summary+details' then both will be shown
processParameters
Defines the parameters (process attributes) to be shown for each process monitored. To disable this mode, set the environment variable SOLARIS_OS_DIRECT to FALSE in the start_netprobe script.
The available process parameters for Unix are:
| Parameter | Description |
|---|---|
| pcpu | % of recent cpu |
| pmem | % of system memory |
| vsz | virtual memory size |
| rss | resident size set |
| time | uptime |
| user | user id |
| group | group id |
| pid | process id |
| ppid | parent process id |
| pscpu | % of recent cpu multiplied by the number of active cpu's on the server |
| args | command line args |
| nlwp | number of threads |
| state | process state, running, sleeping etc. |
| ageh | age of the process in hours |
| aged | age of the process in days |
| agem | age of the process in minutes |
| fd | File descriptors |
| Cputime | the cumulative CPU time of the process in the form [[dd-]hh:]mm:ss |
| Scputime | the cumulative CPU time of the process in seconds |
| szone | Solaris zone - will display the zone that the process is running in on Solaris 10 onwards. |
| latency | CPU latency or wait-time. The percentage of time the process has spent waiting for CPU. Available on Solaris when microstate accounting is enabled. |
The available process parameters for Windows are:
| Parameter | Description |
|---|---|
| pcpu | % of recent cpu time |
| user | % user time |
| priv | % privileged time |
| vszp | Virtual bytes peak |
| pagef | Page faults per sec |
| rssp | Working set peak |
| rss | Working set |
| pfkbp | Page file bytes peak |
| pfkb | Page file bytes |
| nlwp | Thread count |
| prior | Priority base |
| etime | Elapsed time |
| pid | Process id |
| poolp | Pool paged bytes |
| poolnp | Pool non paged bytes |
| pscpu | % of recent cpu multiplied by the number of active cpu's on the server |
| handles | Handle count |
| ppid | Creating process id |
| prikb | Private bytes |
| args | command line args |
| gdi | GDI object count |
| uname | User name |
| ageh | age of the process in hours |
| aged | age of the process in days |
| agem | age of the process in minutes |
| vsz | virtual memory size |
| pmem | percentage of working set memory used by this process |
| imageName | The name of the process or executable |
Note: (For fd usage) If the NetProbe doesn't have root permissions it will only be able to read file descriptor counts for processes running as the same user as the NetProbe.
The summary line will always show the totals for the following columns:
| Column | Totals |
|---|---|
| pcpu | always |
| pmem | always |
| vsz | always |
| rss | always |
| user | if all the users are the same |
| pid | minimum pid if all are threads of the same process (Linux only) |
| nlwp | always |
| args | always |
adjustForLogicalCPUs
Adjusts the summary and detail view of each process to calculate the percentage based on the number of logical cpus.
Note: This is only valid for Solaris/Linux platforms.
adjustForLogicalCPUsSummary
Adjusts the summary view of each process to calculate the percentage based on the number of logical cpus.
Note: This is only valid for Solaris/Linux platforms.
wideProcessSupport
If a unique process name is greater than 75 chars long then wide process name monitoring will come into effect. If the process is owned by the same user as the NetProbe process then the wide process name will be looked up directly. If not then the NetProbe will obtain this information by running /usr/ucb/ps -axww.
There is an additional processing overhead of retrieving long process names with the ps command, but once the name has been retrieved it will be cached on the NetProbe for efficiency.
Wide process name support is only valid for SOLARIS_DIRECT enabled NetProbes.
To change the command used to retrieve long process names (e.g. /usr/ucb/ps -axww), set the wideProcessListCommand in the advanced tab of the probe:
Note: In case of wide process names, Solaris kernel will strip the full path to the process name. This means that the full path should not be used in the ID= .
cacheWideProcessNames
Stores the wide process names in memory so it does not have to be looked up again. This flag is only used in machines running Solaris and AIX.
Mandatory: No
psinfo64
This is an external Solaris application that is used to get the 64-bit values for Resident Set Size and Virtual Memory Size and pass them to the Netprobe.
regexMode
There are five regex modes to select from: berkeley, extended, none, PCRE and normal. For a complete reference of how to write regular expressions for a particular node see below:
- Berkeley
- The regular expression is executed using the Berkeley library interface. On some platforms this may make a difference to the pattern matching algorithm. It is highly recommend you use one of the other modes unless you have a specific reason for choosing this one.
- Normal
- These use the POSIX regular expression syntax.
- Extended
- These use the POSIX extended regular expression syntax.
- PCRE
- These use Perl compatible regular expression syntax.
- None
- The text is searched for in the string as is. This is a case insensitive search by default.
argsMaxLength
This option sets the length of characters to be displayed for the process' arguments. The minimum possible value is set at 8.
processes > process > data
Defines a single process to be monitored. The details can either be defined in the sampler or in an external processDescriptor section in the "Static Vars" section of the setup file.
alias
The alternate name of the process (this could replace a process name with a regular expression so it is more readable). This serves as a unique identifier for the process.
Mandatory: Yes
ID
A unique case sensitive string that will identify the process in the UNIX ps command output.
Mandatory: No
ID > rules
Describes how the search string should match. The choices are as follows:
- atEndOfLine - matches the search string against the end of the process name. That is, if the search string is "option3" and the process name is java myjar.jar -option1 -option2 -option3, then they will match.
- basic/regex - see regexMode for a detailed of how this choice works.
- exact - matches the search string for every character of the process name.
Mandatory: No
Note: If Rules is not set, then the search string can match any substring of the process name. For example, if the search string is option and the process name is java myjar.jar -option 1 -option 2 - option 3, then the process will return as a match to the search string.
parentID
A unique case sensitive string that will identify the parent process in the UNIX ps command output.
Mandatory: No
parentID > rules
Describes how the search string should match. The choices are as follows:
- atEndOfLine - matches the search string against the end of the process name. That is, if the search string is "option3" and the process name is java myjar.jar -option1 -option2 -option3, then they will match.
- basic/regex - see regexMode for a detailed of how this choice works.
- exact - matches the search string for every character of the process name.
Mandatory: No
Note: If Rules is not set, then the search string can match any substring of the process name. For example, if the search string is option and the process name is java myjar.jar -option 1 -option 2 - option 3, then the process will return as a match to the search string.
start
UNIX script or NT batch to run in order to start this process - should include the full path.
Mandatory: No
stop
UNIX script or NT batch run in order to stop this process - should include the full path.
Mandatory: No
logFile
The full path to the process's log file.
The log file may be specified with a wild card '*' , in which case the latest modified file that matches the filespec will be selected.
An option to "View <name> log file" is presented by the right mouse button when you click on the Process name or Instance count in the Active Console PROCESSES view, and will cause a pop-up window to appear with options for a snapshot or continuous display of the file, and filtering.
Up to 30kb of the file can be displayed initially, although by default the first 2Kb of the file will be displayed.
Mandatory: No
restart
When a process is not running, Geneos will try to restart it, every minute, up to the number of times specified by numberOfTries. Geneos will try no more than this number of times within the time period specified by setBackTime in seconds.
Restart runs the script declared as the start script for the process.
Mandatory: No
restart > numberOfTries
Geneos will try no more than this number of times within the time period specified by setBackTime in seconds.
Mandatory: Yes
restart > setBackTime
After this period of time in seconds geneos will try to restart any stopped processes for which restart is set.
e.g. is number of tries is 3 and set back time is 3000 Geneos will make 3 attempts (roughly every sixty seconds) to restart the process. After which it will stop until 3000 seconds have elapsed. It will then try again a further three times if the process is not running.
Mandatory: Yes
restart > retryPeriod
By default if a process stops running and retry is configured, the netprobe will try to restart the process every sixty seconds. This happens up to the number of configured retries until the set back time has elapsed where it tries again.
The optional retry period allows process restart attempts to occur more frequently for a process descriptor. For example there may be a process that should be restarted immediately or after twenty seconds and then at twenty second intervals.
The netprobe will attempt to restart the process after retry period seconds and if unsuccessful will retry every retry period seconds.
Values outside the range of one to fifty nine seconds are ignored.
Mandatory: No
restart > activeTime
Specifies an activeTime to associate with the restart. The restart will not be attempted if the specified activeTime is not currently active.
Note: This feature requires the Gateway Controlled Probe ActiveTimes to be enabled. See the GW2 reference guide for more details on this setting.
Mandatory: No
groups
Allow only the users in the specified groups to be able to view the log file of the process and Start/Stop the process.
ignoreIDs
Allows hiding of processes based on a search string that matches the process command line.
Mandatory: No.
ignoreIDs > rules
Describes how the search string should match. The choices are as follows:
- atEndOfLine - will match the search string against the end of the line e.g. if the process name is java myjar.jar -option1 -option2 -option3 and the search string is option3 it will match.
- basic/regex - see regexMode for a detailed of how this choice works.
- exact - the search string has to match character for character with the process name.
Mandatory: Yes
processes > process > processDescriptor
This allows a process description to use a shared definition stored in the "Static Vars" section. An external section is either used to share a processDescriptor between two different process samplers, or to allow a processDescriptor to be shared between a process sampler and an FKM sampler. (FKM samplers can use a processDescriptor to define the location of a log file to monitor associate with a process).
processDescriptor > name
The name by which the process descriptor is referenced from a sampler.
Mandatory: Yes
processDescriptor > alias
The alternate name of the process (this could replace a process name with a regular expression so it is more readable). It is good practice to uniquely name process descriptor aliases to avoid confusion.
Mandatory: Yes
processDescriptor > ID
A unique case sensitive string that will identify the process in the UNIX ps command output.
Mandatory: No
processDescriptor > ID > rules
Describes how the search string should match. The choices are as follows:
- atEndOfLine - will match the search string against the end of the line e.g. if the process name is java myjar.jar -option1 -option2 -option3 and the search string is option3 it will match.
- basic/regex - see regexMode for a detailed of how this choice works.
- exact - the search string has to match character for character with the process name.
Mandatory: No
processDescriptor > parentID
A unique case sensitive string that will identify the parent process in the UNIX ps command output.
Mandatory: No
processDescriptor > parentID > searchString
The name of the process to be searched for.
Mandatory: Yes
processDescriptor > parentID > rules
Describes how the search string should match. The choices are as follows:
- atEndOfLine - will match the search string against the end of the line e.g. if the process name is java myjar.jar -option1 -option2 -option3 and the search string is option3 it will match.
- basic/regex - see regexMode for a detailed of how this choice works.
- exact - the search string has to match character for character with the process name.
Mandatory: No
processDescriptor > start
UNIX script or NT batch to run in order to start this process - should include the full path.
Mandatory: No
processDescriptor > stop
UNIX script or NT batch run in order to stop this process - should include the full path.
Mandatory: No
processDescriptor > logFile
The full path to the process's log file.
The log file may be specified with a wild card '*' , in which case the latest modified file that matches the filespec will be selected.
An option to "View <name> log file" is presented by the right mouse button when you click on the Process name or Instance count in the Active Console PROCESSES view, and will cause a pop-up window to appear with options for a snapshot or continuous display of the file, and filtering.
Up to 30kb of the file can be displayed initially, although by default the first 2Kb of the file will be displayed.
Mandatory: No
processDescriptor > restart
When a process is not running, Geneos will try to restart it, every minute, up to the number of times specified by numberOfTries. Geneos will try no more than this number of times within the time period specified by setBackTime in seconds.
Restart runs the script declared as the start script for the process.
Mandatory: No
processDescriptor > restart > numberOfTries
Geneos will try no more than this number of times within the time period specified by setBackTime in seconds
processDescriptor > restart > setBackTime
After this period of time in seconds geneos will try to restart any stopped processes for which restart is set.
e.g. is number of tries is 3 and set back time is 3000 Geneos will make 3 attempts (roughly every sixty seconds) to restart the process. After which it will stop until 3000 seconds have elapsed. It will then try again a further three times if the process is not running.
processDescriptor > restart > retryPeriod
By default if a process stops running and retry is configured, the netprobe will try to restart the process every sixty seconds. This happens up to the number of configured retries until the setBackTime has elapsed where it tries again.
The optional retry period allows process restart attempts to occur more frequently for a process descriptor. For example there may be a process that should be restarted immediately or after twenty seconds and then at twenty second intervals.
The netprobe will attempt to restart the process after retry period seconds and if unsuccessful will retry every retry period seconds.
Values outside the range of one to fifty nine seconds are ignored.
Mandatory: No
processDescriptor > restart > activeTime
Specifies an activeTime to associate with the restart. The restart will not be attempted if the specified activeTime is not currently active.
Note: This feature requires Gateway Controlled Probe ActiveTimes to be enabled. See the GW2 reference guide for more details on this setting.
processDescriptor > groups
Allow only the users in the specified groups to be able to view the log file of the process and Start/Stop the process.
Mandatory: No
processDescriptor > ignoreIDs
Allows hiding of processes based on a search string that matches the process command line.
Mandatory: No.
processDescriptor > ignoreIDs > searchString
The name of the process to be searched for.
Mandatory: Yes
processDescriptor > ignoreIDs > rules
Describes how the search string should match. The choices are as follows:
- atEndOfLine - will match the search string against the end of the line e.g. if the process name is java myjar.jar -option1 -option2 -option3 and the search string is option3 it will match.
- basic/regex - see regexMode for a detailed of how this choice works.
- exact - the search string has to match character for character with the process name.
Mandatory: Yes
processFilter > parentProcess
To filter by parent process set this equal to a process token which will match the desired process. With the parent process filter enabled it is still possible to view the parent process itself if desired.
Mandatory: No
lookupUsernames
If username lookup is slowing down the sampler, when using NIS or other remote user lookup, it can be disabled using this parameter. If this is done then the processFilter > usernames should specify a list of user id's rather than user names.
linux > alwaysSampleCPU
This setting currently applies to Linux versions of the plug-in only. Setting this to true will cause the percent CPU utilisation to be calculated on each sample. Doing so may in fact increase CPU utilisation and a warning will be placed in the log file if this is set and the sample interval is less than 4 seconds.
linux > processPollPeriod
This setting currently applies to Linux versions of the plug-in only. This value controls how often in seconds the list of processes are enumerated by the plug-in. Setting this to higher than default value will reduce the overall cpu utilisation when running at high frequency sampling intervals. It may take up to this amount of seconds to detect new processes starting on the machine.
windows > ignoreArgs
When set to TRUE force a process descriptor to match against the process name only, ignoring the arguments.
solaris > zones > filter > allOtherZones
Only processes from zones other than the one in which the probe is run will be collected. This is useful if you are running the probe in the global zone and want to view processes in non-global zones.
solaris > zones > filter > selection > includeOwnZone
Include the zone in which the probe is running in the filter.
solaris > zones > filter > selection > zones
Allows for the specification of individual zones to monitor.
solaris > zones > filter > selection > zones > zone > name
Specify a zone to be added to the filter by name.
solaris > zones > filter > selection > zones > zone > ID
Specify a zone to be added to the filter by zone ID.