Processes Plug-in - Technical Reference

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

Mandatory: No
Default: summary+details

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

Mandatory: No
Default: summary+details

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.

Mandatory: No
Defaults:
pcpu,rss,pid,nlwp,pmem,vsz,time,args,user (Unix)
pcpu,rss,vsz,pid,handles,args,imageName (Windows)

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.

Mandatory: No
Default: True

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.

Mandatory: No
Default: True

showProcessDetails

Shows process details.

Mandatory: No
Default: True

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= .

Mandatory: No
Default: True

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.

Mandatory: No
Default: getpsinfo64

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.
Mandatory: No
Default: Extended

matchCase

This option sets if the match should be case sensitive or not.

Default: True

argsMaxLength

This option sets the length of characters to be displayed for the process' arguments. The minimum possible value is set at 8.

Mandatory: No
Default: 300

processes > process

Defines a list of processes to be monitored.

Mandatory: No

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 > searchString

The name of the process to be searched for.

Mandatory: Yes

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

parentID

A unique case sensitive string that will identify the parent process in the UNIX ps command output.

Mandatory: No

parentID > searchString

The name of the process to be searched for.

Mandatory: Yes

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

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 > searchString

The name of the process to be searched for.

Mandatory: Yes

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 > searchString

The name of the process to be searched for.

Mandatory: Yes

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

Allows filtering of processes by username and parent process.

Mandatory: No

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

processFilter > usernames

Specify a list of unix usernames to filter by.

Mandatory: No

processFilter > userIDs

Specify a list of unix user id's to filter by.

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.

Mandatory: No
Default: False

Options

Specify options for Linux, Solaris, or Windows.

linux

Allows settings specific to the Linux processes plug-in.

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.

Mandatory: No
Default: False

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.

Mandatory: No
Default: 5

windows

Allows settings specific to the Windows processes plug-in.

windows > ignoreArgs

When set to TRUE force a process descriptor to match against the process name only, ignoring the arguments.

Mandatory: No
Default: False

solaris

Allows settings specific to the Solaris processes plug-in.

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

Allows for the specification of individual zones to monitor.

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

A zone to be included in the filter.

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.

solaris > microstateAccounting

If this setting is enabled then the CPU usage figure will be calculated from the microstate accounting statistics in /proc/<pid>/usage. This is potentially much more accurate than the traditional method.

userCacheMaxAge

This setting specifies the suggested maximum age of the user name cache in seconds. This is checked every sample. If value is less than the sampling interval, cache is reset. If the value is more, the value will be reevaluated on the next sampling.

Mandatory: No
Default: 600 seconds