APIs in Category: perf
 Cluster-Mode API version 1.15

 
perf-object-counter-list-info
perf-object-get-instances
perf-object-instance-list-info-iter
perf-object-list-info
The perf APIs enable monitoring of system performance. They provide a single interface to data across various subsystems in the appliance. Data are organized hierarchically, with objects, instances, and counters. An object generally represents a subsystem, an instance represents a single physical or logical entity within the subsystem, and a counter is a datum specific to the instance.

An example of the object-instance-counter hierarchy is processor:processor0:processor_busy. Each CPU in the system is an instance of the 'processor' object. The processor_busy counter of the processor0 instance reports the time during which this processor has been active since an arbitrary point in the past. A second counter, processor_elapsed_time, reports the total time, so the change in processor_busy divided by the change in processor_elapsed_time over an interval can be used to compute the average utilization of the processor. Processor_elapsed_time is referred to as the 'base counter' of processor_busy since it is needed to compute a useful value from processor_busy.

A typical user of these APIs will initially request a list of objects using the perf-object-list-info call. The user may then request a list of counters available for instances of an object by calling perf-object-counter-list-info for each interesting object. The sets of objects and counters are static, so these calls will not need to be made again.

The core perf API call is perf-object-get-instances. This API returns the names and raw counter values of instances of an object at the time of the call. Unlike objects and counters, the set of instances is not always fixed, and the values of counters will vary across calls. Typically this API must be called at least twice over some interval in order to evaluate subsystem performance during that interval. Depending on counter properties, the user may need to perform additional computation on the raw value in order to correctly interpret it.

Each counter has a property which indicates how it's raw value should be interpreted. This property is available as part of the static counter metadata returned by a call to perf-object-counter-list-info. Possible properties are 'raw', 'rate', 'delta', 'average', 'percent', 'string', and 'no-display'. String counters report textual information, such as volume or disk identifiers. No-display counters are not intended for direct use, and this property is typically assigned to base counters. The other properties are interpreted as follows:

  • raw: single counter value is used
  • delta: change in counter value between two samples is used
  • rate: delta divided by the time in seconds between samples is used
  • average: delta divided by the delta of a base counter is used
  • percent: 100*average is used
For 'average' and 'percent' counters, the 'base-counter' element will be set to the name of the base counter. Some counters are multidimensional, and for these the counter description includes a list of labels of the counter subelements, and a 'type' element indicating the counter is an array.

For example, again consider the processor::processor_busy counter. The description and properties of this counter state that it is a percentage, but a call to perf-object-get-instances will return a raw number which must be further processed by the user. Because the counter is a percentage, the user must note the value of its base counter, (processor::processor_elapsed_time) and then make a second call to perf-object-get-instances and again note the raw value of the counter and base counter. Suppose the user made the calls at time T1 and later at time T2, and these raw values were returned (the object and instance name are not shown):

  • (T1) processor_busy=2000000, processor_elapsed_time=3000000
  • (T2) processor_busy=2400000 ,processor_elapsed_time=4000000
The user must then perform the following computation to determine processor utilization: 100*(2400000-2000000)/(4000000-3000000) = 40%

The perf-object-instance-list-info API may be used to list the names of current instances of an object. It does not return any counter values.

NetApp Manage ONTAP
 
perf-object-counter-list-info [top]

Get information about the counters of an object. This information is static and independent of any particular instance of the object. It includes counter names and descriptions, as well as properties which are necessary to to interpret counter values.
Input Name Range Type Description
filter-data string
optional
A string, representing filter-data, in the format of key=value supporting multiple key-value pairs via comma separation
objectname string
Name of the object to get information for.
 
Output Name Range Type Description
counters counter-info[]
List of counters available for instances of this object.

 
perf-object-get-instances [top]
Get a list of current counter values of instances of an object. This will return the values of all specified counters and instances of the specified object with one call. If the object is expected to have a large number of instances and/or counters, the iterator version of this API should be used.
Input Name Range Type Description
counters counter[]
optional
List of counters whose values will be retrieved. This element can be used to limit data collection to a specified subset of the counters of instances of the object. If this element is absent, values of all counters will be retrieved.
filter-data string
optional
A string, representing filter-data, in the format of key=value supporting multiple key-value pairs via comma separation. The applied filter is a combination of ANDing the key-value pairs.
instance-uuids instance-uuid[]
optional
List of instance UUIDs for which to get counter values. This element can be used to limit data collection to a specified subset of the instances of the object. Either instances or instance-uuids input must be provided. The API errors out if both of these inputs are provided or neither of these inputs is provided, or if more than 100 instances are requested.
instances instance[]
optional
List of instance names for which to get counter values. This element can be used to limit data collection to a specified subset of the instances of the object. In Data ONTAP 7-Mode, counter values of all instances of the object will be retrieved when this element is absent. In Data ONTAP Cluster-Mode, either instances or instance-uuids input must be provided. The API errors out if both of these inputs are provided or neither of these inputs is provided, or if more than 100 instances are requested.
objectname string
Name of the object to get counter values for.
privilege-level string
optional
Name of the privilege level. Possible values: "basic", "admin", "advanced", "diag" If the element is absent, the default privilege of the object will be used.
 
Output Name Range Type Description
instances instance-data[]
List of instances of the object. Each element of this list
timestamp string
Timestamp in seconds since January 1, 1970.

 
perf-object-instance-list-info-iter [top]
Iterate over a list of perf objects.
Input Name Range Type Description
desired-attributes instance-info
optional
Specify the attributes that should be returned. If not present, all attributes for which information is available will be returned. If present, only the desired attributes for which information is available will be returned.
filter-data string
optional
Filter Data
max-records [1..100] integer
optional
The maximum number of records to return in this call. Default: 20
objectname string
Object Name
query instance-info
optional
A query that specifies which objects to return. A query could be specified on any number of attributes in the perf object. All perf objects matching this query up to 'max-records' will be returned.
tag string
optional
Specify the tag from the last call. It is usually not specified for the first call. For subsequent calls, copy values from the 'next-tag' obtained from the previous call.
 
Output Name Range Type Description
attributes-list instance-info[]
optional
The list of attributes of perf objects.
next-tag string
optional
Tag for the next call. Not present when there are no more perf objects to return.
num-records [0..100] integer
The number of records returned in this call.
 Errno  Description
 EINTERNALERROR

 
perf-object-list-info [top]
Get list of performance objects in the system.
Input Name Range Type Description
filter-data string
optional
A string, representing filter-data, in the format of key=value supporting multiple key-value pairs via comma separation
 
Output Name Range Type Description
objects object-info[]
List of performance objects.

 
Element definition: counter [top]
Counter name.
[none]

 
Element definition: counter-info [top]
Information about a single counter.
Name Range Type Description
aggregation-style string
optional
For counters that can be aggregated, this element decribes the style. If the element is absent, no aggregation is available for this counter. Valid values include: [ strict, permissive ]. "strict" aggregation requires all items of a set to perform aggregation. If any item is missing, the aggregation will be rejected. "permissive" aggregation is a best effort aggregation. All available items of a set will be aggregated.
base-counter string
optional
Name of the counter used as the denominator to calculate values of counters involving averages and percentages.
desc string
Description of the counter
labels label-info[]
optional
List of labels of an array type counter.
name string
Name of the counter.
privilege-level string
Privilege level of the counter. Any counter with a privilege level of "diag" is not guaranteed to work, to exist in future releases, or to remain unchanged.
Possible values: basic, admin, advanced or diag.
properties string
optional
Comma separated list of properties of the counter. The counter properties determine how raw counter values should be interpreted.
Possible values: raw, rate, delta, percent, string, no-display and no-zero-values.
translation-input-counter string
optional
Name of counter that is used as input for translation. Translation is needed for some counters because the precise value is unknown at the moment of sampling, and must be determined from another counter at a later time. Note that the time frame is still within a single request and response from the ZAPI client's point of view.
type string
optional
Indicator for whether counter is a scalar or array. If this element is absent,the counter is a scalar.
Possible values: array
unit string
optional
Unit of the counter
Possible values: per_sec, b_per_sec (bytes/s), kb_per_sec (Kbytes/s), mb_per_sec (Mbytes/s), percent, millisec, microsec, sec, or none

 
Element definition: instance [top]
Instance name.
[none]

 
Element definition: instance-data [top]
Instance name and counter values.
Name Range Type Description
aggregation aggregation-data
optional
Information related to aggregation that was done. If element is absent, no aggregation was performed on this instance.
counters counter-data[]
List of counter values of this instance. Each element of this list contains the value of a single counter.
name string
Name of the instance
uuid string
UUID of the instance

 
Element definition: instance-info [top]
Description of an instance of an object.
Name Range Type Description
name string
Name of the instance
uuid string
Name of the instance

 
Element definition: instance-uuid [top]
Instance UUID.
[none]

 
Element definition: object-info [top]
Description of a performance object.
Name Range Type Description
name string
Name of the object
privilege-level string
The object privilege level. Any object with a privilege level of "diag" is not guaranteed to work, to exist in future releases, or to remain unchanged.
Possible values: basic, admin, advanced or diag.

 
Element definition: aggregation-data [top]
Information related to aggregation that was done.
Name Range Type Description
constituent-count [0..2^32-1] integer
optional
Number of constituents used to aggregate this instance.
result string
optional
Each counter for an instance can be part of an aggregation set. Each counter can either have a strict or permissive aggregation. (Basically whether an aggregation with missing data samples in the aggregation set can be considered valid.) Possible values: "complete_aggregation", "incomplete_aggregation" If aggregation is 'strict', and we have all of the data samples, we return: complete_aggregation If aggregation is 'strict' and we DON'T have all of the data samples, we return: incomplete_aggregation If aggregation is 'strict' and we only have one instance (such as a flex vole) we return: complete_aggregation If aggregation is 'permissive', we always return: complete_aggregation. (Since the results are always valid.) NOTE: Since a given node DOES NOT have enough information to determine all of the members of the set, we have to assume if we can't contact a given node/process that may contain a piece to be aggregated, the aggregation is incomplete. (For example, if we're trying to aggregate 'volume' stats, and we can't contact the local dblade or a remote node, we'll mark it as incomplete.)

 
Element definition: counter-data [top]
Value of a single counter of an instance of an object at the time of the call.
Name Range Type Description
name string
Name of the counter
value string
Value of the counter. If the counter type is array, this is a comma separated list of values. The counter properties and units must be known in order to interpret this value. Refer to the perf API discussion for details on how raw counter values are interpreted.

 
Element definition: label-info [top]
Comma separated list of labels of an array type counter.
[none]