> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/learn-the-platform/es/modulo-9-supervision-y-resolucion-de-problemas/04-prometheus-grafana.md).

# Integración con Prometheus y Grafana

## Por qué importan las métricas externas

El panel de VergeOS proporciona salud y analíticas en tiempo real, pero las estrategias de monitoreo empresarial suelen requerir un almacén centralizado de series temporales que pueda agregar métricas entre múltiples sistemas, conservar datos más allá de la ventana de 45 días en la interfaz y activar reglas de alertas sofisticadas. La **vergeos-exporter** salva esta brecha al exponer métricas de VergeOS en formato Prometheus, el estándar de facto para el monitoreo nativo de la nube.

Con el exportador en ejecución, obtienes análisis de tendencias a largo plazo, correlación entre sistemas e integración con canalizaciones de alertas existentes, todo sin modificar el propio sistema VergeOS.

```mermaid
graph LR
    subgraph vergeos["Entorno VergeOS"]
        API["API REST de VergeOS"]
    end

    subgraph monitoring["Pila de monitoreo"]
        EXP["vergeos-exporter<br/>:9888/metrics"]
        PROM["Prometheus<br/>Raspado y almacenamiento"]
        GRAF["Paneles de Grafana"]
        ALERT["Notificaciones de AlertManager"]
    end

    API -->|"Llamadas a la API<br/>(list/read)"| EXP
    EXP -->|"Raspado<br/>basado en pull"| PROM
    PROM --> GRAF
    PROM --> ALERT
    ALERT -->|"Email, Slack,<br/>PagerDuty"| OPS["Equipo de operaciones"]

    style vergeos fill:#f0f4ff,stroke:#336
    style monitoring fill:#f0fff4,stroke:#363
```

## El vergeos-exporter

La **vergeos-exporter** es una herramienta de código abierto mantenida por Verge en el [repositorio de GitHub verge-io/vergeos-exporter](https://github.com/verge-io/vergeos-exporter) Repositorio de GitHub. Se conecta a la API REST de VergeOS, recopila métricas de la infraestructura y las expone en un extremo HTTP que Prometheus raspa a un intervalo configurable.

### Métricas expuestas

El exportador recopila tres categorías de métricas:

### Métricas de nivel vSAN

Capacidad, uso y asignación por nivel. Conteos de transacciones y reparaciones. Supervisión del estado de las unidades (online, offline, reparando, inicializando, verificando, sin redundancia, sin espacio). Temperatura y datos de estado de las unidades. Operaciones de lectura/escritura e IOPS.

### Métricas del clúster

Cantidad de nodos por clúster. Utilización de RAM, CPU y disco. Estado de sincronización y salud.

### Métricas de nodo

Uso de CPU y memoria por nodo. Rendimiento y latencia de la red. Estado de los servicios por nodo.

Una referencia completa de métricas está disponible en el `metrics.md` archivo del repositorio del exportador.

### Arquitectura: extracción basada en pull

El vergeos-exporter sigue el modelo pull estándar de Prometheus. Prometheus inicia la conexión raspando el `/metrics` extremo del exportador en un intervalo configurado (normalmente 15–60 segundos). Este enfoque significa:

* **No se requieren** reglas de firewall entrantes
* en el propio sistema VergeOS **Cualquier host** con acceso de red a la API de VergeOS
* Múltiples instancias de Prometheus pueden raspar el mismo exportador para HA
* El exportador es **compatible con AlertManager** -- las reglas de alerta de Prometheus funcionan de forma nativa con las métricas expuestas

## Configuración de la cuenta de servicio

Antes de desplegar el exportador, crea una cuenta de servicio dedicada en VergeOS con privilegios mínimos.

### Paso a paso: crear la cuenta de servicio del exportador

1. Vaya a **Sistema → Usuarios** en la interfaz de VergeOS
2. Haga clic en **Nuevo** para crear un nuevo usuario
3. Rellena el formulario **Nuevo usuario** :
   * **Nombre de usuario:** `prometheus-exporter` (o un nombre descriptivo similar)
   * **Tipo:** `API`
   * **Contraseña:** un valor fuerte, generado aleatoriamente
   * **Autenticación de dos factores:** deja **sin marcar** -- el exportador se autentica mediante nombre de usuario y contraseña de la API
4. Haga clic en **Enviar** para guardar

Los nuevos usuarios Normal/API obtienen **list/read en todo** de forma predeterminada, que es exactamente lo que necesita el exportador. Para restringir más el alcance, limita las concesiones en **Sistema → Permisos** después de crear el usuario.

{% hint style="warning" %}
**Mejor práctica de seguridad**

Nunca uses una cuenta de administrador para el exportador. La cuenta de servicio solo necesita acceso de listado y lectura para consultar métricas, así que deja los valores predeterminados o restríngelos en **Sistema → Permisos** -- y compensa la credencial máquina a máquina usando una contraseña fuerte, generada aleatoriamente, y restringiendo el acceso de red al host del exportador.
{% endhint %}

## Opciones de implementación

El vergeos-exporter admite múltiples modelos de despliegue. Elige el que mejor se adapte a tu infraestructura de monitoreo.

### Opción 1: binario independiente

Hay binarios precompilados disponibles para Linux, Windows y macOS (amd64 y arm64) en la [página de GitHub Releases](https://github.com/verge-io/vergeos-exporter/releases) .

```bash
# Descargar y extraer (ejemplo Linux amd64)
wget https://github.com/verge-io/vergeos-exporter/releases/latest/download/vergeos-exporter-linux-amd64.tar.gz
tar xzf vergeos-exporter-linux-amd64.tar.gz

# Ejecutar con las banderas requeridas
./vergeos-exporter \\
  -verge.url https://your-vergeos-host \\
  -verge.username prometheus-exporter \\
  -verge.password 'YourStrongPassword'
```

El exportador escucha en el puerto **9888** de forma predeterminada. Sobrescribe con la `-web.listen-address` si es necesario.

### Opción 2: servicio systemd de Linux

Para implementaciones Linux de producción, ejecuta el exportador como un servicio systemd administrado:

```ini
# /etc/systemd/system/vergeos-exporter.service
[Unit]
Description=Exportador de Prometheus de VergeOS
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=vergeos_exporter
ExecStart=/usr/local/bin/vergeos-exporter \\
  -verge.url https://your-vergeos-host \\
  -verge.username prometheus-exporter \\
  -verge.password 'YourStrongPassword'
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```bash
# Crear el usuario del servicio, habilitar y arrancar
sudo useradd -r -s /usr/sbin/nologin vergeos_exporter
sudo systemctl daemon-reload
sudo systemctl enable --now vergeos-exporter
```

### Opción 3: servicio de Windows (NSSM)

En hosts de monitoreo Windows, usa [NSSM (Non-Sucking Service Manager)](https://nssm.cc/) para ejecutar el exportador como un servicio de Windows:

1. Descarga NSSM y coloca `nssm.exe` en una ubicación permanente (por ejemplo, `C:\Program Files\nssm\`)
2. Registra el servicio:

```powershell
nssm install vergeos-exporter "C:\monitoring\vergeos-exporter.exe"
nssm set vergeos-exporter AppParameters "-verge.url https://your-vergeos-host -verge.username prometheus-exporter -verge.password YourStrongPassword"
nssm set vergeos-exporter Start SERVICE_AUTO_START
nssm start vergeos-exporter
```

### Opción 4: Docker Compose

El repositorio incluye un ejemplo de Docker Compose listo para usar en `examples/docker-compose/` que agrupa el exportador, Prometheus y Grafana en una sola pila, ideal para evaluaciones rápidas o entornos de laboratorio.

```yaml
# Estructura simplificada de docker-compose.yml
services:
  vergeos-exporter:
    image: vergeos-exporter:latest
    ports:
      - "9888:9888"
    environment:
      - VERGE_URL=https://your-vergeos-host
      - VERGE_USERNAME=prometheus-exporter
      - VERGE_PASSWORD=YourStrongPassword

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
```

El ejemplo de Docker Compose recupera automáticamente el binario correcto específico para tu arquitectura.

## Configuración de Prometheus

Añade el exportador como un destino de scraping en tu `prometheus.yml`:

```yaml
scrape_configs:
  - job_name: "vergeos"
    scrape_interval: 30s
    scrape_timeout: 30s
    static_configs:
      - targets: ["exporter-host:9888"]
        labels:
          environment: "producción"
          cluster: "site-a"
```

Para monitorear múltiples entornos VergeOS, despliega un exportador por entorno y añade cada uno como un destino separado (o usa relabeling de Prometheus para descubrimiento dinámico).

## Panel de Grafana

El vergeos-exporter incluye un panel de Grafana preconfigurado (`examples/grafana-dashboard.json`) que cubre métricas de vSAN, clúster y nodo desde el primer momento.

### Los paneles del dashboard incluyen

| Categoría                    | Paneles                                                                                      |
| ---------------------------- | -------------------------------------------------------------------------------------------- |
| **Rendimiento de vSAN**      | Indicadores de capacidad y uso por nivel, gráficos de IOPS, rendimiento de lectura/escritura |
| **Salud del clúster**        | Cantidad de nodos, estado de sincronización, utilización agregada de CPU y RAM               |
| **Detalles del nodo**        | CPU, memoria, rendimiento de red y temperatura por nodo                                      |
| **Salud del almacenamiento** | Estados de las unidades, estado de reparación, contadores de errores                         |

### Importar el panel

1. Abre Grafana y ve a **Paneles → Importar**
2. Haga clic en **Subir archivo JSON** y selecciona el `grafana-dashboard.json` del repositorio del exportador
3. Selecciona tu **fuente de datos de Prometheus** en el menú desplegable
4. Haga clic en **Importar**

El panel funciona inmediatamente una vez que Prometheus está recibiendo métricas del exportador.

## Verificación

Después del despliegue, verifica que el exportador esté recopilando métricas:

```bash
# Probar directamente el extremo de métricas
curl -s http://localhost:9888/metrics | head -20

# La salida esperada incluye líneas como:
# HELP vergeos_vsan_tier_capacity_bytes Capacidad total por nivel vSAN
# TYPE vergeos_vsan_tier_capacity_bytes gauge
# vergeos_vsan_tier_capacity_bytes{tier="1"} 1.234567e+12
```

Si el extremo devuelve métricas, Prometheus las raspará automáticamente en su siguiente intervalo. Consulta la página de **Destinos** de Prometheus (`http://prometheus:9090/targets`) para confirmar que el `vergeos` trabajo muestra un estado **UP**.

### Lista de verificación de solución de problemas

| Síntoma                      | Compruebe                                                                                             |
| ---------------------------- | ----------------------------------------------------------------------------------------------------- |
| No se devolvieron métricas   | Verifica que la URL, el nombre de usuario y la contraseña de VergeOS sean correctos                   |
| Conexión rechazada           | Confirma que el proceso del exportador está en ejecución y escuchando en 9888                         |
| Error de autenticación       | Confirma que la cuenta de servicio es **Type = API** con **Autenticación de dos factores** sin marcar |
| Métricas parciales           | Verifica que la cuenta de servicio tenga **list y read** permisos                                     |
| Destino de Prometheus CAÍDO  | Comprueba la conectividad de red entre Prometheus y el host del exportador                            |
| Tiempo de espera de scraping | Aumenta `-scrape.timeout` (30 s por defecto) para entornos grandes                                    |

## Integración con AlertManager

Como el exportador expone métricas estándar de Prometheus, puedes escribir reglas de alerta que se activen cuando se superen los umbrales:

```yaml
# Ejemplo de reglas de alerta para métricas de Verge
groups:
  - name: vergeos_alerts
    rules:
      - alert: VSANTierNearCapacity
        expr: vergeos_vsan_tier_usage_bytes / vergeos_vsan_tier_capacity_bytes > 0.85
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "El nivel vSAN {{ $labels.tier }} supera el 85% de capacidad"

      - alert: DriveOffline
        expr: vergeos_vsan_drive_state{state="offline"} > 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "La unidad {{ $labels.drive }} está offline en el nodo {{ $labels.node }}"
```

AlertManager puede enrutar estas alertas a email, Slack, PagerDuty, OpsGenie o cualquier extremo webhook, integrando el monitoreo de VergeOS en tu flujo de trabajo existente de gestión de incidentes.

## Alternativa: integración directa de API con Zabbix

Si tu organización usa Zabbix en lugar de Prometheus, puedes consultar directamente la API REST de VergeOS usando elementos HTTP Agent de Zabbix:

1. Crea un token de API mediante **Sistema → Documentación de la API** (Swagger UI)
2. Usa elementos HTTP Agent de Zabbix para consultar extremos como `/api/v4/vms`, `/api/v4/nodes`, `/api/v4/vnets`
3. Autentícate haciendo POST a `/api/sys/tokens` y pasando el token de sesión en el `x-yottabyte-token` encabezado

El exportador de Prometheus sigue siendo el enfoque recomendado para la mayoría de los entornos debido a su conjunto de métricas más rico y su panel ya preparado.

{% hint style="info" %}
**¿Vienes de VMware o Nutanix?**

VergeOS expone métricas de la plataforma a través de la **vergeos-exporter**, que presenta datos de vSAN, clúster y nodo en formato estándar de Prometheus. Prometheus realiza scraping pull del exportador en el puerto **9888** y Grafana renderiza el panel incluido, de modo que las métricas de VergeOS fluyen hacia la misma pila Prometheus + Grafana que muchos equipos ya ejecutan junto con sus plataformas existentes.
{% endhint %}

## Puntos clave

* La **vergeos-exporter** expone métricas de vSAN, clúster y nodo en el puerto **9888** en formato estándar de Prometheus
* Crea una **cuenta de servicio dedicada de tipo API** -- list/read en todo es el valor predeterminado para los nuevos usuarios Normal/API
* Despliega como binario independiente, servicio systemd, servicio de Windows (NSSM) o pila Docker Compose
* El **panel de Grafana** incluido proporciona visibilidad inmediata sobre la salud del almacenamiento, el clúster y los nodos
* Prometheus **AlertManager** la integración permite alertas proactivas sobre capacidad, estado de las unidades y umbrales de rendimiento
* El exportador usa **extracción basada en pull** -- no se necesitan cambios de firewall entrantes en el sistema VergeOS


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/learn-the-platform/es/modulo-9-supervision-y-resolucion-de-problemas/04-prometheus-grafana.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.