dcgmi policy#

NAME#

dcgmi-policy - configure and observe DCGM violation policies

SYNOPSIS#

dcgmi policy --get [--group <group-id>] [--verbose] [--json]
             [--host <address>]
dcgmi policy --set <action,validation> [--group <group-id>]
             <condition>... [--host <address>]
dcgmi policy --clear [--group <group-id>] [--host <address>]
dcgmi policy --reg [--group <group-id>] [--host <address>]

DESCRIPTION#

dcgmi policy manages a group’s violation policy. A policy identifies conditions that can produce notifications. It also contains legacy action and validation fields that DCGM 4.6 stores and reports but does not execute.

The command can also remain attached to the host engine and print violation notifications as they arrive. The default group is the built-in all-GPU group.

OPTIONS#

Operation selection#

--get

Display the current policy for the selected group.

--set <action,validation>

Replace the current policy. The two comma-separated digits populate legacy action and validation fields:

Action 0 represents no action. Action 1 stores the deprecated GPU reset selection.
Validation 0 represents no validation. 1, 2, and 3 store the short, medium, and long system-validation selections, respectively.

At least one condition option is required. In DCGM 4.6, nonzero action and validation values have no operational effect in the policy module.

--clear

Clear all conditions and stored response fields from the selected group’s policy.

--reg

Register for every supported policy condition and wait indefinitely for notifications. End the listener with an interrupt or termination signal.

Conditions#

-M <count>, --maxpages <count>: Trigger after the number of retired pages reaches the nonnegative integer count.
-T <degrees-c>, --maxtemp <degrees-c>: Trigger when a GPU reaches the specified nonnegative integer temperature in degrees Celsius.
-P <watts>, --maxpower <watts>: Trigger when a GPU reaches the specified nonnegative integer power level in watts.
-e, --eccerrors: Trigger on double-bit ECC errors.
-p, --pcierrors: Trigger on PCIe errors or replays.
-n, --nvlinkerrors: Trigger on NVLink errors.
-x, --xiderrors: Trigger on XID errors.

Targets and output#

-g <group-id>, --group <group-id>: Select a persistent GPU group. The default is the built-in all-GPU group.
-v, --verbose: With --get, display the policy separately for every GPU in the group.
-j, --json: With --get, format the policy body as JSON. DCGM 4.6 also writes a plain-text heading before the document and can append a homogeneity notice. See JSON output.
--host <address>: Connect to the specified host engine.
-h, --help: Print generated usage information and exit.

POLICY CONDITION REFERENCE#

Conditions supplied to one --set are combined: an observed violation of any selected condition is eligible for notification.

Policy conditions#
Option	Threshold	Violation reported
`--maxpages <count>`	Caller-supplied, nonnegative integer retired-page count	The retired-page count reaches the limit; the notification reports the single-bit and double-bit retirement counts
`--maxtemp <degrees-c>`	Caller-supplied, nonnegative integer temperature in degrees Celsius	Measured GPU temperature reaches the limit
`--maxpower <watts>`	Caller-supplied, nonnegative integer power in watts	Measured GPU power reaches the limit
`--eccerrors`	Internal fixed criterion	A double-bit ECC error
`--pcierrors`	Internal fixed criterion	PCIe errors or replay events
`--nvlinkerrors`	Internal fixed criterion	An NVLink error counter violates DCGM’s criterion
`--xiderrors`	The driver event itself	An XID error is detected

The policy API’s internal criteria are not configurable through dcgmi. See Policy for condition categories and Policies for the programmatic interface.

STATE AND SIDE EFFECTS#

--set replaces the selected group’s complete policy; it does not add to an existing policy. The policy remains after this client disconnects, but is state in the running host engine rather than durable configuration. Use --get --verbose to detect GPUs in the group whose policy differs from the summary.

Action and validation are legacy stored fields. --get displays their configured values, but DCGM 4.6 does not dispatch a GPU reset, run a diagnostic, or send an action-completion notification after a policy violation. Use a notification consumer to coordinate recovery and invoke diagnostics explicitly; see dcgmi diag for the diagnostic interface.

--set does not start the policy module’s required field watches. --reg installs a connected listener and starts those watches, so keep a registration active while relying on policy notifications.

--reg is a connection-bound listener, not a policy selector. In DCGM 4.6 it always subscribes to all seven conditions in the table, regardless of any condition options also present on the command line. Stop it with a signal; the stored policy itself remains in the host engine.

EXAMPLES#

Display the policy for group 2:

$ dcgmi policy --get --group 2

Store the legacy reset and short-validation selections for double-bit ECC or PCIe errors. DCGM 4.6 reports but does not execute these selections:

$ dcgmi policy --set 1,1 --group 2 --eccerrors --pcierrors

Notify without taking an action when temperature reaches 85 degrees Celsius:

$ dcgmi policy --set 0,0 --group 2 --maxtemp 85

Wait for policy notifications:

$ dcgmi policy --reg --group 2