Field APIs#

group Field APIs

These APIs are responsible for watching, unwatching, and updating specific fields as defined by DCGM_FI_*.

Functions

dcgmReturn_t dcgmWatchFields(
dcgmHandle_t pDcgmHandle,
dcgmGpuGrp_t groupId,
dcgmFieldGrp_t fieldGroupId,
long long updateFreq,
double maxKeepAge,
int maxKeepSamples
)#

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

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:

dcgmReturn_t dcgmUnwatchFields(
dcgmHandle_t pDcgmHandle,
dcgmGpuGrp_t groupId,
dcgmFieldGrp_t fieldGroupId
)#

Request that DCGM stop recording updates for a given field collection.

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:

dcgmReturn_t dcgmGetValuesSince(
dcgmHandle_t pDcgmHandle,
dcgmGpuGrp_t groupId,
dcgmFieldGrp_t fieldGroupId,
long long sinceTimestamp,
long long *nextSinceTimestamp,
dcgmFieldValueEnumeration_f enumCB,
void *userData
)#

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.

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:

dcgmReturn_t dcgmGetValuesSince_v2(
dcgmHandle_t pDcgmHandle,
dcgmGpuGrp_t groupId,
dcgmFieldGrp_t fieldGroupId,
long long sinceTimestamp,
long long *nextSinceTimestamp,
dcgmFieldValueEntityEnumeration_f enumCB,
void *userData
)#

Request updates for all field values that have updated since a given timestamp.

This version works with non-GPU entities like NvSwitches

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:

dcgmReturn_t dcgmGetLatestValues(
dcgmHandle_t pDcgmHandle,
dcgmGpuGrp_t groupId,
dcgmFieldGrp_t fieldGroupId,
dcgmFieldValueEnumeration_f enumCB,
void *userData
)#

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.

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:

dcgmReturn_t dcgmGetLatestValues_v2(
dcgmHandle_t pDcgmHandle,
dcgmGpuGrp_t groupId,
dcgmFieldGrp_t fieldGroupId,
dcgmFieldValueEntityEnumeration_f enumCB,
void *userData
)#

Request latest cached field value for a field value collection.

This version works with non-GPU entities like NvSwitches

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:

dcgmReturn_t dcgmGetLatestValuesForFields(
dcgmHandle_t pDcgmHandle,
int gpuId,
unsigned short fields[],
unsigned int count,
dcgmFieldValue_v1 values[]
)#

Request latest cached field value for a GPU.

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[].

dcgmReturn_t dcgmEntityGetLatestValues(
dcgmHandle_t pDcgmHandle,
dcgm_field_entity_group_t entityGroup,
int entityId,
unsigned short fields[],
unsigned int count,
dcgmFieldValue_v1 values[]
)#

Request latest cached field value for a group of fields for a specific entity.

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[].

dcgmReturn_t dcgmEntitiesGetLatestValues(
dcgmHandle_t pDcgmHandle,
dcgmGroupEntityPair_t entities[],
unsigned int entityCount,
unsigned short fields[],
unsigned int fieldCount,
unsigned int flags,
dcgmFieldValue_v2 values[]
)#

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.

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.

dcgmReturn_t dcgmGetFieldSummary(
dcgmHandle_t pDcgmHandle,
dcgmFieldSummaryRequest_t *request
)#

Get a summary of the values for a field id over a period of time.

Parameters:

  • pDcgmHandle – IN: DCGM Handle

  • request – IN/OUT: a pointer to the struct detailing the request and containing the response

Returns: