dcgmi profile#

NAME#

dcgmi-profile - inspect and control DCGM profiling metrics

SYNOPSIS#

dcgmi profile --list [--entity-id <entities> | --group-id <group>]
              [--json] [--host <address>]
dcgmi profile --pause [--host <address>]
dcgmi profile --resume [--host <address>]

DESCRIPTION#

dcgmi profile lists profiling metric groups supported by a GPU or pauses and resumes profiling collection for the host engine. Pausing releases profiling resources so developer tools such as Nsight Compute or Nsight Systems can use them.

Metric support is GPU-specific. If a list target contains several GPUs, the command reports support for the first GPU in that entity list or group. With no target, it uses the first supported GPU in the system.

OPTIONS#

-l, --list: List supported profiling metric groups, their field IDs, and field tags.
--pause: Pause profiling metric collection for the host engine.
--resume: Resume profiling metric collection after --pause.
-i <entities>, --entity-id <entities>: Select the first GPU in a comma-separated entity list. Non-GPU entities do not provide a target. See dcgmi for entity syntax.
-g <group>, --group-id <group>: Select the first GPU in a numeric group. all_gpus selects the built-in all-GPU group. A group without a GPU cannot be used to list GPU profiling metrics.
-j, --json: Use JSON for --list output. See JSON output.
--host <address>: Connect to the specified host engine.
-h, --help: Print generated usage information and exit.

METRIC GROUP REFERENCE#

--list is the authoritative profiling catalogue for the selected GPU. Its Field ID and Field Tag columns can be used with dcgmi dmon or dcgmi fieldgroup. The Group.Subgroup value encodes the metric group’s major ID as a letter and its minor ID as a number, for example A.0.

On Ampere and older GPUs, profiling fields in one subgroup are collected together. Subgroups with the same letter use the same hardware resource and cannot be watched concurrently; groups with different letters can be watched concurrently. On Hopper and newer GPUs, GPM obtains the metrics together and all listed GPM/profiling groups can be watched concurrently despite the group labels. These rules are architecture-dependent, which is why a static list is not substituted for profile --list. See Profiling for the API model and Field Identifiers for field definitions.

PAUSE AND RESUME SCOPE#

Pause and resume apply to profiling collection for the entire host engine, not merely the target used by a preceding --list. While paused, DCGM saves blank values for profiling fields, which monitoring clients display as unavailable. Both operations are idempotent. The paused state remains in the running host engine after this dcgmi process exits; coordinate with other clients and always resume after the developer tool finishes.

EXAMPLES#

List profiling metrics supported by GPU 0:

$ dcgmi profile --list --entity-id gpu:0

List metrics for the first GPU in group 2 as JSON:

$ dcgmi profile --list --group-id 2 --json

Pause profiling before launching a developer tool, then resume it:

$ dcgmi profile --pause

$ dcgmi profile --resume