Custom OS Script Metric

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

 

Data Collector

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:

  • JSON/JSON2 supports JSON array format
  • element & metric name supports regular expression
  • metric name not relevant for exit code return format and can be left empty

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!

example 
{"type":"string", "name":"HealthCheck", "value":"Health check failed", "rating":"3"}


{"type":"integer", "name":"LicenseValidity", "value":"45"}

Custom Operation

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.

on UNIX 
cd /usr/sap/hostctrl/exe


mkdir operations.d


chown root:sapsys operations.d


chmod 750 operations.d
on Windows 
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.

 

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

exit_code.conf 
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


 

OS Command

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

exit_code.py 
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>

./saphostctrl -function ExecuteOperation -name exit_code_test 
Webmethod returned successfully


Operation ID: FA163EDC79981EEEA0F6C20AF98C02FD


 


----- Response data ----


description=Dummy Script with exit code  output.


exitcode=0

Custom Metric

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

Example of a python script generating a random value between 1 and 100 and providing an output in a JSON format.

random_int 
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})
random_int.conf 
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
./saphostctrl -function ExecuteOperation -name random_int 
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