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

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

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

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

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.
Returns

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.
Returns

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
Returns

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).