Grafana Alloy Docker Compose: Monitoring einrichten

Stand: 08.10.2026

Mit Grafana Alloy Docker Compose richtest du einen schlanken Telemetrie-Agenten als Container ein. Alloy kann Metriken einsammeln, weiterverarbeiten und per Prometheus Remote Write an einen kompatiblen Empfänger senden. Diese Anleitung zeigt eine nachvollziehbare Basis für einen Linux-Host – einschließlich persistenter Daten und sicherer Übergabe von Zugangsdaten.

Auf einen Blick

• Grafana Alloy ist ein konfigurierbarer Agent für Metriken, Logs, Traces und Profile.
• Die Container-Konfiguration liegt getrennt in einer config.alloy.
• Der Storage-Pfad braucht ein Volume, damit der Write-Ahead Log einen Neustart übersteht.
• Für Host-Metriken müssen /proc, /sys und das Host-Dateisystem eingebunden sein.
• Die Weboberfläche läuft im Beispiel auf Port 12345 und sollte nicht ungeschützt ins Internet.

Was ist Grafana Alloy?

Grafana Alloy ist ein Open-Source-Agent, der Telemetriedaten über Komponenten-Pipelines verarbeitet. Eine Komponente erledigt dabei jeweils eine Aufgabe, etwa Metriken erfassen oder an ein Ziel weiterleiten. Deshalb lässt sich die Konfiguration schrittweise erweitern, ohne für jede Datenart einen separaten Agenten zu betreiben.

Für ein Homelab ist Grafana Alloy Docker Compose vor allem sinnvoll, wenn du Host-Metriken an Prometheus, Mimir oder Grafana Cloud senden möchtest. Ergänzend kannst du die Verfügbarkeit einzelner Dienste mit Uptime Kuma im Docker-Compose-Setup überwachen. Das sind jedoch zwei unterschiedliche Aufgaben: Uptime Kuma prüft Erreichbarkeit, Alloy liefert Messwerte für Auswertung und Alarmierung.

Welche Dateien brauchst du für Grafana Alloy Docker Compose?

Du brauchst eine Compose-Datei und eine Alloy-Konfiguration. Lege beide zum Beispiel in einem eigenen Verzeichnis ab. Die offizielle Docker-Dokumentation verwendet /etc/alloy/config.alloy als Konfigurationspfad und /var/lib/alloy/data als Storage-Pfad. Genau diese Pfade nutzt das folgende Beispiel.

docker-compose.yml

services:
  alloy:
    image: grafana/alloy:latest
    command: ["run", "--server.http.listen-addr=0.0.0.0:12345", "--storage.path=/var/lib/alloy/data", "/etc/alloy/config.alloy"]
    ports: ["127.0.0.1:12345:12345"]
    volumes: ["./config.alloy:/etc/alloy/config.alloy:ro", "alloy-data:/var/lib/alloy/data", "/:/host:ro,rslave", "/proc:/host/proc:ro", "/sys:/host/sys:ro"]
    restart: unless-stopped
volumes:
  alloy-data:

Die Variante mit latest folgt dem offiziellen Docker-Beispiel. Für planbare Updates solltest du nach dem ersten erfolgreichen Betrieb stattdessen einen konkreten Release-Tag einsetzen. Laut Grafana zeigt latest stets auf die jüngste stabile Version; ein Tag im Format grafana/alloy:<VERSION> pinnt eine bestimmte Version.

Der Port ist bewusst nur an 127.0.0.1 gebunden. Dadurch erreichst du die Alloy-Oberfläche lokal, etwa über einen SSH-Tunnel, veröffentlichst sie aber nicht automatisch im Netzwerk. Ein Reverse Proxy ist erst dann sinnvoll, wenn du Authentifizierung und Zugriff sauber regelst. Für das Grundprinzip hilft auch der Beitrag zum Traefik-Setup im Homelab.

Wie sieht die Alloy-Konfiguration für Host-Metriken aus?

Die folgende config.alloy nutzt den offiziellen prometheus.exporter.unix-Baustein. Er basiert auf node_exporter und stellt zahlreiche Hardware- und Betriebssystem-Metriken bereit. Die danach folgende Scrape-Komponente liest diese Metriken aus und leitet sie an Remote Write weiter.

prometheus.exporter.unix "host" {
  rootfs_path = "/host"
  procfs_path = "/host/proc"
  sysfs_path = "/host/sys"
}
prometheus.scrape "host" {
  targets = prometheus.exporter.unix.host.targets
  forward_to = [prometheus.remote_write.default.receiver]
}
prometheus.remote_write "default" {
  endpoint {
    url = sys.env("REMOTE_WRITE_URL")
    basic_auth {
      username = sys.env("REMOTE_WRITE_USERNAME")
      password = sys.env("REMOTE_WRITE_PASSWORD")
    }
  }
}

Ergänze die drei Umgebungsvariablen in deiner lokalen, nicht eingecheckten Compose-Umgebung. Der Remote-Write-Endpunkt ist zwingend, während die Authentifizierung vom Zielsystem abhängt. Grafanas Referenz zeigt ebenfalls eine Übergabe von Benutzername und API-Schlüssel über Umgebungsvariablen. Schreibe solche Werte daher nicht in die Git-versionierte config.alloy.

Alloy verknüpft die Komponenten über Exporte: Der Unix-Exporter stellt Ziele bereit, prometheus.scrape übernimmt sie und übergibt die Messwerte an den Receiver von prometheus.remote_write. So ist die Datenflussrichtung im Code sichtbar. Für Kubernetes gilt ein anderes Bereitstellungsmodell; die Grundlagen zur Auswertung findest du in Kubernetes-Monitoring mit Grafana und Prometheus.

Wie startest und prüfst du den Container?

Starte den Stack im Verzeichnis der Compose-Datei. Danach prüfst du zunächst die Logs und anschließend die Weboberfläche. Ein Fehler beim Remote-Write-Ziel verhindert zwar nicht zwingend das Starten, ist aber in den Logs sichtbar.

1. Lege docker-compose.yml und config.alloy ab.
2. Setze die benötigten Remote-Write-Variablen in deiner geschützten lokalen Umgebung.
3. Starte mit docker compose up -d.
4. Prüfe mit docker compose logs alloy, ob Alloy die Konfiguration akzeptiert.
5. Öffne lokal http://localhost:12345.

Die offizielle Dokumentation nennt das Laden der Alloy-UI ohne Fehler als Prüfung für einen erfolgreichen Start. Wenn du bereits Docker-Services betreibst, ergänze zusätzlich passende Healthchecks; die Anleitung zum Docker-Healthcheck in Compose erklärt, wie du deren Zustand sichtbar machst.

Warum ist persistenter Storage bei Remote Write wichtig?

Persistenter Storage ist wichtig, weil prometheus.remote_write einen Write-Ahead Log, kurz WAL, nutzt. Dieser puffert Messwerte, wenn das Ziel zeitweise nicht erreichbar ist, und hilft beim Wiederanlauf. Ohne das Volume unter /var/lib/alloy/data verliert der Container diesen lokalen Zustand beim Neuerstellen.

Der WAL ist jedoch kein unbegrenztes Archiv. Grafana beschreibt konfigurierbare Aufbewahrungs- und Bereinigungsintervalle. Deshalb solltest du ausreichend Plattenplatz einplanen und einen dauerhaft nicht erreichbaren Endpoint beheben, statt nur das Datenverzeichnis zu löschen. Das Löschen eines WAL entfernt gespeicherte, noch nicht übertragene Daten endgültig.

Welche typischen Fehler gibt es bei Grafana Alloy Docker Compose?

Vermeide außerdem doppelte Scrapes desselben Ziels durch mehrere Agenten. Laut der Remote-Write-Dokumentation können daraus Meldungen zu nicht chronologischen Messwerten entstehen. Entscheide deshalb klar, welcher Agent welche Targets einsammelt.

Fazit

Grafana Alloy Docker Compose ist eine solide Basis für zentrale Metriken im Homelab. Mit einer getrennten Konfigurationsdatei, einem persistierten Storage-Pfad und nicht im Code abgelegten Zugangsdaten bleibt das Setup wartbar. Starte klein mit Host-Metriken und ergänze weitere Komponenten erst, wenn Datenziel und Verantwortlichkeiten klar sind.

Quellen

• Grafana Alloy: Docker-Installation
• Grafana Alloy: prometheus.exporter.unix
• Grafana Alloy: prometheus.remote_write
• Grafana Alloy: Komponenten

Häufige Fragen