1.4. Field APIs
These APIs are responsible for watching, unwatching, and updating specific fields as defined by DCGM_FI_*
Functions
- dcgmReturn_t dcgmEntitiesGetLatestValues ( dcgmHandle_t pDcgmHandle, dcgmGroupEntityPair_t entities[], unsigned int entityCount, unsigned short fields[], unsigned int fieldCount, unsigned int flags, dcgmFieldValue_v2 values[] )
- dcgmReturn_t dcgmEntityGetLatestValues ( dcgmHandle_t pDcgmHandle, dcgm_field_entity_group_t entityGroup, int entityId, unsigned short fields[], unsigned int count, dcgmFieldValue_v1 values[] )
- dcgmReturn_t dcgmGetFieldSummary ( dcgmHandle_t pDcgmHandle, dcgmFieldSummaryRequest_t* request )
- dcgmReturn_t dcgmGetLatestValues ( dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmFieldGrp_t fieldGroupId, dcgmFieldValueEnumeration_f enumCB, void* userData )
- dcgmReturn_t dcgmGetLatestValuesForFields ( dcgmHandle_t pDcgmHandle, int gpuId, unsigned short fields[], unsigned int count, dcgmFieldValue_v1 values[] )
- dcgmReturn_t dcgmGetLatestValues_v2 ( dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmFieldGrp_t fieldGroupId, dcgmFieldValueEntityEnumeration_f enumCB, void* userData )
- dcgmReturn_t dcgmGetValuesSince ( dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmFieldGrp_t fieldGroupId, long long sinceTimestamp, long long* nextSinceTimestamp, dcgmFieldValueEnumeration_f enumCB, void* userData )
- dcgmReturn_t dcgmGetValuesSince_v2 ( dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmFieldGrp_t fieldGroupId, long long sinceTimestamp, long long* nextSinceTimestamp, dcgmFieldValueEntityEnumeration_f enumCB, void* userData )
- dcgmReturn_t dcgmUnwatchFields ( dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmFieldGrp_t fieldGroupId )
- dcgmReturn_t dcgmWatchFields ( dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmFieldGrp_t fieldGroupId, long long updateFreq, double maxKeepAge, int maxKeepSamples )
Functions
- dcgmReturn_t dcgmEntitiesGetLatestValues ( dcgmHandle_t pDcgmHandle, dcgmGroupEntityPair_t entities[], unsigned int entityCount, unsigned short fields[], unsigned int fieldCount, unsigned int flags, dcgmFieldValue_v2 values[] )
-
Parameters
- pDcgmHandle
- IN: DCGM Handle
- entities
- IN: List of entities to get values for
- entityCount
- IN: Number of entries in entities[]
- fields
- IN: Field IDs to return data for. See the definitions in dcgm_fields.h that start with DCGM_FI_.
- fieldCount
- IN: Number of field IDs in fields[] array.
- flags
- IN: Optional flags that affect how this request is processed. Pass DCGM_FV_FLAG_LIVE_DATA here to retrieve a live driver value rather than a cached value. See that flag's documentation for caveats.
- values
- OUT: Latest field values for the fields requested. This must be able to hold entityCount * fieldCount field value records.
Description
Request the latest cached or live field value for a list of fields for a group of entities
Note: The returned entities are not guaranteed to be in any order. Reordering can occur internally in order to optimize calls to the NVIDIA driver.
- dcgmReturn_t dcgmEntityGetLatestValues ( dcgmHandle_t pDcgmHandle, dcgm_field_entity_group_t entityGroup, int entityId, unsigned short fields[], unsigned int count, dcgmFieldValue_v1 values[] )
-
Parameters
- pDcgmHandle
- IN: DCGM Handle
- entityGroup
- IN: entity_group_t (e.g. switch)
- entityId
- IN: entity ID representing the rntity for which the fields are being requested.
- fields
- IN: Field IDs to return data for. See the definitions in dcgm_fields.h that start with DCGM_FI_.
- count
- IN: Number of field IDs in fields[] array.
- values
- OUT: Latest field values for the fields in fields[].
Description
Request latest cached field value for a group of fields for a specific entity
- dcgmReturn_t dcgmGetFieldSummary ( dcgmHandle_t pDcgmHandle, dcgmFieldSummaryRequest_t* request )
-
Parameters
- pDcgmHandle
- IN: DCGM Handle
- request
- IN/OUT: a pointer to the struct detailing the request and containing the response
Returns
- DCGM_ST_OK if the call was successful
- DCGM_ST_FIELD_UNSUPPORTED_BY_API if the field is not int64 or double type
Description
Get a summary of the values for a field id over a period of time.
- dcgmReturn_t dcgmGetLatestValues ( dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmFieldGrp_t fieldGroupId, dcgmFieldValueEnumeration_f enumCB, void* userData )
-
Parameters
- pDcgmHandle
- IN: DCGM Handle
- groupId
- IN: Group ID representing collection of one or more GPUs. Look at dcgmGroupCreate for details on creating the group. Alternatively, pass in the group id as DCGM_GROUP_ALL_GPUS to perform operation on all the GPUs.
- fieldGroupId
- IN: Fields to return data for.
- enumCB
- IN: Callback to invoke for every field value update. Note that multiple updates can be returned in each invocation
- userData
- IN: User data pointer to pass to the userData field of enumCB.
Returns
- DCGM_ST_OK if the call was successful
- DCGM_ST_NOT_SUPPORTED if one of the entities was from a non-GPU type
- DCGM_ST_BADPARAM if a parameter is invalid
Description
Request latest cached field value for a field value collection
This version only works with GPU entities. Use dcgmGetLatestValues_v2 for entity groups containing NvSwitches.
- dcgmReturn_t dcgmGetLatestValuesForFields ( dcgmHandle_t pDcgmHandle, int gpuId, unsigned short fields[], unsigned int count, dcgmFieldValue_v1 values[] )
-
Parameters
- pDcgmHandle
- IN: DCGM Handle
- gpuId
- IN: Gpu ID representing the GPU for which the fields are being requested.
- fields
- IN: Field IDs to return data for. See the definitions in dcgm_fields.h that start with DCGM_FI_.
- count
- IN: Number of field IDs in fields[] array.
- values
- OUT: Latest field values for the fields in fields[].
Description
Request latest cached field value for a GPU
- dcgmReturn_t dcgmGetLatestValues_v2 ( dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmFieldGrp_t fieldGroupId, dcgmFieldValueEntityEnumeration_f enumCB, void* userData )
-
Parameters
- pDcgmHandle
- IN: DCGM Handle
- groupId
- IN: Group ID representing collection of one or more entities. Look at dcgmGroupCreate for details on creating the group. Alternatively, pass in the group id as DCGM_GROUP_ALL_GPUS to perform operation on all the GPUs or DCGM_GROUP_ALL_NVSWITCHES to perform the operation on all NvSwitches.
- fieldGroupId
- IN: Fields to return data for.
- enumCB
- IN: Callback to invoke for every field value update. Note that multiple updates can be returned in each invocation
- userData
- IN: User data pointer to pass to the userData field of enumCB.
Returns
- DCGM_ST_OK if the call was successful
- DCGM_ST_NOT_SUPPORTED if one of the entities was from a non-GPU type
- DCGM_ST_BADPARAM if a parameter is invalid
Description
Request latest cached field value for a field value collection
This version works with non-GPU entities like NvSwitches
- dcgmReturn_t dcgmGetValuesSince ( dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmFieldGrp_t fieldGroupId, long long sinceTimestamp, long long* nextSinceTimestamp, dcgmFieldValueEnumeration_f enumCB, void* userData )
-
Parameters
- pDcgmHandle
- IN: DCGM Handle
- groupId
- IN: Group ID representing collection of one or more GPUs. Look at dcgmGroupCreate for details on creating the group. Alternatively, pass in the group id as DCGM_GROUP_ALL_GPUS to perform operation on all the GPUs.
- fieldGroupId
- IN: Fields to return data for
- sinceTimestamp
- IN: Timestamp to request values since in usec since 1970. This will be returned in nextSinceTimestamp for subsequent calls 0 = request all data
- nextSinceTimestamp
- OUT: Timestamp to use for sinceTimestamp on next call to this function
- enumCB
- IN: Callback to invoke for every field value update. Note that multiple updates can be returned in each invocation
- userData
- IN: User data pointer to pass to the userData field of enumCB.
Returns
- DCGM_ST_OK if the call was successful
- DCGM_ST_NOT_SUPPORTED if one of the entities was from a non-GPU type
- DCGM_ST_BADPARAM if a parameter is invalid
Description
Request updates for all field values that have updated since a given timestamp
This version only works with GPU entities. Use dcgmGetValuesSince_v2 for entity groups containing NvSwitches.
- dcgmReturn_t dcgmGetValuesSince_v2 ( dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmFieldGrp_t fieldGroupId, long long sinceTimestamp, long long* nextSinceTimestamp, dcgmFieldValueEntityEnumeration_f enumCB, void* userData )
-
Parameters
- pDcgmHandle
- IN: DCGM Handle
- groupId
- IN: Group ID representing collection of one or more entities. Look at dcgmGroupCreate for details on creating the group. Alternatively, pass in the group id as DCGM_GROUP_ALL_GPUS to perform operation on all the GPUs or DCGM_GROUP_ALL_NVSWITCHES to perform the operation on all NvSwitches.
- fieldGroupId
- IN: Fields to return data for
- sinceTimestamp
- IN: Timestamp to request values since in usec since 1970. This will be returned in nextSinceTimestamp for subsequent calls 0 = request all data
- nextSinceTimestamp
- OUT: Timestamp to use for sinceTimestamp on next call to this function
- enumCB
- IN: Callback to invoke for every field value update. Note that multiple updates can be returned in each invocation
- userData
- IN: User data pointer to pass to the userData field of enumCB.
Description
Request updates for all field values that have updated since a given timestamp
This version works with non-GPU entities like NvSwitches
- dcgmReturn_t dcgmUnwatchFields ( dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmFieldGrp_t fieldGroupId )
-
Parameters
- pDcgmHandle
- IN: DCGM Handle
- groupId
- IN: Group ID representing collection of one or more entities. Look at dcgmGroupCreate for details on creating the group. Alternatively, pass in the group id as DCGM_GROUP_ALL_GPUS to perform operation on all the GPUs or DCGM_GROUP_ALL_NVSWITCHES to to perform the operation on all NvSwitches.
- fieldGroupId
- IN: Fields to unwatch.
Description
Request that DCGM stop recording updates for a given field collection.
- dcgmReturn_t dcgmWatchFields ( dcgmHandle_t pDcgmHandle, dcgmGpuGrp_t groupId, dcgmFieldGrp_t fieldGroupId, long long updateFreq, double maxKeepAge, int maxKeepSamples )
-
Parameters
- pDcgmHandle
- IN: DCGM Handle
- groupId
- IN: Group ID representing collection of one or more entities. Look at dcgmGroupCreate for details on creating the group. Alternatively, pass in the group id as DCGM_GROUP_ALL_GPUS to perform operation on all the GPUs or DCGM_GROUP_ALL_NVSWITCHES to to perform the operation on all NvSwitches.
- fieldGroupId
- IN: Fields to watch.
- updateFreq
- IN: How often to update this field in usec
- maxKeepAge
- IN: How long to keep data for this field in seconds
- maxKeepSamples
- IN: Maximum number of samples to keep. 0=no limit
Description
Request that DCGM start recording updates for a given field collection.
Note that the first update of the field will not occur until the next field update cycle. To force a field update cycle, call dcgmUpdateAllFields(1).