all-smi 0.26.2

// Copyright 2025 Lablup Inc. and Jeongkyu Shin
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
//! Prometheus snapshot serializer.
//!
//! Delegates to the shared
//! [`crate::api::metrics::render::render_prometheus_exposition`] helper so
//! the output is byte-for-byte identical to what the `/metrics` endpoint of
//! `all-smi api` emits for the same inputs. This upholds the acceptance
//! criterion:
//!
//! > `all-smi snapshot --format prometheus` byte-for-byte matches a single
//! > scrape of `api` mode's `/metrics` for the same data.
//!
//! Caveat: both code paths today pass `RuntimeEnvironment::default()`,
//! empty `vgpu_info`, and empty `mig_info` because neither
//! `api::server::run_api_mode` nor the snapshot collector populates those
//! extras. When (and if) one path starts populating them, the other must
//! follow to keep parity.

use anyhow::Result;

use crate::api::metrics::render::{MetricsRenderInputs, render_prometheus_exposition};
use crate::snapshot::Snapshot;
use crate::utils::RuntimeEnvironment;

/// Render a *single* snapshot to the Prometheus exposition format.
///
/// Prometheus scrape semantics are inherently single-sample, so the caller
/// already capped the samples list to one entry. Any soft reader errors
/// accumulated in `snap.errors` are written to stderr rather than injected
/// into the exposition, since Prometheus parsers reject unknown comment
/// lines on some scrapers.
pub fn render(snapshots: &[Snapshot]) -> Result<String> {
    // `run_with_collector` caps Prometheus output at a single sample; guard
    // defensively in case a future caller reuses this function.
    let snap = snapshots
        .first()
        .ok_or_else(|| anyhow::anyhow!("Prometheus serializer requires at least one snapshot"))?;

    // Empty slices for sections the snapshot did not collect so the
    // per-section exporters stay silent — matching `api::server::run_api_mode`
    // which leaves vgpu/mig empty and uses the default `RuntimeEnvironment`.
    let runtime_env = RuntimeEnvironment::default();
    let empty_vgpu = Vec::new();
    let empty_mig = Vec::new();

    let inputs = MetricsRenderInputs {
        gpu_info: snap.gpus.as_deref().unwrap_or(&[]),
        process_info: snap.processes.as_deref().unwrap_or(&[]),
        cpu_info: snap.cpus.as_deref().unwrap_or(&[]),
        memory_info: snap.memory.as_deref().unwrap_or(&[]),
        storage_info: snap.storage.as_deref().unwrap_or(&[]),
        runtime_environment: &runtime_env,
        chassis_info: snap.chassis.as_deref().unwrap_or(&[]),
        vgpu_info: &empty_vgpu,
        mig_info: &empty_mig,
        // Snapshot mode is one-shot; no integrator state exists to
        // expose. Leaving this `None` keeps `snapshot --format
        // prometheus` byte-for-byte identical to a single `api`
        // scrape taken before any energy samples have been recorded.
        energy_integrator: None,
        // The snapshot path collects synchronously and only reaches this
        // serializer once that collection has returned, so by the time
        // `all_smi_up` is rendered the cycle this output describes has
        // completed. Reporting 0 here would be false (issue #324).
        //
        // `snap.errors` being non-empty does not change this: a partial
        // collection is still a completed cycle, and per-reader failures
        // are reported on stderr below rather than by pretending the
        // exporter never ran.
        ready: true,
    };

    let out = render_prometheus_exposition(&inputs);

    // Surface reader errors on stderr rather than polluting the exposition.
    for err in &snap.errors {
        eprintln!(
            "snapshot: {section} reader {kind}: {message}",
            section = err.section,
            kind = err.kind,
            message = err.message
        );
    }

    Ok(out)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::device::GpuInfo;
    use crate::snapshot::Snapshot;
    use std::collections::HashMap;

    fn make_gpu() -> GpuInfo {
        GpuInfo {
            uuid: "GPU-0".to_string(),
            time: "2026-04-20T00:00:00Z".to_string(),
            name: "Test GPU".to_string(),
            device_type: "GPU".to_string(),
            host_id: "host0".to_string(),
            hostname: "host0".to_string(),
            instance: "host0:9090".to_string(),
            utilization: 50.0,
            ane_utilization: 0.0,
            dla_utilization: None,
            tensorcore_utilization: None,
            temperature: 55,
            used_memory: 2048,
            total_memory: 8192,
            frequency: 1500,
            power_consumption: 200.0,
            gpu_core_count: None,
            temperature_threshold_slowdown: None,
            temperature_threshold_shutdown: None,
            temperature_threshold_max_operating: None,
            temperature_threshold_acoustic: None,
            performance_state: None,
            fan_speed_rpm: None,
            numa_node_id: None,
            gsp_firmware_mode: None,
            gsp_firmware_version: None,
            nvlink_remote_devices: Vec::new(),
            gpm_metrics: None,
            detail: HashMap::new(),
        }
    }

    /// Supersedes the former `empty_snapshot_renders_empty_string`, the
    /// snapshot-side twin of `empty_inputs_render_empty_string`. Both
    /// asserted the behaviour issue #324 removed. A snapshot that
    /// collected no sections still renders the baseline, and must keep
    /// reporting `all_smi_up 1`: the collection ran, it simply had
    /// nothing to report, which is precisely the case that used to be
    /// indistinguishable from "the exporter has not started yet".
    #[test]
    fn empty_snapshot_still_renders_the_baseline() {
        let snap = Snapshot {
            schema: 1,
            timestamp: "2026-04-20T00:00:00Z".to_string(),
            hostname: "host0".to_string(),
            gpus: None,
            cpus: None,
            memory: None,
            chassis: None,
            processes: None,
            storage: None,
            errors: Vec::new(),
        };
        let rendered = render(&[snap]).unwrap();
        assert!(!rendered.is_empty());

        let up = rendered
            .lines()
            .find(|l| l.starts_with("all_smi_up{"))
            .expect("all_smi_up sample line");
        assert!(
            up.ends_with(" 1"),
            "a completed one-shot collection is up, even with no sections: {up}"
        );
        assert!(rendered.contains("all_smi_build_info{"));

        // Nothing beyond the baseline: the device exporters must still
        // self-filter on a snapshot that collected nothing.
        for line in rendered.lines().filter(|l| !l.starts_with('#')) {
            assert!(
                line.starts_with("all_smi_up{") || line.starts_with("all_smi_build_info{"),
                "unexpected sample from an empty snapshot: {line}"
            );
        }
    }

    #[test]
    fn gpu_snapshot_produces_expected_metric_names() {
        let snap = Snapshot {
            schema: 1,
            timestamp: "2026-04-20T00:00:00Z".to_string(),
            hostname: "host0".to_string(),
            gpus: Some(vec![make_gpu()]),
            cpus: None,
            memory: None,
            chassis: None,
            processes: None,
            storage: None,
            errors: Vec::new(),
        };
        let rendered = render(&[snap]).unwrap();
        assert!(
            rendered.contains("all_smi_gpu_utilization"),
            "missing GPU utilization metric: {rendered}"
        );
        assert!(rendered.contains("all_smi_gpu_memory_used_bytes"));
        assert!(rendered.contains("all_smi_gpu_temperature_celsius"));
    }

    #[test]
    fn empty_inputs_return_error() {
        let result = render(&[]);
        assert!(result.is_err());
    }
}