Overview
SAP Host Agent provides the following Web service APIs to access operating system data:
Provided data is based on the Common Information Model (CIM). CIM class documentation is available here:
The following documents provide the mapping of the deprecated saposcol-based APIs to the new APIs:
- Mapping of saposcol metrics to SAP_Metric classes
- Mapping of SAP_ComputerSystem data to SAP_ITSAM classes
The saphostctrl command line tool provides convenient methods to access this data:
GetCIMObject API
The GetCIMObject API is a CIM-based API providing access to different information providers. The API is mainly semantic free and returns an array of CIMObject. The method gets parameters as key/value pairs. Every key/value pair represents a method call on a provider. It is also possible to bind more requests together in one Web service call.
Please refer to the WSDL of the SAPHostControl Web service for more details on the method signature and data structures (http://<hostname>:1128/SAPHostControl/?wsdl).
The following groups of operating system classes are supported:
SAP_ITSAM Classes
SAP_ITSAM classes provide access to configuration-like, infrequent changing, data. The following classes are available:
| Classname | Description | Supported method |
|---|---|---|
| SAP_ITSAMComputerSystem | Provides computer system data |
|
| SAP_ITSAMOperatingSystem | Provides operating system data |
|
| SAP_ITSAMProcessor | Provides processor data. An instance for each processor is provided. |
|
| SAP_ITSAMNetworkPort | Provides network interface data. An instance for each network interface is provided. |
|
| SAP_ITSAMFileSystem | Provides file system data. An instance for each file system is provided. |
|
| SAP_ITSAMSoftwarePackage | Provides installed software data. An instance for each installed software package is provided. |
|
| SAP_ITSAMSoftwarePatch | Provides installed patches data. An instance for each installed patch is provided. |
|
| SAP_ITSAMOSProcess | Provides OS process data. An instance for each running process is provided. Returned instances can be filtered as described in Enumerating SAP_ITSAMOSProcess Instances. |
|
| SAP_ITSAMVirtualComputerSystem | Provides virtual computer system data. It will only be provided if the computer system is running in a virtual machine or container. |
|
| SAP_ITSAMHostComputerSystem | Describes a computer system that hosts a SAP_ITSAMVirtualComputerSystem. It will only be provided if the computer system is running in a virtual machine or container. |
|
For detailed documentation of the classes and its properties please refer to SAP CIM Model for Operating System Monitoring.
In case you want to get all data describing the complete computer system you can also use the more convenient GetComputerSystem API.
Enumerating SAP_ITSAMOSProcess Instances
Returned SAP_ITSAMOSProcess instances can be filtered by the following properties:
| Name | Description |
|---|---|
| CommandLine | Filter by CommandLine property. '*' wildcard character can be used to match zero or more characters and '?' to match one character. Can be specified multiple times. |
| Username | Filter by Username property. '*' wildcard character can be used to match zero or more characters and '?' to match one character. Can be specified multiple times. |
| PID | Filter by PID property. Can be specified multiple times. |
Filter properties that can be specified multiple times can also be combined. Per default same filter types are or'ed, different are and'ed. Optionally, the combination operators AND/OR can explicitly be specified. The AND operator has higher precedence than OR.
Filter properties are specified like a URI query, they are introduced with a ? character and separated by an & character.
If a reserved URI character ( '?&%' ) it used in the filter pattern it must be percent-encoded (http://tools.ietf.org/html/rfc3986). For an example please refer to Enumerate processes and filter by a term that contains a reserved URI character.
If the result of an enumeration would exceed 25000 instances an "Not selective enough" exception is returned.
Enumerating Top CPU Consuming SAP_ITSAMOSProcess Instances
By specifying the optional argument topprocesses the top N (default 40) CPU consuming processes will be returned. The topprocesses argument needs to be specified by using two ? characters.
Examples
Enumerate operating system data
Use the following query to enumerate operating system data:
mKey=EnumerateInstances mValue=SAP_ITSAMOperatingSystem
Enumerate file system data
Use the following query to enumerate file system data:
mKey=EnumerateInstances mValue=SAP_ITSAMFileSystem
Enumerate processes that match a single filter term
Simple example to enumerate processes that match a single filter term, the command line contains saphostexec:
mKey=EnumerateInstances mValue=SAP_ITSAMOSProcess?CommandLine=*saphostexec*
Enumerate processes that match multiple filter terms
To enumerate processes that match multiple filter terms, the command line contains sapstartsrv and command is executed by user sapadm:
mKey=EnumerateInstances mValue=SAP_ITSAMOSProcess?CommandLine=*sapstartsrv*&Username=sapadm
Enumerate processes that match multiple filter terms using the AND operator
The previous query can also be specified by explicitly using the AND combination operator:
mKey=EnumerateInstances mValue=SAP_ITSAMOSProcess?&CommandLine=*sapstartsrv*&AND&Username=sapadm
Enumerate processes and combine filter terms using AND/OR operators
More advanced example to filter out processes where the command line contains either saphostexec or sapstartsrv and the latter is executed by the sapadm user:
mKey=EnumerateInstances mValue=SAP_ITSAMOSProcess?CommandLine=*saphostexec*&OR&CommandLine=*sapstartsrv*&AND&Username=sapadm
Enumerate processes and filter by a term that contains a reserved URI character
To filter out processes that are executed in context of any <sid>adm user one could use the filter pattern ???adm. Whereas the ? character denotes a wildcard that matches one character. As the ? character is a reserved URI character is must be percent-encoded as %3F. So the actual query arguments would be:
mKey=EnumerateInstances mValue=SAP_ITSAMOSProcess?Username=%3F%3F%3Fadm
Enumerate the top 40 CPU consuming processes
mKey=EnumerateInstances mValue=SAP_ITSAMOSProcess??topprocesses
Enumerate the top 10 CPU consuming processes
mKey=EnumerateInstances mValue=SAP_ITSAMOSProcess??topprocesses=10
SAP_Metric Classes
These classes provide OS performance metrics.
| Classname | Description | Supported method |
|---|---|---|
| SAP_MetricDefinition | Provides the meta data of a metric |
|
| SAP_MetricValue | Provides the actual value of a metric. Returned instances can be filtered as described in Enumerating SAP_MetricValue Instances. |
|
Enumerating SAP_MetricValue Instances
Returned SAP_MetricValue instances can be filtered by the following properties:
| Name | Description |
|---|---|
| Interval | Filter by interval. There are 5, 15 and 60 minute summation intervals in addition to the 1 minute collection interval. |
| MetricDefinitionId | Filter by MetricDefinitionId e.g. OS.UserTimePercentage. '*' wildcard character can be used to match zero or more characters and '?' to match one character. Can be specified multiple times. |
| MeasuredElementType | Filter by measured resource type. Currently, valid types are OperatingSystem, Disk, FileSystem, NetworkPort, VirtualComputerSystem, HostComputerSystem. '*' wildcard character can be used to match zero or more characters and '?' to match one character. Can be specified multiple times. |
| MeasuredElementName | Filter by MeasuredElementName. '*' wildcard character can be used to match zero or more characters and '?' to match one character. Can be specified multiple times. |
StartTime/EndTime | Filter by time range. Times need to be specified in CIM datetime format. StartTime=0: Only current values are returned (default). StartTime=-1: All available values are returned. |
Filter properties that can be specified multiple times can also be combined. Per default same filter types are or'ed, different are and'ed. Optionally, AND, OR properties can be used to explicitly specify the combination operator. AND has higher precedence than OR.
If the result of an enumeration would exceed 25000 instances an "Not selective enough" exception is returned.
Examples
Enumerate all available metrics
mKey=EnumerateInstances mValue=SAP_MetricValue
Enumerate all metric definitions
mKey=EnumerateInstances mValue=SAP_MetricDefinition
Enumerate overall CPU user and system time
mKey=EnumerateInstances mValue=SAP_MetricValue?MetricDefinitionId=OS.UserTimePercentage&MetricDefinitionId=OS.SystemTimePercentage
Enumerate all metrics of a specified file system
mKey=EnumerateInstances mValue=SAP_MetricValue?MeasuredElementName=/usr/sap/C11
Enumerate all disk metrics
mKey=EnumerateInstances mValue=SAP_MetricValue?MeasuredElementType=Disk
Enumerate available physical memory from the 5 minute interval
mKey=EnumerateInstances mValue=SAP_MetricValue?MetricDefinitionId=OS.AvailablePhysicalMemory&Interval=00000000000500.000000:000
Enumerate all hourly overall CPU idle times from a specific time in the past
mKey=EnumerateInstances mValue=SAP_MetricValue?MetricDefinitionId=OS.IdleTimePercentage&Interval=00000000010000.000000:000&StartTime=20200123080000.000000+120
GetComputerSystem API
The method GetComputerSystem is designed as a commodity function to select from a CIM-based repository all the classes describing the features of the computer system where the SAPHostAgent is running.
The method returns a CIMObject. This represents an instance of CIM_ComputerSystem (or a derived class). The instances of the other classes that describe the computer system are provided as members of the CIM_ComputerSystem instance.
The method accepts the following optional properties as arguments:
Key | Description |
|---|---|
provider | Specifies the providers to be used for gathering the computer system data. |
Please refer to the WSDL of the SAPHostControl Web service for more details on the method signature and data structures (http://<hostname>:1128/SAPHostControl/?wsdl).
SAP_ITSAM Providers
Instances of the following classes will be provided:
- SAP_ITSAMComputerSystem
- SAP_ITSAMOperatingSystem
- SAP_ITSAMProcessor
- SAP_ITSAMNetworkPort
- SAP_ITSAMFileSystem
- SAP_ITSAMVirtualComputerSystem
- SAP_ITSAMHostComputerSystem
SAP_ITSAMVirtualComputerSystem and SAP_ITSAMHostComputerSystem instances will only be provided if the computer system is running in a virtual machine or container. All instances are members of the SAP_ITSAMComputerSystem instance, except SAP_ITSAMHostComputerSystem which is a member of the SAP_ITSAMVirtualComputerSystem instance.
The SAP_ITSAM providers accept the following optional properties as arguments:
Key | Description |
|---|---|
swpackages | Include installed software represented as SAP_ITSAMSoftwarePackage instances. These instances are provided as members of SAP_ITSAMComputerSystem. |
swpatches | Include installed patches represented as SAP_ITSAMSoftwarePatch instances. These instances are provided as members of SAP_ITSAMComputerSystem. |
topprocesses | Include top N (default 40) CPU consuming processes represented as SAP_ITSAMOSProcess instances. These instances are provided as members of SAP_ITSAMOperatingSystem. |
SAP CIM Model for Operating System Monitoring
CIM model for operating system classes is available here. Please download it, extract it and point a browser to the contained index.html.
The saphostctrl Command Line Tool
The saphoctrl command line tool provides a convenient interface for accessing the operating system data. To get the detailed usage you can run the following command, e.g. on Unix:
$ /usr/sap/hostctrl/exe/saphostctrl -help
To get the usage of a specific Web service method:
$ /usr/sap/hostctrl/exe/saphostctrl -help <Webmethod>
Get Computer System Data
The GetComputerSystem function provides the GetComputerSystem API data. To get the complete usage, execute the following command:
$ ./saphostctrl -help GetComputerSystem
Examples
Get the SAP_ITSAM computer system data
$ ./saphostctrl -function GetComputerSystem -sapitsam
Get the SAP_ITSAM computer system data along with the information about installed software
$ ./saphostctrl -function GetComputerSystem -sapitsam -swpackages
List operating system processes
The ListOSProcesses provides the SAP_ITSAMOSProcess data. To get the complete usage, execute the following command::
$ ./saphostctrl -help ListOSProcesses
Examples
Enumerate processes that match a single filter term
Simple example to enumerate processes that match a single filter term, the command line contains saphostexec:
$ ./saphostctrl -function ListOSProcesses -cmd "*saphostexec*"
Enumerate processes that match multiple filter terms
To enumerate processes that match multiple filter terms, the command line contains sapstartsrv and command is executed by user sapadm:
$ ./saphostctrl -function ListOSProcesses -cmd "*sapstartsrv*" -cmduser sapadm
Enumerate processes that match multiple filter terms using the AND operator
The previous query can also be specified by explicitly using the AND combination operator:
$ ./saphostctrl -function ListOSProcesses -cmd "*sapstartsrv*" -and -cmduser sapadm
Enumerate processes and combine filter terms using AND/OR operators
More advanced example to filter out processes where the command line contains either saphostexec or sapstartsrv and the latter is executed by the sapadm user:
$ ./saphostctrl -function ListOSProcesses -cmd "*saphostexec*" -or -cmd "*sapstartsrv*" -and -cmduser sapadm
Enumerate the top 40 CPU consuming processes
$ ./saphostctrl -function ListOSProcesses -top
Enumerate the top 10 CPU consuming processes
$ ./saphostctrl -function ListOSProcesses -top 10
List operating system metrics
The ListOSMetrics provides the SAP_Metric data. To get the complete usage, execute the following command:
$ ./saphostctrl -help ListOSMetrics
Examples
Enumerate overall CPU user and system time
$ ./saphostctrl -function ListOSMetrics -id OS.UserTimePercentage -id OS.SystemTimePercentage
Enumerate all metrics of a specified file system
$ ./saphostctrl -function ListOSMetrics -me /usr/sap/C11
Enumerate all disk metrics
$ ./saphostctrl -function ListOSMetrics -metype Disk
Enumerate available physical memory from the 5 minute interval
$ ./saphostctrl -function ListOSMetrics -id OS.AvailablePhysicalMemory -iv 300
Enumerate all hourly overall CPU idle times from a specific time in the past
$ ./saphostctrl -function ListOSMetrics -id OS.IdleTimePercentage -iv 3600 -start 2020-01-23-08:00:00