dcgmi test#

NAME#

dcgmi-test - inspect and modify DCGM cache and collection state for testing

SYNOPSIS#

dcgmi test --introspect [--gpuid <gpu-id> | --group <group-id>]
           --field <field> [--host <address>]
dcgmi test --inject [--gpuid <gpu-id>] --field <field> --value <value>
           [--offset <seconds>] [--host <address>]
dcgmi test --pause [--host <address>]
dcgmi test --resume [--host <address>]

DESCRIPTION#

dcgmi test provides cache-manager inspection, synthetic field injection, and global collection pause and resume operations for controlled validation workflows. Cache injection can change the values observed by health checks, policies, diagnostics, and API clients; pausing collection affects all active metric watchers on the host engine.

Use this command only in an isolated DCGM development or test environment.

OPTIONS#

--introspect: Display cache-manager metadata for a field, including sample count, timestamps, monitor interval, retention age, fetch count, and watchers.
--inject: Inject a timestamped value into one GPU field. Binary fields cannot be injected.
--pause: Pause all host-engine metric collection. Active watchers receive unavailable values while collection is paused.
--resume: Resume metric collection after --pause.
--gpuid <gpu-id>: Select one GPU. If neither a GPU nor group is selected, the parser defaults to GPU ID 1.
-g <group-id>, --group <group-id>: Select a group for --introspect. Injection supports one GPU only.
-f <field>, --field <field>: Select a numeric field ID.
-v <value>, --value <value>: Set the value for --inject. The value is converted according to the field metadata: integer and timestamp, floating point, or string.
--offset <seconds>: Timestamp an injected value this many seconds in the future. The default is 1 second and the value must be nonnegative.
--host <address>: Connect to the specified host engine.
-h, --help: Print generated usage information and exit.

FIELD AND OUTPUT REFERENCE#

Use dcgmi dmon --list to look up a numeric field ID. The static definitions are in Field Identifiers, with entity compatibility in Field Scope and conversion types in Field Types. A field’s existence in the catalogue does not mean it is injectable or supported by the selected GPU.

Cache introspection reports the last collection status, sample count, oldest and newest timestamps, monitor interval in milliseconds, retention age in seconds, fetch count, total and average fetch time in microseconds, and active watcher count. Selecting a group repeats that metadata for the group’s GPUs.

Injection adds a synthetic cache sample timestamped at current wall-clock time plus --offset. It does not change the hardware counter from which the field normally originates. Integer/timestamp, floating-point, and string values are converted according to field metadata; binary and unknown fields are rejected.

GLOBAL STATE EFFECTS#

--pause and --resume affect metric collection for all clients of the host engine, and the paused state remains until resumed or the host engine exits. Injection can alter the latest or retained data consumed by health, policy, statistics, and monitoring operations. There is no general dcgmi test operation that removes an arbitrary injected sample. Always use an isolated host engine and explicitly select --gpuid rather than relying on the historical default of GPU 1.

EXAMPLES#

The following examples are for an isolated test host engine.

Inspect field 150 for GPU 0:

$ dcgmi test --introspect --gpuid 0 --field 150

Inject integer value 10 into field 150 for GPU 0:

$ dcgmi test --inject --gpuid 0 --field 150 --value 10 --offset 1