Go SDK#

The DCGM Go SDK, provided by the NVIDIA go-dcgm project, supplies Go bindings and higher-level helpers for the DCGM C API. Use it to call DCGM from a Go application without writing a separate cgo layer.

go-dcgm is not a pure Go implementation of DCGM. It uses cgo, loads the installed libdcgm.so.4 at runtime, and calls the native DCGM API. The application therefore uses the capabilities, permissions, and hardware support of the installed DCGM runtime.

Capabilities and Architecture#

What You Can Do#

The SDK exposes helpers for the principal DCGM integration workflows:

Task	Representative Go API	Related DCGM documentation
Discover devices and entity hierarchies	`GetSupportedDevices`, `GetDeviceInfo`, `GetEntityGroupEntities`, `GetGPUInstanceHierarchy`, and `GetCPUHierarchy_v2`	Entities and Groups
Read common GPU status	`GetGPUStatus` and `GetDeviceStatus`	Fields and Watches
Create and manage entity groups	`CreateGroup`, `AddEntityToGroup`, `GetGroupInfo`, and `DestroyGroup`	Entities and Groups
Resolve, watch, and read telemetry fields	`GetFieldID`, `FieldGetByID`, `FieldGroupCreate`, `WatchFieldsWithGroupEx`, `EntitiesGetLatestValues`, and `GetValuesSince`	Fields and Watches and Field Identifiers
Configure and check health watches	`HealthSet`, `HealthGet`, `HealthCheck`, and `HealthCheckByGpuId`	Health Monitoring
Run diagnostics	`RunDiag`	Diagnostics
Configure policies and receive violations	`SetPolicyForGroup`, `GetPolicyForGroup`, `ClearPolicyForGroup`, and `WatchPolicyViolationsForGroup`	Health Monitoring
Inspect topology and NVLink state	`GetDeviceTopology`, `GetNvLinkLinkStatus`, and `GetNvLinkP2PStatus`	Topology and NVLink
Read process and profiling information	`WatchPidFields`, `WatchPidFieldsEx`, `GetProcessInfo`, and `GetSupportedMetricGroups`	Profiling
Inspect DCGM resource use, versions, and error metadata	`Introspect`, `GetVersionInfo`, `GetHostengineVersionInfo`, and `GetErrorMeta`	Introspection and Health Monitoring
Coordinate a live driver update	`DetachDriver` and `AttachDriver`	Getting Started for Application Developers

Start with convenience helpers such as GetDeviceInfo, GetDeviceStatus, and HealthCheckByGpuId. Use entity groups, field groups, and watches when the application needs custom entity sets, fields, collection intervals, or retention.

This table covers the SDK’s feature areas, not every exported function or type. The package also exposes lower-level value conversion, field metadata, blank-value detection, and DCGM test-injection helpers for specialized code. Use the Go package reference to check the current exported functions, types, ownership requirements, and version notes. Do not assume that every native C API has a Go wrapper.

How the SDK Works#

A Go application initializes go-dcgm in one of three modes. The package then keeps a process-wide DCGM handle that its exported functions use to call libdcgm.so.4.

Mode	Behavior	Use it when
`dcgm.Embedded`	Loads the DCGM host engine into the application process. The application owns its lifecycle.	The application should own DCGM and does not need a separate DCGM host engine process.
`dcgm.Standalone`	Connects to an existing DCGM `nv-hostengine` process over TCP, a Unix socket, or VSOCK.	DCGM is managed independently or the application connects remotely.
`dcgm.StartHostengine`	Starts `nv-hostengine` as a child process, connects to it, and stops it during cleanup. The executable must be in `PATH`.	The application should own a separate DCGM host engine process.

The first successful dcgm.Init call establishes the process-wide mode and connection. Additional calls share that initialization. Each successful call returns a cleanup function; DCGM shuts down or disconnects after all matching cleanup calls complete. Defer every returned cleanup function immediately.

DCGM field watches collect and cache samples independently of the Go caller. Reading a field returns data governed by the watch frequency and retention configured for that field group. See Fields and Watches before choosing collection intervals or interpreting cached values.

Requirements, Compatibility, and Installation#

Requirements#

A supported NVIDIA driver and DCGM installation. See Feature Availability by GPU Class and Install DCGM.
A Go toolchain that satisfies the version declared by the go-dcgm go.mod file.
A C compiler with cgo enabled to build the bindings.
A running DCGM host engine when using dcgm.Standalone.

Some DCGM operations require elevated privileges. Run the application with the permissions required by the corresponding native DCGM API.

Version Compatibility#

go-dcgm includes the C headers used to compile the bindings, but it calls the installed libdcgm.so.4 at runtime. API availability therefore depends on both the selected go-dcgm version and the installed DCGM version.

Use a go-dcgm release intended for the deployed DCGM release. Pin the Go module version, then build and test the application with the same DCGM runtime used in production.

Install `go-dcgm`#

Create a Go module and add the package:

$ mkdir dcgm-info
$ cd dcgm-info
$ go mod init example.com/dcgm-info
$ go get github.com/NVIDIA/go-dcgm/pkg/dcgm@latest

go get records the resolved module version in go.mod. Commit the resulting go.mod and go.sum files so builds use the selected version.

Getting Started and Resource Lifetime#

Initialize a Connection#

Embedded mode requires no connection arguments:

cleanup, err := dcgm.Init(dcgm.Embedded)

Standalone mode accepts a DCGM connection string with DCGM 4.5 or later:

cleanup, err := dcgm.Init(dcgm.Standalone, "tcp://127.0.0.1:5555")

Use tcp://[::1]:5555 for IPv6, unix:///path/to/socket for a Unix socket, or vsock://cid:port for VSOCK. With an older DCGM 4 runtime, pass the address and socket flag separately. Use "0" for TCP and "1" for a Unix socket:

cleanup, err := dcgm.Init(dcgm.Standalone, "127.0.0.1", "0")

To let the application start and stop a separate DCGM host engine process:

cleanup, err := dcgm.Init(dcgm.StartHostengine)

In each case, check err before calling or deferring cleanup.

The examples below focus on the Go calling pattern. See Getting Started for Application Developers for the shared DCGM state, deployment, and lifecycle model that applies to both C and Go clients.

Query GPU Information#

The following program starts DCGM in embedded mode and prints every supported GPU:

package main

import (
    "fmt"
    "log"

    "github.com/NVIDIA/go-dcgm/pkg/dcgm"
)

func main() {
    cleanup, err := dcgm.Init(dcgm.Embedded)
    if err != nil {
        log.Fatal(err)
    }
    defer cleanup()

    gpuIDs, err := dcgm.GetSupportedDevices()
    if err != nil {
        log.Fatal(err)
    }

    for _, gpuID := range gpuIDs {
        device, err := dcgm.GetDeviceInfo(gpuID)
        if err != nil {
            log.Fatal(err)
        }
        fmt.Printf("GPU %d: %s (%s)\n", gpuID, device.Identifiers.Model, device.UUID)
    }
}

Save the program as main.go, then run it:

$ go run .

Resource Lifetime#

The cleanup function returned by dcgm.Init releases the process-wide DCGM connection when the final user finishes. Resources created through the API can have shorter, independent lifetimes. For example, destroy application-created groups and field groups when they are no longer needed, stop explicit watches with UnwatchFields, and cancel contexts used by policy listeners so their channels and registrations can be released.

Follow the ownership and cleanup notes for each function in the Go package reference. This is especially important for long-running services.

Policy notification channels are best-effort and must be drained promptly. Cancel their context to unregister the listener and close its channel. Use WatchPolicyViolationsForGroup to watch policies already configured for a group. The ListenForPolicyViolations* convenience functions first add any requested conditions that are missing from the group’s policy configuration. PolicyViolationDropCount reports process-wide local drops caused by full listener channels.

Troubleshoot Initialization#

If initialization reports that libdcgm.so.4 was not found, install the DCGM runtime package or make the library available to the dynamic loader.

If the Go build reports that cgo is unavailable, enable cgo and install a C compiler for the target platform.

If standalone initialization cannot connect, verify that the DCGM host engine is running and that the endpoint is reachable. If a connection-string call reports that dcgmConnect_v3 is unavailable, upgrade to DCGM 4.5 or later or use the legacy address and socket-flag arguments shown in Initialize a Connection.