APIs in Category: perf
 API version 1.6

 
perf-object-counter-list-info
perf-object-get-instances
perf-object-get-instances-iter-end
perf-object-get-instances-iter-next
perf-object-get-instances-iter-start
perf-object-instance-list-info
perf-object-instance-list-info-iter-end
perf-object-instance-list-info-iter-next
perf-object-instance-list-info-iter-start
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
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.
instances instance[]
optional
List of instances to get counter values for. This element can be used to limit data collection to a specified subset of the instances of the object. If this element is absent, counter values of all instances of the object will be retrieved.
objectname string
Name of the object to get counter values for.
 
Output Name Range Type Description
instances instance-data[]
List of instances of the object. Each element of this list contains the counter values of a single instance of the object at the time of the call.
timestamp string
Timestamp in seconds since January 1, 1970.

 
perf-object-get-instances-iter-end [top]
Terminate a perf-object-get-instances iterator.
Input Name Range Type Description
tag string
Tag from a pervious perf-object-get-instances-iter-start

 
perf-object-get-instances-iter-next [top]
Continue retrieving the values of counters of instances of an object. This call will return a partial list instance names, continued from the previous call with the same tag. When the 'records' output element is 0, all counter values of all instances have been retrieved and the perf-object-instance-list-info-iter-end API should be called.
Input Name Range Type Description
maximum integer
Maximum number of entries to retrieve with this call.
Range: [0..2^31-1]
tag string
Tag from a previous perf-object-get-instances-iter-start
 
Output Name Range Type Description
instances instance-data[]
Partial list of instances of the object. Each element of this list contains the counter values of a single instance of the object at the time perf-object-get-instances-iter-start was called.
records integer
Number of records returned by this call to perf-object-instance-info-iter-next. A value of 0 indicates all counter values of all instances have been returned.
Range: [0..2^31-1]

 
perf-object-get-instances-iter-start [top]
Begin retrieving the counter values of instances of an object. This call should be followed with one or more calls to perf-object-get-instances-iter-next
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.
instances instance[]
optional
List of instances to get counter values for. This element can be used to limit data collection to a specified subset of the instances of the object. If this element is absent, counter values of all instances of the object will be retrieved.
objectname string
Name of the object to get counter values for.
 
Output Name Range Type Description
records integer
Number of items that have been saved for future retrieval with perf-object-instance-list-info-iter-next.
Range: [0..2^31-1]
tag string
Tag to be used in subsequent calls to perf-object-get-instances-iter-next
timestamp string
Timestamp in seconds since January 1, 1970.

 
perf-object-instance-list-info [top]
Get the list of names of current instances of an object. This will return the names of all current instances of the specified object with one call. If the object is expected to have a large number of instances, the iterator version of this API should be used.
Input Name Range Type Description
objectname string
Name of the object to get instance information for.
 
Output Name Range Type Description
instances instance-info[]
Array of names of current instances of the object.

 
perf-object-instance-list-info-iter-end [top]
Terminate a perf-object-instance-list-info iterator.
Input Name Range Type Description
tag string
Tag from a previous perf-object-instance-list-info-iter-start

 
perf-object-instance-list-info-iter-next [top]
Continue retrieving the names of instances of an object. This call will return a partial list instance names, continued from the previous call with the same name. When the 'records' output element is 0, all instance names have been retrieved and the perf-object-instance-list-info-iter-end API should be called.
Input Name Range Type Description
maximum integer
Maximum number of instance names to retrieve with this call. Range: [0..2^31-1]
tag string
Tag from earlier call to perf-object-instance-list-info-iter-start
 
Output Name Range Type Description
instances instance-info[]
Partial list of names of instances of the object at the time perf-object-instance-list-info-start was called.
records integer
Number of records returned by this call to perf-object-instance-info-iter-next. A value of 0 indicates all instances have been returned.
Range: [0..2^31-1]

 
perf-object-instance-list-info-iter-start [top]
Begin retrieving the names of instances of an object. This call should be followed with one or more calls to perf-object-instance-list-info-iter-next
Input Name Range Type Description
objectname string
Name of the object to get instance information for.
 
Output Name Range Type Description
records integer
Number of items that have been saved for future retrieval with perf-object-instance-list-info-iter-next.
Range: [0..2^31-1]
tag string
Tag to be used in subsequent calls to perf-object-instance-list-info-iter-next

 
perf-object-list-info [top]
Get list of performance objects in the system.
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
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.
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
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

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

 
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: 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]