v1/metrics.proto#

The Metrics API contains metrics & telemetry data queries & messages.

Services#

MetricsManagementService#

MetricsManagementService is responsible for retrieving current policy state, power usage, and other telemetry data from the system.

Currently, all metrics are retrieved via Redfish. Please see the supplemental Metrics API documentation for additional information regarding challenges & limitations of this service.

For dpsctl usage for the MetricsManagementService, see the dpsctl metrics CLI guide.

GPUMetricsQuery#

rpc GPUMetricsQuery(GPUMetricsQueryRequest) returns GPUMetricsQueryResponse

GPUMetricsQuery is used to query GPU power usage metrics from a list of node-GPU pairs.

MetricsQuery#

rpc MetricsQuery(MetricsQueryRequest) returns MetricsQueryResponse

MetricsQuery is used to retrieve standardized GPU, CPU, and memory usage metrics from a list of requested nodes.

Messages#

GPUMetricsQueryRequest#

GPUMetricsQueryRequest is used to query GPU power usage metrics from a given list of node-GPU pairs.

Each pair must specify the node name & GPU ID.

If you are unsure of the GPU IDs available on the node, you may retrieve the number of available GPUs using the MetricsQuery API. The available number of GPUs is listed under the num_gpus property, with IDs starting at zero and ranging to num_gpus - 1.

Example:

{
    "gpus": [
        {
            "node": "viking592",
            "gpu": 0
        },
        {
            "node": "viking592",
            "gpu": 1
        },
        {
            "node": "viking592",
            "gpu": 2
        },
        {
            "node": "viking593",
            "gpu": 0
        }
    ]
}

Field	Type	Description
gpus	repeated `GPUMetricsQueryRequest.GpuMetricsRequest`	List of node-GPU pairs to query. Must contain at least one item.

GPUMetricsQueryRequest.GpuMetricsRequest#

Field	Type	Description
node	`string`	Name of the node entity within the configured Topology. Must not be empty.
gpu	`uint32`	The GPU ID on the node. IDs typically range from 0 to 7

GPUMetricsQueryResponse#

{
  "metrics:" [
    {
      "node": "viking592",
      "gpu": 0,
      "usage": 700.0
    },
    {
      "node": "viking592",
      "gpu": 1,
      "usage": 698.2
    },
    {
      "node": "viking592",
      "gpu": 2,
      "usage": 700.0
    },
    {
      "node": "viking593",
      "gpu": 0,
      "usage": 374.5
    },
  ]
}

Field	Type	Description
metrics	repeated `GPUMetricsQueryResponse.GpuMetrics`	A list of node-GPU pairs with the corresponding GPU power usage

GPUMetricsQueryResponse.GpuMetrics#

Field	Type	Description
node	`string`	Name of the node entity
gpu	`uint32`	GPU ID
usage	`double`	Power usage (in watts)
oneof _gpu_uuid.gpu_uuid	optional `string`	Hardware-backed Redfish Processor UUID.

MetricsQueryRequest#

MetricsQueryRequest is used to query standardized usage metrics from the requested list of nodes.

Example:

{
    "nodes": [
        "node001",
        "node002",
        "node003",
    ]
}

Field	Type	Description
nodes	repeated `string`	nodes is the list of nodes to retrieve metrics from. Each node name must not be empty.
effective	`bool`	Read power-limit fields from BMC EnvironmentMetrics.

MetricsQueryResponse#

MetricsQueryResponse contains standardized usage metrics for GPU, CPU, and memory from the requested nodes.

Field	Type	Description
nodes	repeated `NodeMetricsResponse`	List of node metrics responses, one for each requested node

NodeMetricsResponse#

NodeMetricsResponse contains aggregated metrics for all components on a single node

Field	Type	Description
name	`string`	Name of the node
num_gpus	`uint32`	Number of GPUs present on the node
num_cpus	`uint32`	Number of CPUs present on the node
num_memory_units	`uint32`	Number of memory units (DIMMs) present on the node
power_usage	`double`	none
gpus	repeated `NodeMetricsResponse.ComponentUsage`	List of GPU usage metrics for each GPU on the node
cpus	repeated `NodeMetricsResponse.ComponentUsage`	List of CPU usage metrics for each CPU on the node
memory	repeated `NodeMetricsResponse.ComponentUsage`	List of memory usage metrics for each memory unit on the node

NodeMetricsResponse.ComponentUsage#

ComponentUsage contains power and thermal metrics for a single component (GPU, CPU, or memory). Where not available, metrics will be zero.

Field	Type	Description
id	`string`	Unique identifier for the component on the node (e.g., GPU ID typically 0-based)
power_usage	`double`	Current power consumption in watts
energy_usage	`double`	Cumulative energy consumption since last reset
energy_usage_unit	`string`	Unit for energy consumption (e.g., “Joules”)
set_limit	`double`	Currently set power limit in watts
max_limit	`double`	Maximum allowed power limit in watts
min_limit	`double`	Minimum allowed power limit in watts
temperature_celsius	`double`	Current temperature in Celsius
requested_oneshot_watts	`double`	Last oneshot OOB power-limit request observed from the BMC.
requested_persistent_watts	`double`	Last persistent OOB power-limit request observed from the BMC.
oneof _power_limit_persistency.power_limit_persistency	optional `bool`	Persistency flag for the latest OOB power-limit request.
oneof _gpu_uuid.gpu_uuid	optional `string`	Hardware-backed Redfish Processor UUID. Set only for GPU components.

Scalar Value Types#

.proto Type	Notes	C++ Type	Java Type	Python Type
double		double	double	float
float		float	float	float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long
uint32	Uses variable-length encoding.	uint32	int	int/long
uint64	Uses variable-length encoding.	uint64	long	int/long
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long
sfixed32	Always four bytes.	int32	int	int
sfixed64	Always eight bytes.	int64	long	int/long
bool		bool	boolean	boolean
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str