# Plugin Nvidia GPU

# Introducción

**Ver.** 1.0

Este plugin de agente sirve para monitorizar las estadísticas de una o más GPUs NVIDIA en un servidor. Ejecuta `nvidia-smi` y genera módulos XML que el EndPoint de Pandora FMS ingesta vía `module_plugin`.

**Tipo:** plugin de agente (binario único, zero-config)

Genera 18 módulos por GPU (Utilización, Temperatura, Memoria, Potencia, Ventilador, Reloj, Throttling, Errores ECC, Estado de Rendimiento, Nombre) más 3 globales (cantidad de GPUs, versión del driver, versión de CUDA). Total: `18N + 3` módulos (`17N + 3` con `--include-fan=false`).

# Matriz de compatibilidad

Este plugin se ha desarrollado y probado con `nvidia-smi` versión moderna. Soporta cualquier GPU NVIDIA (data-center y consumer) en los siguientes sistemas operativos:

- Linux amd64
- Linux arm64
- Windows amd64

# Pre requisitos

- **Requiere** el driver NVIDIA cargado en el equipo objetivo
- **Requiere** `nvidia-smi` accesible en el PATH (o en `C:\Program Files\NVIDIA Corporation\NVSMI\nvidia-smi.exe` en Windows)
- **Requiere** Pandora FMS EndPoint **>= 7.0** (versiones anteriores no reenvían flags arbitrarios en `module_plugin`)

Si `nvidia-smi` no está disponible o el driver no está cargado, el plugin emite un único módulo `GPU_Count=0` (CRITICAL) y termina con código 0. No requiere Python, Perl ni ningún runtime adicional.

# Configuración

#### Flags de línea de comandos

El plugin es zero-config: todos los flags tienen valor por defecto y el binario funciona sin argumentos.

```bash
## Ruta a nvidia-smi (vacío = auto-detección)
smi-path =
## Incluir módulos de velocidad de ventilador
include-fan = true
## Límite máximo de GPUs a reportar
max-count = 32
## Timeout por invocación a nvidia-smi (segundos)
smi-timeout = 10
## Modo debug (logs a stderr)
debug = false

```

**--smi-path**  
Ruta completa al binario `nvidia-smi`. Si está vacío, el plugin busca en el PATH del sistema. En Windows prueba también `C:\Program Files\NVIDIA Corporation\NVSMI\nvidia-smi.exe` y `C:\Windows\System32\nvidia-smi.exe`.

**--include-fan**  
Habilita o deshabilita el módulo de velocidad del ventilador por GPU. Útil en servidores con GPUs sin ventilador (tarjetas data-center pasivas).

**--max-count**  
Límite suave de GPUs. Si se detectan más, el plugin emite una advertencia por stderr pero sigue generando todos los módulos.

**--smi-timeout**  
Timeout en segundos para cada llamada a `nvidia-smi`. El plugin hace tres llamadas por ciclo.

**--debug**  
Activa logs detallados por stderr (útil para diagnóstico).

# Ejecución manual

Para ejecutar el plugin manualmente:

```bash
./pandora-nvidia-gpu

```

Agregando `--debug` se ven los detalles de ejecución:

```bash
./pandora-nvidia-gpu --debug

```

Al ejecutarse, devuelve un bloque XML por cada módulo:

```xml
<module>
    <name><![CDATA[GPU_0_Status]]></name>
    <type><![CDATA[generic_proc]]></type>
    <data><![CDATA[1]]></data>
    <module_group><![CDATA[GPU]]></module_group>
</module>
<module>
    <name><![CDATA[GPU_0_Utilization]]></name>
    <type><![CDATA[generic_data]]></type>
    <data><![CDATA[85.2]]></data>
    <unit><![CDATA[%]]></unit>
    <module_group><![CDATA[GPU]]></module_group>
</module>

```

# Ejecución programada

Se puede ejecutar como `module_plugin` en un agente de Pandora FMS. Agregar una de las siguientes líneas en `/etc/pandora/pandora_agent.conf` (Linux) o `pandora_agent.conf` (Windows):

```
## Zero-config (nvidia-smi auto-detectado)
module_plugin /etc/pandora/plugins/pandora-nvidia-gpu

## Servidor con GPUs sin ventilador
module_plugin /etc/pandora/plugins/pandora-nvidia-gpu --include-fan=false

## Windows con ruta explícita a nvidia-smi
module_plugin "C:\Program Files\pandora_agent\plugins\pandora-nvidia-gpu.exe" --smi-path "C:\Windows\System32\nvidia-smi.exe"

## Límite personalizado de GPUs
module_plugin /etc/pandora/plugins/pandora-nvidia-gpu --max-count 64

```

Luego reiniciar el servicio `pandora_agent` para que el cambio tenga efecto.

# Módulos generados por el plugin

Cada GPU `i` (0-indexado) genera los siguientes módulos:

<table id="bkmrk-m%C3%B3dulo-tipo-unidad-d"><thead><tr><th>Módulo</th><th>Tipo</th><th>Unidad</th><th>Descripción</th></tr></thead><tbody><tr><td>`GPU_<i>_Status`</td><td>`generic_proc`</td><td>-</td><td>1 si la GPU está detectada, 0 si no</td></tr><tr><td>`GPU_<i>_Utilization`</td><td>`generic_data`</td><td>%</td><td>Utilización de cómputo de la GPU</td></tr><tr><td>`GPU_<i>_Throttle_Active`</td><td>`generic_data`</td><td>-</td><td>Bitmask de razones de throttling activas</td></tr><tr><td>`GPU_<i>_Throttle_Reasons`</td><td>`generic_data_string`</td><td>-</td><td>Etiquetas de throttling separadas por coma</td></tr><tr><td>`GPU_<i>_Memory_Controller_Utilization`</td><td>`generic_data`</td><td>%</td><td>Utilización del controlador de memoria</td></tr><tr><td>`GPU_<i>_Memory_Used`</td><td>`generic_data`</td><td>MiB</td><td>Memoria usada</td></tr><tr><td>`GPU_<i>_Memory_Free`</td><td>`generic_data`</td><td>MiB</td><td>Memoria libre</td></tr><tr><td>`GPU_<i>_Memory_Total`</td><td>`generic_data`</td><td>MiB</td><td>Memoria total</td></tr><tr><td>`GPU_<i>_Memory_Used_Percent`</td><td>`generic_data`</td><td>%</td><td>(usada/total) \* 100 redondeado a 1 decimal</td></tr><tr><td>`GPU_<i>_Temperature`</td><td>`generic_data`</td><td>°C</td><td>Temperatura de la GPU</td></tr><tr><td>`GPU_<i>_Power_Draw`</td><td>`generic_data`</td><td>W</td><td>Consumo actual de energía</td></tr><tr><td>`GPU_<i>_Power_Limit`</td><td>`generic_data`</td><td>W</td><td>Límite de energía</td></tr><tr><td>`GPU_<i>_Fan_Speed`</td><td>`generic_data`</td><td>%</td><td>Velocidad del ventilador (omitido con `--include-fan=false`)</td></tr><tr><td>`GPU_<i>_Graphics_Clock`</td><td>`generic_data`</td><td>MHz</td><td>Frecuencia del reloj de gráficos</td></tr><tr><td>`GPU_<i>_Performance_State`</td><td>`generic_data_string`</td><td>-</td><td>Etiqueta del estado de rendimiento (ej: P0)</td></tr><tr><td>`GPU_<i>_Performance_State_Number`</td><td>`generic_data`</td><td>PNumber</td><td>Valor numérico del estado de rendimiento</td></tr><tr><td>`GPU_<i>_Critical_Errors`</td><td>`generic_data`</td><td>-</td><td>Conteo de errores ECC no corregidos</td></tr><tr><td>`GPU_<i>_Name`</td><td>`generic_data_string`</td><td>-</td><td>Nombre del modelo de GPU</td></tr></tbody></table>

## Módulos globales (3 total)

<table id="bkmrk-m%C3%B3dulo-tipo-descripc"><thead><tr><th>Módulo</th><th>Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td>`GPU_Count`</td><td>`generic_proc`</td><td>Número de GPUs detectadas (0 = CRITICAL)</td></tr><tr><td>`GPU_Driver_Version`</td><td>`generic_data_string`</td><td>Versión del driver NVIDIA</td></tr><tr><td>`GPU_CUDA_Version`</td><td>`generic_data_string`</td><td>Versión máxima de CUDA soportada</td></tr></tbody></table>

## Política de thresholds

<table id="bkmrk-m%C3%B3dulo-normal-warnin"><thead><tr><th>Módulo</th><th>Normal</th><th>Warning</th><th>Critical</th></tr></thead><tbody><tr><td>Temperature</td><td>\[0, 69\]</td><td>\[70, 89\]</td><td>\[90, 110\]</td></tr><tr><td>Memory\_Used\_Percent</td><td>\[0, 69\]</td><td>\[70, 84\]</td><td>\[85, 100\]</td></tr><tr><td>Critical\_Errors</td><td>0</td><td>(ninguno)</td><td>\[1, 1000000\]</td></tr></tbody></table>

Los thresholds están hardcodeados en el binario. Para modificarlos, usar plantillas de alerta en la consola de Pandora FMS.

## Grupos de módulos

- Todos los módulos por GPU usan `module_group=GPU`
- Los módulos globales (`GPU_Count`, `GPU_Driver_Version`, `GPU_CUDA_Version`) no tienen module\_group