PTI Metrics API Reference

PTI Metrics API Reference#

Warning

DRAFT DOCUMENTATION - This documentation is currently in draft status and subject to change.

This section provides API documentation for the PTI Metrics API (device-level metrics sampling).

Note

This page documents the Metrics API for device-level time-based and event-based metrics sampling. For per-kernel metrics collection, see PTI Metrics Scope API Reference.

Overview#

The Metrics API provides time-based and event-based sampling of hardware performance metrics across application runtime. This API provides system-level performance monitoring without kernel-level granularity.

The API includes:

Device Discovery Functions - Enumerate devices that support metrics collection
Metric Discovery Functions - Discover available metric groups and individual metrics
Collection Control Functions - Configure, start, stop, pause, and resume collection
Data Retrieval Functions - Retrieve calculated metrics data
Structures - Device properties, metric properties, and collection parameters
Enumerators - Metric group types, metric types, and value types

Detailed API Documentation#

Device Discovery Functions#

pti_result ptiMetricsGetDevices(pti_device_properties_t *devices, uint32_t *device_count)#

Get the properties of all devices on the system on which metric collection can be done usage: 1- Call ptiMetricsGetDevices(NULL, device_count) to discover the required buffer size; the required buffer size will be written to device_count. 2- Allocate devices buffer of size sizeof(pti_device_properties_t) * device_count 3- Call ptiMetricsGetDevices(devices, device_count) to get the properties of the discovered devices written to devices.

Parameters:

[in/out] – devices Pointer to the array of devices. If NULL, the number of devices is returned in *device_count if not NULL, it should point to the buffer of size: sizeof(pti_device_description_t) * (*device_count)
[in/out] – device_count Number of devices in - if devices is NULL or if device_count is less than the required minimum buffer size, device_count will contain the required buffer size out - devices buffer size used Note: device_count cannot be NULL

Returns:

pti_result

Metric Discovery Functions#

pti_result ptiMetricsGetMetricGroups(pti_device_handle_t device_handle, pti_metrics_group_properties_t *metrics_groups, uint32_t *metrics_group_count)#

Get the properties of the metric groups supported by the device Usage: 1- Call ptiMetricsGetMetricGroups(device_handle, null, metrics_group_count) to discover the required buffer size; the required buffer size will be written to metrics_group_count. 2- Allocate metrics_groups buffer of size sizeof(pti_metrics_group_properties_t) * metrics_group_count 3- Call ptiMetricsGetMetricGroups(device_handle, metrics_groups, metrics_group_count) again to get the properties of the discovered metric groups written to the supplied buffer.

Parameters:

device_handle – [in] Device handle
[in/out] – metrics_groups Buffer where to save metric group properties for the metric groups that can be collected. Set to null to discover the required buffer size
[in/out] – metrics_group_count If metrics_groups is set to null or metrics_group_count is less than the required minimum buffer size, metrics_group_count will contain the metric group count Otherwise, metrics_group_count will contain actual metric group count Note: metrics_group_count cannot be null

Returns:

pti_result

pti_result ptiMetricsGetMetricsProperties(pti_metrics_group_handle_t metrics_group_handle, pti_metric_properties_t *metrics)#

Get properties for all metrics in a metric group. Usage: 1- Get available metric groups on a specified device using ptiMetricsGetMetricGroups 2- In the metric group properties structure of the metric group of interest, allocate buffer _metric_properties of size sizeof(pti_metric_properties_t) * _metric_count 3- call ptiMetricsGetMetricsProperties(metrics_group_handle, _metric_properties) to get the metric properties written to the supplied buffer.

Parameters:

metrics_group_handle – [in] Metric group handle
[in/out] – metrics Buffer where to save metric properties for the specified metric group

Returns:

pti_result

Collection Control Functions#

pti_result ptiMetricsConfigureCollection(pti_device_handle_t device_handle, pti_metrics_group_collection_params_t *metrics_group_collection_params, uint32_t metrics_group_count)#

Configure metric groups of interest. Note: only 1 metric group of type PTI_METRIC_GROUP_TYPE_TIME_BASED can be specified at this time. TODO: add support for multiple metric groups and different types.

Parameters:

device_handle – [in] Device handle
metric_config_params – [in] Buffer of input parameters structures. Note: only 1 is supported at this time
metrics_group_count – [in] Number of configuration structures in the configuration buffer

Returns:

pti_result

pti_result ptiMetricsStartCollection(pti_device_handle_t device_handle)#

Start metrics collection on specified device Note: ptiMetricsConfigureCollection must be called first to configure the metric group(s) of interest.

Parameters:: device_handle – [in] Device handle
Returns:: pti_result

pti_result ptiMetricsStartCollectionPaused(pti_device_handle_t device_handle)#

Start metrics collection on specified device in paused mode Note: ptiMetricsConfigureCollection must be called first to configure the metric group(s) of interest.

Parameters:: device_handle – [in] Device handle
Returns:: pti_result

pti_result ptiMetricsPauseCollection(pti_device_handle_t device_handle)#

Pause metrics collection on specified device Note: Collection must be started first.

Parameters:: device_handle – [in] Device handle
Returns:: pti_result

pti_result ptiMetricsResumeCollection(pti_device_handle_t device_handle)#

Resume metrics collection on specified device Note: Collection must be started and paused.

Parameters:: device_handle – [in] Device handle
Returns:: pti_result

pti_result ptiMetricsStopCollection(pti_device_handle_t device_handle)#

stop metrics collection on specified device Note: ptiMetricsStartCollection must be called first to start the collection This function terminates the collection but does not process the data

Parameters:: device_handle – [in] Device handle
Returns:: pti_result

Data Retrieval Functions#

pti_result ptiMetricsGetCalculatedData(pti_device_handle_t device_handle, pti_metrics_group_handle_t metrics_group_handle, pti_value_t *metrics_values_buffer, uint32_t *metrics_values_count)#

process and dump collected data on specified device Note: ptiMetricsStopCollection must be called first to process collected data ptiMetricsGetCalculatedData can only be called once after the collection is stopped and cannot be called between pause and resume

usage: 1- Call ptiMetricsGetCalculatedData(device_handle, metrics_group_handle, NULL, metrics_values_count) to discover the required buffer size for data collected for the specified metric group on on the specified device ; the required buffer size will be written to value_count in multiples of pti_value_t. 2- Allocate metrics_values_buffer for holding metrics_values_count values 3- Call ptiMetricsGetCalculatedData(device_handle, metrics_group_handle, metrics_values_buffer, metrics_values_count) to get the values written to buffer A sample contains a 64bit value container for each metric in the metric group. based on the metric’s value type, the 64bit value container should be converted appropriately.

Parameters:

device_handle – [in] Device handle
metrics_group_handle – [in] Metric Group handle
[in/out] – metrics_values_buffer Buffer where to save collected samples Set to null to discover the required buffer size
[in/out] – metrics_values_count If metrics_values_buffer is set to null, metrics_values_count will contain the number of pti_value_t values the buffer needs to be able to hold

Returns:

pti_result

Structures#

struct pti_device_properties_t#

Public Members

pti_device_handle_t _handle#: Internal handle to device.

pti_pci_properties_t _address#: PCI device properties.

const char *_model_name#: Model name of the device.

uint8_t _uuid[PTI_MAX_DEVICE_UUID_SIZE]#: Universal unique identifier.

struct pti_pci_properties_t#

struct pti_metric_properties_t#

Public Members

pti_metric_handle_t _handle#: Internal handle for the metric.

const char *_name#: Name of the metric.

const char *_description#: Description of the metric.

pti_metric_type _metric_type#: Type of the metric.

pti_metric_value_type _value_type#: Value type of the metric.

const char *_units#: The units of the metric result values.

struct pti_metrics_group_properties_t#

Public Members

pti_metrics_group_handle_t _handle#: Internal handle for the metric group.

pti_metrics_group_type _type#: Sampling type of the metric group.

uint32_t _domain#: Hardware domain responsible for collecting the metric group.

uint32_t _metric_count#: Number of metrics in the metric group.

pti_metric_properties_t *_metric_properties#: Convenience pointer to buffer where metric properties in the metric group can be saved.

const char *_name#: Name of the metric group.

const char *_description#: Description of the metric group.

struct pti_metrics_group_collection_params_t#

Public Members

size_t _struct_size#: [in] Size of the pti_metirc_config_collection_params struct used for backwards compatibility

pti_metrics_group_handle_t _group_handle#: [in] Metric group handle.

uint32_t _sampling_interval#: [in] Set the sampling interval in nsec. This field is applicable for PTI_METRIC_GROUP_TYPE_TIME_BASED metrics groups only.

uint32_t _time_aggr_window#: [in] Set the time aggregation window in nsec. This field is applicable for PTI_METRIC_GROUP_TYPE_TRACE_BASED metrics groups only.

Enumerators#

enum pti_metrics_group_type#

Values:

enumerator PTI_METRIC_GROUP_TYPE_EVENT_BASED#: Event based sampling (Query)

enumerator PTI_METRIC_GROUP_TYPE_TIME_BASED#: Time based sampling (Stream)

enumerator PTI_METRIC_GROUP_TYPE_TRACE_BASED#: Trace based sampling (Trace)

enumerator PTI_METRIC_GROUP_TYPE_FORCE_UINT32#

enum pti_metric_type#

Metric types.

Values:

enumerator PTI_METRIC_TYPE_DURATION#: duration

enumerator PTI_METRIC_TYPE_EVENT#: event

enumerator PTI_METRIC_TYPE_EVENT_WITH_RANGE#: event with range

enumerator PTI_METRIC_TYPE_THROUGHPUT#: throughput

enumerator PTI_METRIC_TYPE_TIMESTAMP#: timestamp

enumerator PTI_METRIC_TYPE_FLAG#: flag

enumerator PTI_METRIC_TYPE_RATIO#: ratio

enumerator PTI_METRIC_TYPE_RAW#: raw

enumerator PTI_METRIC_TYPE_IP#: instruction pointer

enumerator PTI_METRIC_TYPE_FORCE_UINT32#

enum pti_metric_value_type#

Supported value types.

Values:

enumerator PTI_METRIC_VALUE_TYPE_UINT32#: 32-bit unsigned-integer

enumerator PTI_METRIC_VALUE_TYPE_UINT64#: 64-bit unsigned-integer

enumerator PTI_METRIC_VALUE_TYPE_FLOAT32#: 32-bit floating-point

enumerator PTI_METRIC_VALUE_TYPE_FLOAT64#: 64-bit floating-point

enumerator PTI_METRIC_VALUE_TYPE_BOOL8#: 8-bit boolean

enumerator PTI_METRIC_VALUE_TYPE_STRING#: C string.

enumerator PTI_METRIC_VALUE_TYPE_UINT8#: 8-bit unsigned-integer

enumerator PTI_METRIC_VALUE_TYPE_UINT16#: 16-bit unsigned-integer

enumerator PTI_METRIC_VALUE_TYPE_FORCE_UINT32#

Type Definitions#

typedef void *pti_device_handle_t#

Abstraction for backend-specific objects.

Level Zero is currently the only supported backend. However, these types will attempt to serve other backends. In case the other backend supported - the same types will serve it. Device handle

typedef void *pti_metrics_group_handle_t#: Abstraction of a metric group handle within PTI.

PTI Metrics API Reference

Contents

PTI Metrics API Reference#

Overview#

Detailed API Documentation#

Device Discovery Functions#

Metric Discovery Functions#

Collection Control Functions#

Data Retrieval Functions#

Structures#

Enumerators#

Type Definitions#