Command Line

The purpose of the Command Line Monitor is to run commands or in-house scripts and analyze their result on a regular basic.

To monitor commands or in-house scripts, Monitoring Studio X needs:

  • the command line to be executed. It can either be a shell command, a shell script, or an executable file with arguments. A file containing the command to execute can also be referred to with the %{FILE:<filename>} macro. Refer to Embedded Files for more details.
  • the credentials required to run the command.

By default, the specified command line is executed on the monitored Host. The command line can contain the macros below:

  • %{TIME:<date-time-format>}, which will be replaced at run-time with the current date and time. Refer to Time and Date Formats for Macros for more details.
  • %{LASTTIME:<date-time-format>}, which will be replaced at run-time with the date and time at which the command was last executed. This macro is useful to specify a time range for the command, like listing events since the last time you checked. When using this macro, the execution is skipped entirely the first time the Monitor runs (after the PATROL Agent starts). This is to ensure that an actual date and time is inserted with an actual value for this macro.
  • %{FILE:<filename>}, which will be replaced by the path to the corresponding Embedded File, stored in a temporary location at run time. Refer to Embedded Files for more details.

When the command is executed on the agent system, you can use the following macros:

  • %{HOSTNAME}, which will be replaced at run-time with the hostname of the monitored host
  • %{USERNAME}, which will be replaced at run-time with the username of the selected credentials
  • %{PASSWORD}, which will be replaced at run-time with the password of the selected credentials. User-defined %{...PASSWORD} macros will also be replaced with the decrypted password.

Example: WMIC /NAMESPACE:\\%{HOSTNAME}\root\cimv2 /USERNAME:%{USERNAME} /PASSWORD:%{PASSWORD} CPU

The password being inserted in clear text, it may be visible in command-lines and in debug files to non-root users. Use at your own risk.

You can specify how Monitoring Studio X will determine whether the command executed successfully with:

  • a regular expression that must be found in the output of the command (e.g. the ping command must contain Pinging)
  • exit codes that mean the command succeeded (typically with exit code 0)

When the command is successfully executed, Monitoring Studio X provides the execution time, the exit code returned, the exit status, and the result of the command line.

If the command is not successful, Monitoring Studio X will either trigger an alert on the Status parameter of the Monitor or report execution errors in the Collection Error Count parameter of the Template. Other parameters will not be collected and the output of the command will not be parsed with the String Searches, Numeric Value Extractions, etc.

The result of the command line can also be analyzed through a wide range of tools (Dynamic Object, Numeric Value Extraction, Text Pre-Processing, String Search, and Value Map).

Refer to the table below to know how to configure the Command Line Monitor:

Property Description
Command Line Command line to be executed.
Execute as (Only when command is run on the host) Credentials required to execute the command line on the host. By default, System Credentials are used.
Set %{USERNAME} And %{PASSWORD} With (Only when command is run on the Agent) Credentials available through the %{USERNAME} and %{PASSWORD} macros in the command line executed on the Agent (Example: isql -U %{USERNAME} -P %{PASSWORD} "SELECT * FROM sysprocesses"). The command will be executed as the default PATROL Agent user.
Run this Command on the Monitored Host or Agent system? Host on which the command will be run (HOST or AGENT). When the command is run on the Agent, you will have to set the credentials to be used through the %{USERNAME} and %{PASSWORD} macros.
Display Name Name to identify the Command Line Monitor instance in TrueSight Operations Management.
Internal ID ID to be used to store the Command Line configuration in the PATROL Agent configuration. This Internal ID is automatically generated based on the Display Name provided but can be edited if needed.
Collect Schedule How often new data is collected. A new collect can be performed from once every second, to once in a day. By default, the collect schedule is set to 2 minutes.
Command Output Should Contain Regular expression to be found in the command output for the command to be considered successful. If not found, the Status attribute of the Command Line Monitor is automatically set to 2 (Failed). This option helps ensure command has been properly executed and avoid false alerts on the associated String Search/Numeric Value Extraction.
Timeout After Time in seconds after which the command line will be stopped (Default: 30 seconds). If the command times out, the Status parameter of the Monitor will be set to 2 (Failed) and an alarm will be triggered, or the Template's Collection Error Count will be increased by ‘1’.
Command Exit Code Exit codes that will indicate whether the command was successfully executed or failed. Select No Validation if you do not wish to validate the command execution.

Once you are done with the configuration, you can run a Dry Run to trigger the execution of this command line on a specific host and therefore verify that the output is conform to the expected result.

Finally, you can define where alerts are reported, the threshold alert values, and the alert severity levels for the Monitor:

  • Indicate if you want Monitoring Studio X to report Monitor Errors in The Monitor's Status Parameter or The Template's Collection Error Count Parameter (default).

  • Then, for each parameter, define up to three alarm ranges (Alarm #1, Alarm #2 and Out-of-range) each with a minimum and a maximum value:

    • Use the Alarm #1 and Alarm #2 options to define the range of parameter values that triggers warnings and alarms.
    • Use the Out-of-range border conditions to be informed when the collected values are outside the norm (less than or greater than the defined range limits).

Refer to the Configuring Alerts for details and to Studio Command Line for more information about the parameters available and the thresholds set by default.

Keywords:
studio km patrol develop web
No results.