APIs in Category: perf | 7-Mode API version 1.21

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 performance 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. In Data ONTAP 7-Mode, 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 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 500 instances are requested.
> 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
> 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[] optional | 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
> is-key |  | boolean optional | True if the counter is a key counter. A set of key counters for an object can be used to uniquely identify instances of an object.
> 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 optional | Name of the instance

Element definition: object-info | [top]

> Description of a performance object.

> Name | Range | Type | Description
> description |  | string optional | Description of the object
> get-instances-preferred-counter |  | string optional | Name of the counter, either instance_name or instance_uuid, which should be used for perf-object-get-instances ZAPI for optimal performance. If this element is absent for an object, the value of this element defaults to instance_name counter. This element is a performance hint for getting optimal performance for the perf-object-get-instances ZAPI. If the value of this element is set to instance UUID counter of an object, using the instance UUID counter in the perf-object-get-instances query will return the counter information faster than using instance name counter. Otherwise, instance_name will yield faster results.
> 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]