Field APIs

group DCGMAPI_FI

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: