sentry-processes

Retrieves the process list from a remote sentry.

Command properties

Property	Description
Command type	Transforming
Required permission	Administrator
License usage	N/A
Parallel execution	Supported
Distributed execution	Not supported

Syntax

sentry-processes [timeout=INT]

Options

timeout=INT: RPC timeout in seconds. Accepts a value between 1 and 600. (Default: 30)

Input fields

Field	Type	Required	Description
guid	string	Required	Sentry unique identifier.

Output fields

Field	Type	Description
guid	string	Sentry unique identifier.
pid	integer or string	Process ID.
name	string	Process name.
cpu_usage	integer or string	CPU usage (%).
working_set	long or integer	Memory size (unit: bytes).
_error	string	Error message added to the original record if an error occurs.

The values and types of the pid, cpu_usage, and working_set fields depend on the operating system where the sentry is installed:

Operating system	pid	cpu_usage	working_set
Linux	integer	Always `0` (integer), because CPU usage is not measured.	The VmSize value in `/proc/[pid]/status`, that is, the virtual memory size converted to bytes (long).
Windows	integer	The CPU usage (%) measured over about 0.1 seconds, divided by the number of processors and truncated to an integer (integer). null for a process whose usage could not be measured.	The working set size (long).
AIX, Solaris	string	The %CPU column value in the output of the `ps` command (string).	The VSZ column value in the output of the `ps` command, that is, the virtual memory size in KB multiplied by 1024 (integer).

For the name field, Linux sentries assign the Name value in /proc/[pid]/status, Windows sentries assign the executable file name including the extension, and AIX and Solaris sentries assign the comm column value in the output of the ps command.

HP-UX sentries cannot retrieve the process list, and an error message is assigned to the _error field of the result record.

Error codes

Parsing errors

Error code	Message	Description
23100	no sentry rpc permission	A user without administrator privileges ran the command.
23101	invalid sentry rpc timeout. use timeout between 1 and 600.	The `timeout` option value is not an integer or is outside the range 1–600.

Runtime errors

Errors are returned via the _error field:

Error message	Description
guid is null	The `guid` field value in the input record is null.
guid should be string	The `guid` field value in the input record is not a string.
guid should be non empty string	The `guid` field value in the input record is an empty string.
not connected	The sentry is not connected.
timeout	The RPC request timed out.
disconnected	The sentry connection was already lost when the RPC request was sent.

Other RPC exception messages may be returned depending on the state of the system where the sentry is installed.

Description

The sentry-processes command reads the guid field of each input record, sends an asynchronous RPC message to the corresponding sentry, and retrieves the list of running processes.

Results are returned in the order RPC response messages are received from sentries, so the output record order may differ from the input record order.

The maximum length of the asynchronous RPC request queue is 100 by default and can be adjusted using the logpresso.core.sentry_rpc_parallel environment variable.

To retrieve results from all Data Nodes at once in a cluster environment, use the sonar-sentry-processes command.

Examples

Retrieve the process list from all sentries
```
sentry | fields guid | sentry-processes
```
Retrieves the list of currently running processes from all connected sentries.
Sort by memory size descending
```
sentry | fields guid | sentry-processes | sort -working_set
```
Retrieves the process list from all sentries sorted by memory size in descending order.
Retrieve with a 60-second timeout
```
sentry | fields guid | sentry-processes timeout=60
```
Retrieves the process list from sentries with the RPC timeout set to 60 seconds.

Change history

The sentry-processes command has been available since before Sonar 4.0.