Request for existing cases, user IDs, Portal navigation support and more
In this guide, we will walk you through the step-by-step process of crafting a personalized metric utilizing an OS command data collector.
The ExecuteOperation data provider carries out a custom operation defined within the SAP Host Agent, wherein an operation comprises a series of commands executed in the specified sequence until either the first failure occurs or the entire set is executed successfully. For more information please refer to ExecuteOperation | SAP Help Portal
The OS ExecuteOperation data provider in SAP Focused Run executes a custom operation defined on the SAP Host Agent. An operation is a set of command, executed in the configured order until the first failure happens, or the complete set was successfully executed.
Parameters:
CUSTOM_OPERATION_NAME: name of the custom operation defined on OS
ELEMENT: can be used for metric grouping (only relevant for "JSON2" return format as a mandatory parameter)
METRIC_NAME: name of the metric
PARAMETERS: optional additional parameters which should be added to the ExecuteOperation command. The parameters and values have to be maintained as a JSON fragment (for example: "SID":"ABC","INSTANCE":"instance_04_abc"). Only supported for JSON/JSON2.
RETURNFORMAT: JSON or EXITCODE
Remark: as of Simple Diagnostics Agent version 1.65.0 several improvements have been done to this data collector:
Unstructured Data (RETURNFORMAT = EXITCODE)
Use Case: Execute a custom operation and check the result of the script. The script result is evaluated by the exit code of the script. This use case only supports the usage of rating and text. For each script execution only one metric can be defined.
EXITCODE = 0 is mapped to green rating
EXITCODE = 1 is mapped to yellow rating
EXITCODE >= 2 is mapped to red rating
Structured Data (RETURNFORMAT = JSON)
Use Case: Collect multiple metrics with the execution of one script. The script needs to provide the result in a JSON format. Each metric is identified by the "name" attribute of the JSON result. The metrics can contain text (type=string) or number values (type=integer) and an optional rating. The floating type is not supported!
{"type":"string", "name":"HealthCheck", "value":"Health check failed", "rating":"3"}
{"type":"integer", "name":"LicenseValidity", "value":"45"}
Within the installation directory of SAP Host Agent, it is possible to configure custom operations. Custom Operations are normally stored in the sub-directory operations.d of the executable directory of SAP Host Agent.
For example on a UNIX system the directory /usr/sap/hostctrl/exe/operations.d/ must be used, which per default does not exist and has to be created.
cd /usr/sap/hostctrl/exe
mkdir operations.d
chown root:sapsys operations.d
chmod 750 operations.d
mkdir %ProgramFiles%\SAP\hostctrl\exe\operations.d
Every custom operation requires a configuration file with .conf extension, e.g. my_custom_operation.conf to be stored under /usr/sap/hostctrl/exe/operations.d (UNIX) directory per default.
The config file has a key/value format. To define a specific command following keys are relevant.
| Key | Restriction | Description |
|---|---|---|
| Name |
| Name of the operation to be passed to ExecuteOperation as name. If this key is not defined, the config file name without .conf will be used. |
Description
|
|
Description of the command
|
Command
|
variable format supported
| Command to be executed. In our case a script namee.g. python /usr/sap/hostctrl/exe/operations.d/custom_operations/custom_script.py |
ResultConverter
|
flat
|
Format of the provided result
|
Platform
|
Windows or Unix
|
|
Remark: the compete list of supported keys can be found on Configure a Custom Operation | SAP Help Portal.
An example of a config file.
Name: exit_code_test
Command: python /usr/sap/hostctrl/exe/operations.d/custom_operations/exit_code.py
Description: Dummy Script with exit code output.
ResultConverter: flat
Platform: Unix
Usually, the scripts are stored under the sub-folders of the operations.d. In our case the directory is called customer_operations.
Below an example of a simple dummy script ending with a certain exit code (in this case 0, which would mean a green rating on the System Monitoring side).
import sys
# Define the exit code
exit_code = 0
# Perform some actions or calculations here
# ...
# Exit with the specified exit code
sys.exit(exit_code)
The custom operation can be tested as follows:
./saphostctrl -function ExecuteOperation -name <CUSTOM_OPERATION_NAME>
Webmethod returned successfully
Operation ID: FA163EDC79981EEEA0F6C20AF98C02FD
----- Response data ----
description=Dummy Script with exit code output.
exitcode=0
Once the script/operation providing an expected result, the next step is to create a custom metric/alert by selecting the OS:ExecuteOperation data provider and maintaining the relevant parameters. This can be either done with the metric creation wizard in System Monitoring Template Maintenance or in Custom Metric Management (part of System Monitoring Advanced Configuration UI).
Example of a python script generating a random value between 1 and 100 and providing an output in a JSON format.
import json
import random
#Generate a random integer
random_int = random.randint(1,100)
# Output the JSON string
print({"type":"integer", "name":"Random", "value":random_int})
Name: random_int
Command: python /usr/sap/hostctrl/exe/operations.d/custom_operations/random_int.py
Description: Dummy Script generating a random integer value with JSON output.
ResultConverter: flat
Platform: Unix
Webmethod returned successfully
Operation ID: FA163EDC79981EEEA0FA09F4336182FD
----- Response data ----
description=Dummy Script generating a random integer value with JSON output.
{'type': 'integer', 'name': 'Random', 'value': 45}
exitcode=0