--- title: "Processes" description: "" url: "https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/processes/index.html" --- ## Introduction GENEOS UNIVERSAL Processes plugin monitors instances of running processes. This plugin 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. ## Views The GENEOS UNIVERSAL Processes plugin produces a single view. This will always show the process name and instance count. ### Standard view ![Standard view](https://docscdn.itrsgroup.com/geneos/images/plug-ins/processes-standard-dataview.png) 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 [plugin configuration](#plugin-configuration). 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. **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 ![Expanded view](https://docscdn.itrsgroup.com/geneos/images/plug-ins/processes-expanded-dataview.png) 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 | Type | |----|----|----| | processName | The name of the proc_descriptor. **Note** If there is more than one instance of a process, the view will show numbered instances (e.g., process_name#002, process_name#003). | 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 set size 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 User ID that started this process instance. | Additional expanded option | | groupId | The Unix Group ID of this process instance. **Note** If an error occurred while acquiring the groupId, '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). | Additional expanded option | | ageHours | The number of hours the process has been running. | Additional expanded option | | ageDays | The number of days the process has been running. **Note** A process started one minute before midnight will show as 1 day just after midnight. | Additional expanded option | | latency | CPU latency or wait time — the percentage of time the process spent waiting for CPU. | Additional expanded option | ## Plugin configuration ### Basic tab #### 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 variables** section of the setup file. #### alias The alternate name of the process. An alias can be created using regular expression (regex) patterns. 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 **Geneos PCRE2 upgrade** Beginning with version 7.3.x, Geneos now uses `PCRE2 10.44` by default, upgrading from `PCRE 8.44` for improved handling of regular expressions. Please be aware that this may introduce breaking changes to your implementation. For more information about the differences, refer to the [PCRE2 documentation](https://www.pcre.org/current/doc/html/pcre2compat.html). 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 - 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*](#regexmode) for a detailed of how this choice works. - exact - matches the search string for every character of the process name. Mandatory: No 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 > searchString **Geneos PCRE2 upgrade** Beginning with version 7.3.x, Geneos now uses `PCRE2 10.44` by default, upgrading from `PCRE 8.44` for improved handling of regular expressions. Please be aware that this may introduce breaking changes to your implementation. For more information about the differences, refer to the [PCRE2 documentation](https://www.pcre.org/current/doc/html/pcre2compat.html). 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 - 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*](#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 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. Mandatory: No **Note** This feature requires the Gateway Controlled Probe ActiveTimes to be enabled. See the GW2 reference guide for more details on this setting. #### groups **Note** This field is now deprecated beginning Geneos 7.1.0. 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*](#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 variables** section of the setup file. 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. An alias can be created using regular expression (regex) patterns. 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*](#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*](#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 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 **Note** This field is now deprecated beginning Geneos 7.1.0. 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*](#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 ### Advanced tab **Warning** Some configuration options are specific to legacy Solaris support and are ignored on currently supported platforms. This includes [wideProcessSupport](#wideprocesssupport), [psinfo64](#psinfo64), and [solaris-specific options](#solaris). #### 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 **Note** This setting is deprecated. Use the [**var-displayMode**](#var-displaymode) setting instead. 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. You can set processParameters using a stringList. For more information, see [environments > environment > var > stringList in User Variables and Environments](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway-administration/gateway_user_variables_and_environments/index.html#environments--environment--var--stringlist). The available process parameters for Unix are: | Parameter | Description | |----|----| | pcpu | % of recent CPU | | pmem | % of system memory | | vsz | Virtual memory size | | rss | Resident set size | | 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 CPUs on the server | | args | Command line arguments | | nlwp | Number of threads | | state | Process state (e.g., 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 | Cumulative CPU time of the process in the form `[[dd-]hh:]mm:ss` | | Scputime | Cumulative CPU time of the process in seconds | | latency | CPU latency or wait time — percentage of time the process has spent waiting for CPU. | 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 file descriptors: 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 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 Linux platforms. Mandatory: No Default: True #### showProcessDetails Shows process details. Mandatory: No Default: True #### wideProcessSupport **Warning** This setting is specific to legacy Solaris support and is ignored on currently supported platforms. 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 AIX. Mandatory: No #### psinfo64 **Warning** This setting is specific to legacy Solaris support and is ignored on currently supported platforms. 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 #### 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 #### 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 usernames to filter by. Each filter uses exact or normalized matching. You can enter multiple comma-separated values, and these will be evaluated with multi-token OR logic. The input filter must be valid to ensure filtering works correctly: | Input filter | Example | Result | |-------|-------|-------| | (empty) | | No filtering is applied. All processes are displayed. | | Single valid username | `admin` | Only processes owned by that user are displayed. | | Multiple valid usernames | `admin, root` | Only processes owned by the specified users are displayed. | | Single invalid or non-existent username | `nonexistent` | No processes are displayed. | | Mix of valid and invalid usernames | `admin, nonexistent` | Only processes owned by valid users are displayed. In this example, only processes owned by `admin` will be displayed. | | All invalid or non-existent usernames | `nonexistent, ghost` | No processes are displayed. | | Case differences | `admin` vs. `Admin` | Matching depends on platform rules: - Windows — case-insensitive - Unix — case-sensitive | | Extra spaces | `admin , root` | Filters are trimmed, and valid users will match as expected. | | Windows: Domain and username | `DOMAIN\user` | Matches processes for the domain user | | Windows: UPN | `user@domain.com` | Matches processes for that user (normalized to the correct account). | | Windows: Domain only (with backslash, case-insensitive) | `DOMAIN\` | Displays all processes within that domain. | Mandatory: No #### processFilter > userIDs Specify a list of Unix user IDs to filter by. Mandatory: No #### regexMode There are five regex modes to select from: `Berkeley`, `Extended`, `None`, `PCRE Perl Compatible`, 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 Perl Compatible **Geneos PCRE2 upgrade** Beginning with version 7.3.x, Geneos now uses `PCRE2 10.44` by default, upgrading from `PCRE 8.44` for improved handling of regular expressions. Please be aware that this may introduce breaking changes to your implementation. For more information about the differences, refer to the [PCRE2 documentation](https://www.pcre.org/current/doc/html/pcre2compat.html). - These use Perl Compatible Regular Expression (PCRE2) 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 #### Options Specify options for Linux or Windows. #### linux Allows settings specific to the Linux processes plugin. #### linux > alwaysSampleCPU This setting currently applies to Linux versions of the plugin 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 plugin only. This value controls how often in seconds the list of processes are enumerated by the plugin. 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 plugin. #### 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 **Warning** These settings are specific to legacy Solaris support and are ignored on currently supported platforms. Allows settings specific to the Solaris processes plugin. #### 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//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