Prometheus Metrics

View as Markdown

This page is the full reference for Prometheus metrics exposed by the Cluster Readiness Engine (CRE) controller. All metrics are registered with the controller-runtime metrics registry and served on the /metrics endpoint.

Scrape configuration

The Helm chart ships a ServiceMonitor for the Prometheus Operator (enabled by default via metrics.serviceMonitor.enabled):

1apiVersion: monitoring.coreos.com/v1
2kind: ServiceMonitor
3metadata:
4 name: cluster-readiness-engine-metrics-monitor
5 namespace: cluster-readiness-engine
6spec:
7 endpoints:
8 - path: /metrics
9 port: https
10 scheme: https
11 bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token
12 tlsConfig:
13 insecureSkipVerify: true # Use cert-manager in production
14 selector:
15 matchLabels:
16 control-plane: manager

Job status metrics

MetricTypeLabelsDescription
cre_job_statusGaugenamespace, job, workflow, statusCurrent status of burn-in Jobs. Value is 1 for the current status, 0 for others. Status values: in_progress, succeeded, failed.

The gauge is set for all three status values on each update, ensuring that a transition from in_progress to succeeded also zeroes out the in_progress series. Metrics are cleaned up when a Job is deleted.

Hardware failure metrics

MetricTypeLabelsDescription
cre_hardware_failed_jobs_totalCounternamespace, job, workflowTotal number of Jobs that detected hardware failures. Incremented once per Job on first detection.
cre_job_failed_nodesGaugenamespace, job, workflowNumber of nodes with detected hardware failures per Job.
cre_hardware_failures_detected_totalCounternamespace, job, workflow, nodeTotal number of hardware failures detected across all evaluations. Per-node granularity.

Node health check metrics

MetricTypeLabelsDescription
cre_node_health_check_duration_secondsHistogramnamespace, job, workflowDuration of node health check operations in seconds. Buckets: 1ms to ~16s (exponential).
cre_nodes_evaluated_totalCounternamespace, job, workflowTotal number of node health evaluations performed.

Reconciliation metrics

MetricTypeLabelsDescription
cre_reconcile_totalCounternamespace, job, workflow, resultTotal number of reconciliation attempts. result values: success, error, requeue.
cre_reconcile_duration_secondsHistogramnamespace, job, workflowDuration of reconciliation operations in seconds. Buckets: 10ms to ~20s (exponential).

Workload metrics

MetricTypeLabelsDescription
cre_workload_created_totalCounternamespace, job, workflowTotal number of workloads created by the Job controller.

Goodput metrics

All goodput metrics share the same label set: namespace, measurement, job, workflow.

MetricTypeDescription
cre_goodput_ratioGaugeRuntime goodput ratio (0.0 to 1.0)
cre_goodput_avg_tflops_per_gpuGaugeAverage TFLOPS per GPU from goodput measurement
cre_goodput_training_time_secondsGaugeTotal training wall-clock time in seconds
cre_goodput_reschedule_time_secondsGaugeCumulative reschedule time in seconds
cre_goodput_resume_time_secondsGaugeCumulative resume time in seconds
cre_goodput_checkpoint_save_time_secondsGaugeCumulative checkpoint save time in seconds
cre_goodput_warmup_time_secondsGaugeTotal warmup step time in seconds
cre_goodput_non_warmup_time_secondsGaugeTotal non-warmup step time in seconds
cre_goodput_avg_step_time_secondsGaugeAverage time per training step in seconds
cre_goodput_lost_work_time_secondsGaugeCumulative lost work time in seconds (work done after last checkpoint, lost on restart)

Goodput metrics are cleaned up when a GoodputMeasurement is deleted.

Metric lifecycle

Goodput metrics are cleaned up at specific lifecycle events to prevent stale data in Prometheus:

EventWhat is cleaned upWhat is preserved
Job completes (succeeded or failed)Operational metrics (every cre_goodput_* gauge except the ratio: TFLOPS, step time, training/warmup/non-warmup time, checkpoint, reschedule, resume, lost work)cre_goodput_ratio (the outcome)
Job restarts from checkpointInstantaneous metrics (TFLOPS, avg step time)All cumulative metrics
GoodputMeasurement deletedAll goodput metrics for that measurement
BandwidthMeasurement completes or is deletedAll NCCL bandwidth metrics for that measurement

NCCL bandwidth metrics

All NCCL bandwidth metrics share the same label set: namespace, measurement, job, workflow, nccl_test, message_size_bytes.

MetricTypeDescription
cre_nccl_algbw_gbpsGaugeNCCL algorithmic bandwidth in GB/s per message size
cre_nccl_busbw_gbpsGaugeNCCL bus bandwidth in GB/s per message size

The nccl_test label identifies the collective operation (e.g., all_reduce, all_gather, alltoall). The message_size_bytes label tracks results per message size tested.

NCCL bandwidth metrics are cleaned up when a BandwidthMeasurement is deleted.

Cardinality at scale: NCCL metrics include a message_size_bytes label (typically 20-30 values per test). With 3 test types and 10 concurrent measurements, expect ~600-900 NCCL time series. Goodput metrics produce 10 series per measurement. At 100+ concurrent Jobs, monitor your Prometheus memory and consider increasing sampleInterval or limiting concurrent Certifications.

Topology metrics

MetricTypeLabelsDescription
cre_topology_validated_nodesGaugenamespace, workflow, topology_key, domain, nodeSet to 1 for each node that passed burn-in validation. Per-node granularity for identifying exactly which nodes are certified in each topology domain.
cre_topology_failed_nodesGaugenamespace, workflow, topology_key, domain, nodeSet to 1 for each node that failed burn-in validation. Useful for identifying bad switches, racks, or NVLink cliques from Prometheus.

Example PromQL queries

Job status

# Count of failed jobs
count(cre_job_status{status="failed"} == 1) by (namespace)
# All currently running jobs
cre_job_status{status="in_progress"} == 1
# Job status breakdown per namespace
sum by (namespace, status) (cre_job_status == 1)

Hardware failures

# Nodes with hardware failures across all jobs
count(cre_hardware_failures_detected_total) by (node)
# Hardware failure rate (per hour)
sum(rate(cre_hardware_failures_detected_total[1h])) by (namespace)
# Jobs with the most failed nodes
topk(10, cre_job_failed_nodes)

Goodput

# Average goodput across all measurements in a namespace
avg(cre_goodput_ratio) by (namespace)
# Jobs with low goodput (below 80%)
cre_goodput_ratio < 0.8
# Training time breakdown for a specific job
{__name__=~"cre_goodput_(training|reschedule|resume|checkpoint_save|warmup|non_warmup)_time_seconds", job="my-training-job"}
# Average TFLOPS per GPU across measurements
avg(cre_goodput_avg_tflops_per_gpu) by (namespace)

NCCL bandwidth

# Bus bandwidth for all_reduce across all message sizes
cre_nccl_busbw_gbps{nccl_test="all_reduce"}
# Average algorithmic bandwidth per test type
avg(cre_nccl_algbw_gbps) by (nccl_test)
# Compare bandwidth across message sizes for a specific measurement
cre_nccl_algbw_gbps{measurement="nccl-allreduce-bw"}

Reconciliation performance

# Reconciliation error rate
sum(rate(cre_reconcile_total{result="error"}[5m])) by (namespace)
# 99th percentile reconciliation duration
histogram_quantile(0.99, sum(rate(cre_reconcile_duration_seconds_bucket[5m])) by (le))
# Node health check duration (p95)
histogram_quantile(0.95, sum(rate(cre_node_health_check_duration_seconds_bucket[5m])) by (le))

Topology validation

# Nodes validated per topology domain
cre_topology_validated_nodes{topology_key="nvidia.com/gpu.clique"}
# Total validated nodes per workflow
sum(cre_topology_validated_nodes) by (namespace, workflow)

Example alerting rules

The following PrometheusRule examples provide starting points for monitoring a burn-in cluster.

1apiVersion: monitoring.coreos.com/v1
2kind: PrometheusRule
3metadata:
4 name: cre-alerts
5 labels:
6 app.kubernetes.io/name: cluster-readiness-engine
7spec:
8 groups:
9 - name: burnin.rules
10 rules:
11 # Alert when hardware failure rate exceeds threshold
12 - alert: CREHighHardwareFailureRate
13 expr: |
14 sum(rate(cre_hardware_failures_detected_total[1h])) by (namespace) > 0.5
15 for: 10m
16 labels:
17 severity: critical
18 annotations:
19 summary: "High hardware failure rate in namespace {{ $labels.namespace }}"
20 description: >
21 More than 0.5 hardware failures per second detected in
22 namespace {{ $labels.namespace }} over the last hour.
23
24 # Alert when goodput drops below acceptable threshold
25 - alert: CRELowGoodput
26 expr: |
27 cre_goodput_ratio < 0.75
28 and cre_goodput_ratio > 0
29 for: 15m
30 labels:
31 severity: warning
32 annotations:
33 summary: "Low goodput for measurement {{ $labels.measurement }}"
34 description: >
35 Goodput ratio for {{ $labels.measurement }} in
36 {{ $labels.namespace }} is {{ $value | humanize }},
37 below the 75% threshold. Check for frequent checkpointing
38 or rescheduling overhead.
39
40 # Alert when a job appears stuck (in_progress for too long)
41 - alert: CREJobStuck
42 expr: |
43 cre_job_status{status="in_progress"} == 1
44 unless on(namespace, job) (
45 increase(cre_reconcile_total[30m]) > 0
46 )
47 for: 30m
48 labels:
49 severity: warning
50 annotations:
51 summary: "CRE job {{ $labels.job }} appears stuck"
52 description: >
53 Job {{ $labels.job }} in namespace {{ $labels.namespace }}
54 has been in_progress for at least 30 minutes with no
55 reconciliation activity.

See also