> 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/de/modul-9-monitoring-und-fehlerbehebung/04-prometheus-grafana.md).

# Prometheus- und Grafana-Integration

## Warum externe Metriken wichtig sind

Das VergeOS-Dashboard bietet Echtzeit-Zustand und Analysen, aber Unternehmensüberwachungsstrategien erfordern typischerweise einen zentralen Time-Series-Speicher, der Metriken über mehrere Systeme hinweg aggregieren, Daten über das 45-Tage-Fenster in der UI hinaus aufbewahren und ausgefeilte Alarmierungsregeln auslösen kann. Der **vergeos-exporter** schließt diese Lücke, indem er VergeOS-Metriken im Prometheus-Format bereitstellt -- dem De-facto-Standard für Cloud-native Überwachung.

Wenn der Exporter läuft, erhalten Sie langfristige Trendanalysen, systemübergreifende Korrelation und Integration in bestehende Alarmierungspipelines -- alles ohne Änderungen am VergeOS-System selbst.

```mermaid
graph LR
    subgraph vergeos["VergeOS-Umgebung"]
        API["VergeOS-REST-API"]
    end

    subgraph monitoring["Überwachungs-Stack"]
        EXP["vergeos-exporter<br/>:9888/metrics"]
        PROM["Prometheus<br/>Abrufen & Speichern"]
        GRAF["Grafana<br/>Dashboards"]
        ALERT["AlertManager<br/>Benachrichtigungen"]
    end

    API -->|"API-Aufrufe<br/>(auflisten/lesen)"| EXP
    EXP -->|"Pull-basiertes<br/>Abrufen"| PROM
    PROM --> GRAF
    PROM --> ALERT
    ALERT -->|"E-Mail, Slack,<br/>PagerDuty"| OPS["Ops-Team"]

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

## Der vergeos-exporter

Das **vergeos-exporter** ist ein Open-Source-Tool, das von Verge im [verge-io/vergeos-exporter](https://github.com/verge-io/vergeos-exporter) GitHub-Repository gepflegt wird. Es verbindet sich mit der VergeOS-REST-API, sammelt Infrastrukturmetriken und stellt sie an einem HTTP-Endpunkt bereit, den Prometheus in einem konfigurierbaren Intervall abruft.

### Verfügbare Metriken

Der Exporter sammelt drei Kategorien von Metriken:

### vSAN-Tier-Metriken

Kapazität, Nutzung und Zuweisung pro Tier. Transaktions- und Reparaturzähler. Überwachung des Laufwerkstatus (online, offline, repairing, initializing, verifying, noredundant, outofspace). Laufwerkstemperatur- und Gesundheitsdaten. Lese-/Schreibvorgänge und IOPS.

### Cluster-Metriken

Knotenzahl pro Cluster. RAM-, CPU- und Festplattenauslastung. Synchronisierungsstatus und Zustand.

### Knotenmetriken

CPU- und Speichernutzung pro Knoten. Netzwerkdurchsatz und Latenz. Servicestatus pro Knoten.

Eine vollständige Metrik-Referenz ist in der `metrics.md` -Datei im Repository des Exporters verfügbar.

### Architektur: Pull-basiertes Abrufen

Der vergeos-exporter folgt dem standardmäßigen Prometheus-Pull-Modell. Prometheus initiiert die Verbindung, indem es den `/metrics` -Endpunkt am Exporter in einem konfigurierten Intervall abruft (typischerweise 15–60 Sekunden). Dieser Ansatz bedeutet:

* **Keine eingehenden Firewall-Regeln** sind auf dem VergeOS-System selbst erforderlich
* Der Exporter kann auf **jedem Host** mit Netzwerkzugriff auf die VergeOS-API ausgeführt werden
* Mehrere Prometheus-Instanzen können denselben Exporter für HA abrufen
* Der Exporter ist **AlertManager-kompatibel** -- Prometheus-Alarmierungsregeln funktionieren nativ mit den bereitgestellten Metriken

## Konfiguration des Dienstkontos

Bevor Sie den Exporter bereitstellen, erstellen Sie in VergeOS ein dediziertes Dienstkonto mit minimalen Berechtigungen.

### Schritt für Schritt: Dienstkonto für den Exporter erstellen

1. Navigieren Sie zu **System → Benutzer** in der VergeOS-UI
2. Klicken Sie auf **Neu** um einen neuen Benutzer zu erstellen
3. Füllen Sie das **Neuer Benutzer** -Formular aus:
   * **Benutzername:** `prometheus-exporter` (oder ein ähnlicher beschreibender Name)
   * **Typ:** `API`
   * **Passwort:** einen starken, zufällig generierten Wert
   * **Zwei-Faktor-Authentifizierung:** lassen Sie **deaktiviert** -- der Exporter authentifiziert sich per API-Benutzername/-Passwort
4. Klicken Sie auf **Senden** um zu speichern

Neue normale/API-Benutzer erhalten **standardmäßig Auflisten/Lesen für alles** was genau das ist, was der Exporter benötigt. Um den Umfang weiter zu verkleinern, schränken Sie die Berechtigungen unter **System → Berechtigungen** ein, nachdem der Benutzer erstellt wurde.

{% hint style="warning" %}
**Sicherheits-Best-Practice**

Verwenden Sie niemals ein Administratorkonto für den Exporter. Das Dienstkonto benötigt nur Lese- und Auflistungszugriff, um Metriken abzufragen, lassen Sie also die Standardeinstellungen bestehen oder schränken Sie sie unter **System → Berechtigungen** ein -- und gleichen Sie die Maschine-zu-Maschine-Anmeldedaten durch ein starkes, zufällig generiertes Passwort und die Einschränkung des Netzwerkzugriffs auf den Exporter-Host aus.
{% endhint %}

## Bereitstellungsoptionen

Der vergeos-exporter unterstützt mehrere Bereitstellungsmodelle. Wählen Sie dasjenige, das am besten zu Ihrer Überwachungsinfrastruktur passt.

### Option 1: Standalone-Binary

Vorgefertigte Binaries sind für Linux, Windows und macOS (amd64 und arm64) auf der [GitHub-Releases](https://github.com/verge-io/vergeos-exporter/releases) -Seite verfügbar.

```bash
# Herunterladen und entpacken (Linux-amd64-Beispiel)
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

# Mit den erforderlichen Flags ausführen
./vergeos-exporter \
  -verge.url https://your-vergeos-host \
  -verge.username prometheus-exporter \
  -verge.password 'YourStrongPassword'
```

Der Exporter lauscht standardmäßig auf Port **9888** . Überschreiben Sie ihn bei Bedarf mit dem `-web.listen-address` -Flag.

### Option 2: Linux-Systemd-Dienst

Für produktive Linux-Bereitstellungen führen Sie den Exporter als verwalteten systemd-Dienst aus:

```ini
# /etc/systemd/system/vergeos-exporter.service
[Unit]
Description=VergeOS Prometheus Exporter
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
# Dienstbenutzer erstellen, aktivieren und starten
sudo useradd -r -s /usr/sbin/nologin vergeos_exporter
sudo systemctl daemon-reload
sudo systemctl enable --now vergeos-exporter
```

### Option 3: Windows-Dienst (NSSM)

Auf Windows-Überwachungs-Hosts verwenden Sie [NSSM (Non-Sucking Service Manager)](https://nssm.cc/) um den Exporter als Windows-Dienst auszuführen:

1. Laden Sie NSSM herunter und platzieren Sie `nssm.exe` an einem dauerhaften Speicherort (z. B. `C:\Program Files\nssm\`)
2. Registrieren Sie den Dienst:

```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
```

### Option 4: Docker Compose

Das Repository enthält ein vorgefertigtes Docker-Compose-Beispiel unter `examples/docker-compose/` das den Exporter, Prometheus und Grafana in einem einzigen Stack bündelt -- ideal für schnelle Evaluierungen oder Laborumgebungen.

```yaml
# Vereinfachte Struktur von 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"
```

Das Docker-Compose-Beispiel lädt automatisch das richtige plattformspezifische Binary für Ihre Architektur herunter.

## Prometheus-Konfiguration

Fügen Sie den Exporter in Ihrer `prometheus.yml`:

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

Zum Überwachen mehrerer VergeOS-Umgebungen stellen Sie pro Umgebung einen Exporter bereit und fügen Sie jeden als separates Ziel hinzu (oder verwenden Sie Prometheus-Relabeling für dynamische Erkennung).

## Grafana-Dashboard

Der vergeos-exporter wird mit einem vorkonfigurierten Grafana-Dashboard ausgeliefert (`examples/grafana-dashboard.json`), das vSAN-, Cluster- und Knotenmetriken sofort abdeckt.

### Enthaltene Dashboard-Bereiche

| Kategorie            | Bedienfelder                                                                     |
| -------------------- | -------------------------------------------------------------------------------- |
| **vSAN-Performance** | Anzeigen für Tier-Kapazität und -Nutzung, IOPS-Diagramme, Lese-/Schreibdurchsatz |
| **Cluster-Zustand**  | Knotenzahl, Synchronisierungsstatus, aggregierte CPU- und RAM-Auslastung         |
| **Knotendetails**    | CPU, Speicher, Netzwerkdurchsatz und Temperatur pro Knoten                       |
| **Speicherzustand**  | Laufwerkszustände, Reparaturstatus, Fehlerzähler                                 |

### Importieren des Dashboards

1. Öffnen Sie Grafana und navigieren Sie zu **Dashboards → Import**
2. Klicken Sie auf **JSON-Datei hochladen** und wählen Sie die `grafana-dashboard.json` aus dem Exporter-Repository aus
3. Wählen Sie Ihre **Prometheus-Datenquelle** aus dem Dropdown-Menü
4. Klicken Sie auf **Importieren**

Das Dashboard ist sofort funktionsfähig, sobald Prometheus Exporter-Metriken empfängt.

## Verifizierung

Überprüfen Sie nach der Bereitstellung, ob der Exporter Metriken sammelt:

```bash
# Den Metrik-Endpunkt direkt testen
curl -s http://localhost:9888/metrics | head -20

# Erwartete Ausgabe enthält Zeilen wie:
# HELP vergeos_vsan_tier_capacity_bytes Gesamtkapazität pro vSAN-Tier
# TYPE vergeos_vsan_tier_capacity_bytes gauge
# vergeos_vsan_tier_capacity_bytes{tier="1"} 1.234567e+12
```

Wenn der Endpunkt Metriken zurückgibt, ruft Prometheus sie automatisch beim nächsten Intervall ab. Prüfen Sie die Prometheus- **Ziele** -Seite (`http://prometheus:9090/targets`), um zu bestätigen, dass der `vergeos` Job den Status **UP**.

### Checkliste zur Fehlerbehebung

| Symptom                      | Prüfen Sie                                                                                           |
| ---------------------------- | ---------------------------------------------------------------------------------------------------- |
| Keine Metriken zurückgegeben | Vergewissern Sie sich, dass die VergeOS-URL, der Benutzername und das Passwort korrekt sind          |
| Verbindung abgelehnt         | Bestätigen Sie, dass der Exporter-Prozess läuft und auf 9888 lauscht                                 |
| Authentifizierungsfehler     | Bestätigen Sie, dass das Dienstkonto **Typ = API** mit **Zwei-Faktor-Authentifizierung** deaktiviert |
| Teilweise Metriken           | Vergewissern Sie sich, dass das Dienstkonto **Auflisten und Lesen** -Berechtigungen                  |
| Prometheus-Ziel DOWN         | Prüfen Sie die Netzwerkkonnektivität zwischen Prometheus und dem Exporter-Host                       |
| Scrape-Timeout               | Erhöhen Sie `-scrape.timeout` (Standard 30 s) für große Umgebungen                                   |

## Integration mit AlertManager

Da der Exporter Standard-Prometheus-Metriken bereitstellt, können Sie Alarmierungsregeln schreiben, die ausgelöst werden, wenn Schwellenwerte überschritten werden:

```yaml
# Beispiel-Alarmierungsregeln für vergeos-Metriken
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: "vSAN-Tier {{ $labels.tier }} liegt über 85 % Kapazität"

      - alert: DriveOffline
        expr: vergeos_vsan_drive_state{state="offline"} > 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "Laufwerk {{ $labels.drive }} ist auf Knoten {{ $labels.node }} offline"
```

AlertManager kann diese Alarme an E-Mail, Slack, PagerDuty, OpsGenie oder einen beliebigen Webhook-Endpunkt weiterleiten -- und so das VergeOS-Monitoring in Ihren bestehenden Vorfallmanagement-Workflow integrieren.

## Alternative: Direkte API-Integration mit Zabbix

Wenn Ihre Organisation Zabbix statt Prometheus verwendet, können Sie die VergeOS-REST-API direkt mit Zabbix HTTP-Agent-Elementen abfragen:

1. Erstellen Sie ein API-Token über **System → API-Dokumentation** (Swagger UI)
2. Verwenden Sie Zabbix-HTTP-Agent-Elemente, um Endpunkte abzufragen wie `/api/v4/vms`, `/api/v4/nodes`, `/api/v4/vnets`
3. Authentifizieren Sie sich per POST an `/api/sys/tokens` und übergeben Sie das Sitzungstoken im `x-yottabyte-token` -Header

Der Prometheus-Exporter bleibt für die meisten Umgebungen der empfohlene Ansatz, da er einen umfangreicheren Metriksatz und ein vorgefertigtes Dashboard bietet.

{% hint style="info" %}
**Kommen Sie von VMware oder Nutanix?**

VergeOS stellt Plattformmetriken über die **vergeos-exporter**bereit, die vSAN-, Cluster- und Knotendaten im standardmäßigen Prometheus-Format darstellt. Prometheus ruft den Exporter per Pull-Verfahren auf Port **9888** und Grafana rendert das gebündelte Dashboard -- so fließen VergeOS-Metriken in denselben Prometheus + Grafana-Stack, den viele Teams bereits parallel zu ihren bestehenden Plattformen betreiben.
{% endhint %}

## Wichtige Erkenntnisse

* Das **vergeos-exporter** stellt vSAN-, Cluster- und Knotenmetriken auf Port **9888** im standardmäßigen Prometheus-Format bereit
* Erstellen Sie ein **dediziertes API-Dienstkonto** -- Auflisten/Lesen für alles ist die Standardeinstellung für neue Normal/API-Benutzer
* Bereitstellung als Standalone-Binary, systemd-Dienst, Windows-Dienst (NSSM) oder Docker-Compose-Stack
* Das gebündelte **Grafana-Dashboard** bietet sofortige Einblicke in Speicher-, Cluster- und Knoten-Zustand
* Prometheus **AlertManager** Integration ermöglicht proaktive Alarmierung bei Kapazitäts-, Laufwerkszustands- und Leistungsschwellenwerten
* Der Exporter verwendet **pull-basiertes Abrufen** -- keine eingehenden Firewall-Änderungen am VergeOS-System erforderlich


---

# 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/de/modul-9-monitoring-und-fehlerbehebung/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.