6/04/2020

SAP Operating System Monitoring - APIs

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:
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://: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
  • EnumerateInstances
SAP_ITSAMOperatingSystemProvides operating system data
  • EnumerateInstances
SAP_ITSAMProcessorProvides processor data. An instance for each processor is provided.
  • EnumerateInstances
SAP_ITSAMNetworkPortProvides network interface data. An instance for each network interface is provided.
  • EnumerateInstances
SAP_ITSAMFileSystemProvides file system data. An instance for each file system is provided.
  • EnumerateInstances
SAP_ITSAMSoftwarePackageProvides installed software data. An instance for each installed software package is provided.
  • EnumerateInstances
SAP_ITSAMSoftwarePatchProvides installed patches data. An instance for each installed patch is provided.
  • EnumerateInstances
SAP_ITSAMOSProcessProvides OS process data. An instance for each running process is provided. Returned instances can be filtered as described in Enumerating SAP_ITSAMOSProcess Instances.
  • EnumerateInstances
SAP_ITSAMVirtualComputerSystemProvides virtual computer system data. It will only be provided if the computer system is running in a virtual machine or container.
  • EnumerateInstances
SAP_ITSAMHostComputerSystemDescribes 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.
  • EnumerateInstances
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
CommandLineFilter by CommandLine property. '*' wildcard character can be used to match zero or more characters and '?' to match one character. Can be specified multiple times.
UsernameFilter by Username property. '*' wildcard character can be used to match zero or more characters and '?' to match one character. Can be specified multiple times.
PIDFilter 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 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_MetricDefinitionProvides the meta data of a metric
  • EnumerateInstances
SAP_MetricValueProvides the actual value of a metric. Returned instances can be filtered as described in Enumerating SAP_MetricValue Instances.
  • EnumerateInstances

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.
Needs to be specified in CIM datetime interval format: 00000000000100.000000:000 (1 min, default), 00000000000500.000000:000 (5 min), ...
MetricDefinitionIdFilter 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.
MeasuredElementTypeFilter by measured resource type. Currently, valid types are OperatingSystemDiskFileSystemNetworkPortVirtualComputerSystemHostComputerSystem. '*' wildcard character can be used to match zero or more characters and '?' to match one character. Can be specified multiple times.
MeasuredElementNameFilter 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, ANDOR 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.
wbem: The operating system's WBEM infrastructure (if available) will be used for gathering the computer system data
sapitsam: Computer system data as supplied by the SAP_ITSAM Providers
Please refer to the WSDL of the SAPHostControl Web service for more details on the method signature and data structures (http://:1128/SAPHostControl/?wsdl).
SAP_ITSAM Providers
Instances of the following classes will be provided:
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

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

Operating System Monitoring - APIs

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

No comments:

Post a Comment

Popular Posts