APIs in Category: perf
 API version 1.9

 
perf-archive-get-headers
perf-archive-get-instances-iter-end
perf-archive-get-instances-iter-next
perf-archive-get-instances-iter-start
perf-archive-get-oldest-timestamp
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.

The perf APIs are divided into two subsets: the perf-object-* calls for real time sampling of the data, and the perf-archive-* calls, which provide access to data which has already been periodically sampled by the data archival subsystem. Subset #1: perf-object-* 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. Subset #2: perf-archive-* Due to the highly complex nature and quantity of the archived data, the expected user of these APIs will be Netapp tools. Use of these APIs requires an understanding of the ondisk, archival data files. The APIs allow users to select time periods from which to retrieve the data. Typically, clients will first issue a single call to perf-archive-get-oldest-timestamp, which returns the timestamp of the oldest archived sample available. Second, clients will issue a call to perf-archive-get-headers, which retrieves formatting and parsing information. These headers correspond to header information which is embedded within each archival data file. Lastly, clients may issue multiple subsequent calls to the perf-archive-get-instances-* iterators. Each call will retrieve archived data instances and return them to the client; since data may be continuously archived as the client is retrieving, the iterators may be used indefinitely. (Iterator tags not used within a one hour period are culled.) Note that the size of the headers and binary data returned may vary depending on the counters being sampled. In any given instance, sampled counters are chosen by two factors: the selection of the counter within a preset file, and the frequency of each counter's sampling rate. Typically, only about 25-30% of the total number of available counters will be archived, so we should not approach maximum sizes.

NetApp Manage ONTAP
 
perf-archive-get-headers [top]

Retrieve all headers available of archive datafiles. This call should be preceded by a call to perf-archive-get-oldest-timestamp, otherwise an error may be returned if the input timestamp is too old.
Input Name Range Type Description
duration integer
Duration in milliseconds to retrieve headers A zero value duration signifies to go until the most recent timestamp. Range: [0..2^31-1]
timestamp string
Timestamp (in seconds, Unix Epoch Time) to start searching for headers. Range: [0..2^31-1]
 
Output Name Range Type Description
archive-headers archive-header[]
Array of "archive-header" strings.

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

 
perf-archive-get-instances-iter-next [top]
Continue retrieving the instances of an archive. When the 'records' output element is 0, all instance data 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 records to retrieve with this call. Range: [0..2^31-1]
tag string
Tag from earlier call to perf-object-instance-list-info-iter-start Note that any tag not used for 1 hour will be deleted.
 
Output Name Range Type Description
archive-records archive-record[]
Array of archive-records data.
generation integer
The generation id for the last header that corresponds to the instances returned. If the generation id has increased from a previous call to perf-archive-get-instances-iter-next, then the data returned may require a new header to parse. Range: [1..2^31-1]
records integer
Number of records returned by this call to perf-archive-get-instances-iter-next. If records does not equal the maximum input request, then there are no more archives. Range: [0..2^31-1]

 
perf-archive-get-instances-iter-start [top]
Begin retrieving the instances of an archive. This call should be followed with one or more calls to perf-archive-get-instances-iter-next. This call should be preceded by a call to perf-archive-get-oldest-timestamp, otherwise an error may be returned if the input timestamp is too old.
Input Name Range Type Description
timestamp string
Timestamp (in seconds, Unix Epoch Time) to start. Range: [0..2^31-1]
 
Output Name Range Type Description
tag string
Tag to be used in subsequent calls to perf-archive-get-instances-iter-next Note that any tag not used for 1 hour will be deleted.

 
perf-archive-get-oldest-timestamp [top]
Retrieve the oldest timestamp available.
Output Name Range Type Description
timestamp integer
Oldest timestamp of all data available (in seconds, Unix Epoch Time). Range: [0..2^31-1]

 
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: archive-header [top]
Header that describes information about instances of sampled data. If the requested timestamp is greater/newer than available in the archives, we will return the most recent header.
Name Range Type Description
data string
XML formatted header data. Average expected length of each return string is around 512k bytes, though this number will fluctuate depending on the number of counters being sampled.

 
Element definition: archive-record [top]
Single instance of sampled data in binary form.
Name Range Type Description
data string
Binary instance data. Average expected length of each return string is under 10k bytes, though this number will fluctuate depending on the number of counters being sampled. May contain error string if we are unable to base64 encode the particular instance.

 
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]