Loki Docker Compose bündelt Container-Logs in einer durchsuchbaren Oberfläche: Grafana zeigt die Daten an, Alloy liest Docker-Container aus und Loki speichert sowie durchsucht sie. Dieser Leitfaden setzt den offiziellen Loki-Compose-Stack nachvollziehbar auf und zeigt, welche Grenzen er für den Produktivbetrieb hat.

Stand: 17.11.2026

Auf einen Blick

  • Der offizielle Compose-Stack startet Loki, Grafana, Alloy, MinIO, Gateway und einen Log-Generator.
  • Alloy entdeckt Docker-Container über den Docker-Socket und sendet ihre Logs an Loki.
  • Die Endpunkte /ready auf Port 3101 und 3102 prüfen getrennt Lese- und Schreibpfad.
  • Containername, Umgebung und Anwendung sind sinnvolle Labels; IDs und Request-IDs gehören nicht in Labels.
  • Für Produktion empfiehlt Grafana statt Docker Compose eine Installation mit Helm oder Tanka.

1. Die Ausgangslage und das Ziel

Mit Loki Docker Compose baust du eine lokale, zentrale Logsuche für Docker-Container auf. Das Ergebnis ist kein bloßer Log-Viewer: Alloy erkennt laufende Container, versieht sie mit einem Container-Label und schreibt die Zeilen über das Gateway in Loki. Grafana verbindet sich bereits mit der Loki-Datenquelle.

Der praktische Nutzen entsteht bei der Fehlersuche: Statt auf jedem Host einzelne Container-Ausgaben zu öffnen, grenzt du eine Suche nach Anwendung oder Container im selben Werkzeug ein. Loki Docker Compose liefert dafür absichtlich einen vollständigen, kleinen Datenfluss. Du siehst also sowohl die Quelle der Logs als auch die Speicherung und die Abfrageoberfläche.

Der offizielle Einstieg ist ausdrücklich für Evaluierung, Tests und Entwicklung gedacht. Grafana dokumentiert, dass die zugehörigen Dateien Loki als einzelne Binärdatei ausführen, und empfiehlt für Produktion Helm oder Tanka. Plane diesen Stack deshalb als Lern-, Labor- oder Vorbereitungsumgebung ein, nicht als unkritisch übernommene Produktionsarchitektur.

Wenn Docker Compose noch neu für dich ist, erklärt der Beitrag Docker Compose Grundlagen das Modell aus Diensten, Netzwerken und Volumes. Für die Überwachung der Dienste ergänzt ein sauberer Docker-Healthcheck die Logsuche sinnvoll.

Teil 1 – Voraussetzungen und Architektur

2. Was der Compose-Stack tatsächlich bereitstellt

Die Architektur trennt Annahme und Abfrage der Logs. Der Gateway-Dienst leitet Schreibanfragen an write und Suchanfragen an read; der Dienst backend übernimmt im offiziellen Beispiel die Hintergrundrolle. MinIO stellt den S3-kompatiblen Speicher bereit. Dadurch ist sichtbar, warum nicht jeder Browser oder Container direkt auf einen Loki-Interna-Port zugreifen muss.

Alloy hat Zugriff auf /var/run/docker.sock. Das ist notwendig, damit discovery.docker Container findet und loki.source.docker deren Logs lesen kann. Gleichzeitig ist dieser Mount besonders privilegiert. Setze ihn daher nur in einem vertrauenswürdigen, lokalen Monitoring-Stack ein und veröffentliche den Socket nie über einen Reverse Proxy.

Für Loki Docker Compose bedeutet diese Aufteilung auch: Grafana ist der Arbeitsplatz zum Lesen, Loki ist der Logdienst und Alloy ist der Sammler. MinIO ist im Beispiel nicht als allgemeiner Dateispeicher gedacht, sondern stellt den S3-kompatiblen Speicher für Loki bereit. Das Gateway ist wiederum die feste Adresse, an die Alloy schreibt und von der Grafana liest.

Architektur des offiziellen Loki-Docker-Compose-Beispiels mit Alloy, Gateway, Loki-Lese- und Schreibpfad, MinIO und Grafana.
Alloy sammelt Docker-Logs; das Gateway trennt Schreib- und Abfrageweg im offiziellen Beispiel.

Der mitgelieferte Stack enthält zusätzlich flog. Dieser Dienst erzeugt JSON-Logs im Abstand von 200 Millisekunden. Deshalb kannst du die Suche unmittelbar ausprobieren, ohne erst eine eigene Anwendung umzubauen. Bereits vorhandenes Infrastruktur-Monitoring bleibt davon getrennt: Node Exporter mit Docker Compose sammelt Metriken, während Loki Logzeilen verwaltet.

3. Verzeichnis vorbereiten und Dateien aus der offiziellen Version laden

Lege zuerst ein eigenes Arbeitsverzeichnis an. Das verhindert, dass Konfigurationsdateien mit anderen Compose-Projekten vermischt werden.

mkdir loki
cd loki

Erfolg erkennst du daran, dass die Shell anschließend im neuen Verzeichnis arbeitet.

Lade danach die drei Dateien aus dem offiziellen Beispiel für Loki 3.7.0. Die Version steht in der offiziellen Installationsanleitung; verwende für dieses Tutorial genau dieselben zusammenpassenden Beispieldateien.

wget https://raw.githubusercontent.com/grafana/loki/v3.7.0/examples/getting-started/docker-compose.yaml -O docker-compose.yaml
wget https://raw.githubusercontent.com/grafana/loki/v3.7.0/examples/getting-started/alloy-local-config.yaml -O alloy-local-config.yaml
wget https://raw.githubusercontent.com/grafana/loki/v3.7.0/examples/getting-started/loki-config.yaml -O loki-config.yaml

Danach müssen die drei Dateien im aktuellen Verzeichnis liegen. Ändere sie zunächst nicht: Der Stack verweist genau auf diese Namen.

Die drei Dateien erfüllen unterschiedliche Aufgaben. docker-compose.yaml beschreibt die Container und ihre Verbindungen. alloy-local-config.yaml beschreibt Erkennung, Relabeling und Weiterleitung der Docker-Logs. loki-config.yaml legt dagegen Schema, Speicher und Ring fest. Diese Trennung hilft bei späteren Änderungen: Suche erst in der Datei, die für genau diesen Teil verantwortlich ist.

4. Die zentralen Dienste verstehen

Die folgenden Ausschnitte stammen aus dem offiziellen Compose-Beispiel. read veröffentlicht Port 3101, write Port 3102; beide verwenden dieselbe Loki-Konfiguration und prüfen ihre Gesundheit mit /usr/bin/loki -health. Die Trennung macht die späteren Bereitschaftsprüfungen eindeutig.

read:
  image: grafana/loki:latest
  command: "-config.file=/etc/loki/config.yaml -target=read"
  ports:
    - 3101:3100
  volumes:
    - ./loki-config.yaml:/etc/loki/config.yaml
  healthcheck:
    test: [ "CMD", "/usr/bin/loki", "-health" ]

write:
  image: grafana/loki:latest
  command: "-config.file=/etc/loki/config.yaml -target=write"
  ports:
    - 3102:3100
  volumes:
    - ./loki-config.yaml:/etc/loki/config.yaml

Beim Start erzeugt Compose die Dienste als Container. Ein Status Started für loki-loki-1, loki-grafana-1 und loki-alloy-1 entspricht der Ausgabe aus der Dokumentation.

Teil 2 – Loki Docker Compose starten

5. Stack starten und die Startausgabe einordnen

Starte Loki Docker Compose im Verzeichnis mit den drei geladenen Dateien. Der Dokumentationsbefehl läuft im Vordergrund, damit du Fehler und die ersten Logzeilen direkt siehst.

docker-compose -f docker-compose.yaml up

Erfolg erkennst du an der offiziellen Startmeldung mit gestarteten Containern, zum Beispiel:

✔ Container loki-loki-1      Started
✔ Container loki-grafana-1   Started
✔ Container loki-alloy-1     Started

Öffne anschließend Grafana auf http://localhost:3000. Die Beispielkonfiguration legt eine Loki-Datenquelle an und verwendet dafür das interne Gateway unter http://gateway:3100 mit dem Mandanten tenant1. Die anonyme Admin-Rolle in diesem Beispiel ist ein weiterer Grund, den Stack nicht unverändert ins Internet zu stellen.

Lass den ersten Lauf bewusst klein. Der Stack enthält mit flog bereits eine Quelle für Logdaten; damit lassen sich Verkabelung und Suche prüfen, bevor eigene Dienste dazukommen. Erst wenn diese Basiskette funktioniert, ist eine zusätzliche Anwendung ein aussagekräftiger Test. Andernfalls bleibt unklar, ob ein Fehler aus der Anwendung, aus Alloy oder aus Loki stammt.

6. Wie Alloy Container findet und Logs weiterleitet

Alloy ist der Collector des Beispiels. Er fragt den Docker-Socket im Abstand von fünf Sekunden ab, übernimmt den Docker-Containernamen als Label container und leitet an den Loki-Writer weiter. Damit bleibt das Label für die Abfrage nützlich, ohne automatisch eine kurzlebige ID zum Index hinzuzufügen.

discovery.docker "flog_scrape" {
  host             = "unix:///var/run/docker.sock"
  refresh_interval = "5s"
}

discovery.relabel "flog_scrape" {
  targets = []
  rule {
    source_labels = ["__meta_docker_container_name"]
    regex         = "/(.*)"
    target_label  = "container"
  }
}

Der Erfolg besteht darin, dass Alloy Ziele an loki.source.docker übergibt; die Konfiguration verbindet diese Quelle mit dem Writer.

loki.source.docker "flog_scrape" {
  host             = "unix:///var/run/docker.sock"
  targets          = discovery.docker.flog_scrape.targets
  forward_to       = [loki.write.default.receiver]
  relabel_rules    = discovery.relabel.flog_scrape.rules
  refresh_interval = "5s"
}

loki.write "default" {
  endpoint {
    url       = "http://gateway:3100/loki/api/v1/push"
    tenant_id = "tenant1"
  }
}

Der Collector schreibt damit nicht direkt zu read oder backend, sondern zum Gateway. Diese Route ist wichtig, weil das Gateway im Beispiel Schreib- und Lese-API unterschiedlich weiterleitet.

Damit wird auch die Fehlersuche strukturierter. Fehlen Container in der Auswahl, prüfst du zuerst Erkennung und Socket-Mount bei Alloy. Existiert ein Container-Label, aber es kommen keine neuen Zeilen an, ist der Weg von Alloy über das Gateway zum Schreibpfad relevant. Liefert eine gespeicherte Suche nichts, prüfst du anschließend Lesepfad und Grafana-Datenquelle. Loki Docker Compose macht diese drei Ebenen im Beispiel sichtbar.

Ablauf vom Docker-Container über Alloy und Gateway in Loki bis zur Abfrage in Grafana.
Der Logfluss wird zuerst geschrieben und danach über den Lesepfad in Grafana abgefragt.

Teil 3 – Datenmodell und sinnvolle Abfragen

7. Labels bewusst klein halten

Labels bestimmen, welche Streams Loki bildet. Laut der Loki-Dokumentation zu Labels eignen sich Region, Cluster, Server, Anwendung, Namespace und Umgebung, weil ihre Werte begrenzt sind. Der Containername aus dem Beispiel ist ebenfalls ein nachvollziehbarer Startpunkt.

Vermeide dagegen Request-ID, Bestellnummer oder Trace-ID als Label. Viele Kombinationen vergrößern den Index und erzeugen kleine Chunks, was die Leistung verschlechtern kann. Suche solche Werte stattdessen als Textfilter in der Logzeile. Die Dokumentation zeigt dafür beispielsweise folgende Abfrage:

{logGroup="group1"} |= "requestId=32422355"

Erfolg bedeutet hier nicht „möglichst viele Labels“, sondern ein stabiles Schema. Ergänze ein Label nur, wenn es regelmäßig zur Auswahl oder Filterung genutzt wird.

Ein guter erster Satz an Labels beschreibt, woher ein Log stammt und zu welcher dauerhaft bekannten Anwendung es gehört. Ein schlechter erster Satz kopiert jede Eigenschaft aus dem Ereignis. Der Unterschied ist wichtig: Ein Containername oder eine Umgebung hilft viele Zeilen zu gruppieren; eine individuelle Anfrage identifiziert fast nur eine einzige Zeile. Deshalb gehören selten gesuchte, kurzlebige Werte als Suchtext in die Logzeile.

8. Speicher und Schema nicht blind umstellen

Das offizielle Cluster-Beispiel nutzt TSDB mit Schema v13 und einen S3-kompatiblen Speicher. Im Compose-Beispiel übernimmt MinIO diese Rolle. Die folgenden Parameter erklären die wesentlichen Beziehungen, sie sind aber kein Ersatz für eine produktionsreife Speicherplanung.

schema_config:
  configs:
    - from: 2023-01-01
      store: tsdb
      object_store: s3
      schema: v13
      index:
        prefix: index_
        period: 24h
common:
  path_prefix: /loki
  replication_factor: 1

Erfolg erkennst du daran, dass alle Dienste dieselbe geladene loki-config.yaml verwenden und der Stack seine Healthchecks besteht. Für einen rein lokalen Loki nennt die Konfigurationsreferenz alternativ Dateisystemspeicher mit object_store: filesystem; das ist eine andere Architekturentscheidung, keine kosmetische Änderung.

9. Entscheidungshilfe: Compose-Beispiel oder anderer Betrieb?

SituationPassender WegBegründung
Evaluation, Test, EntwicklungOffizieller Loki-Docker-Compose-StackGrafana dokumentiert diesen Installationsweg genau für diese Zwecke.
ProduktionsbetriebHelm oder Tanka prüfenDas ist die ausdrückliche Empfehlung der Installationsdokumentation für Produktion.
Docker-Host mit Log-CollectorAlloy aus dem BeispielGrafana verweist zum Senden von Logs auf Alloy.
Loki Docker DriverNur bewusst einsetzenDer Treiber ist ein Drittanbieter-Client ohne dieselbe Support-Zusage wie Alloy.

Ein Treiber-Plugin ist nicht nötig, um den offiziellen Compose-Stack zu nutzen. Falls du es dennoch getrennt evaluierst, dokumentiert Grafana die Installation pro Docker-Host für AMD64 wie folgt:

docker plugin install grafana/loki-docker-driver:3.7.0-amd64 --alias loki --grant-all-permissions

Auf ARM64 verlangt die Dokumentation das Suffix -arm64. Ein erfolgreich installiertes Plugin erscheint bei der Prüfung als aktiviert.

docker plugin ls

Erwartet wird eine Zeile mit dem Namen loki und ENABLED auf true. Der Treiber puffert bei Nichterreichbarkeit Logs im Speicher; unbegrenzte Wiederholungen können laut Dokumentation den Docker-Daemon warten lassen. Deshalb ist Alloy die robustere Ausgangsbasis dieses Leitfadens.

Das ist auch eine Entscheidung über Betriebsrisiko. Der Docker-Driver kann Container-Logs an eine private Loki-Instanz senden, trägt aber laut Dokumentation nicht dieselbe Support-Zusage wie Alloy. Loki Docker Compose verwendet daher nicht den Driver, sondern die dokumentierte Alloy-Quelle. So bleibt der Aufbau näher an der aktuellen Empfehlung der Loki-Dokumentation.

Die wichtigsten Stolperfallen

Grafana oder Loki sind nach außen erreichbar

Symptom: Die Ports des Beispiels sind vom falschen Netz aus erreichbar. Ursache: Compose veröffentlicht im offiziellen Beispiel unter anderem Grafana auf 3000 und Gateway auf 3100. Lösung: Betreibe den Evaluierungsstack nur im vertrauenswürdigen Netz und übernimm die anonyme Grafana-Admin-Konfiguration nicht als Internetdienst.

Alloy findet keine Container

Symptom: In Grafana erscheinen keine Container-Logs. Ursache: Die Collector-Konfiguration benötigt den Mount von /var/run/docker.sock und fragt ihn über unix:///var/run/docker.sock ab. Lösung: Prüfe, ob der Mount im Alloy-Dienst vorhanden ist und ob Alloy die geladene Konfigurationsdatei lesen kann.

Zu viele oder instabile Labels

Symptom: Der Index wächst, Streams fragmentieren oder Abfragen werden schlechter. Ursache: Dynamische Werte erzeugen viele Label-Kombinationen. Lösung: Nutze begrenzte, langlebige Labels und filtere Request-IDs oder ähnliche Werte im Logtext.

Der Docker-Driver blockiert bei Loki-Ausfall

Symptom: Der Docker-Daemon wartet sehr lange. Ursache: Bei loki-retries=0 versucht der Treiber laut Dokumentation unbegrenzt erneut, während er Logs verarbeitet. Lösung: Verwende Alloy oder setze beim Treiber begrenzte Wiederholungen, kurze Backoffs und keep-file=true nach der Treiber-Dokumentation.

Der Stack wird als Produktionsvorlage missverstanden

Symptom: Ein Test-Compose-Setup soll ohne Betriebsdesign produktive Logs tragen. Ursache: Die Installationsseite ordnet Docker und Compose Evaluation, Test und Entwicklung zu. Lösung: Plane für Produktion Helm oder Tanka und prüfe Speicher, Zugriff und Betriebsverantwortung separat.

Verifikation: So prüfst du, dass alles läuft

Prüfe zuerst die Container. Die offizielle Installationsanleitung erwartet bei einem laufenden Einzelcontainer einen Status Up und eine Portabbildung für 3100; im Compose-Stack müssen die bereitgestellten Dienste ebenfalls laufen.

docker container ls

Erfolg erkennst du an laufenden Containern; die Dokumentation zeigt für Loki zum Beispiel STATUS Up und eine Zuordnung von Port 3100.

Prüfe dann die beiden dokumentierten Bereitschafts-URLs im Browser: http://localhost:3101/ready für den Lesepfad sowie http://localhost:3102/ready für den Schreibpfad. Die dazugehörigen Metriken liegen laut Installationsdokumentation auf /metrics derselben Ports.

Zum Schluss öffnest du http://localhost:3000, wählst die vorkonfigurierte Loki-Datenquelle und suchst nach dem Container-Label. Weil flog kontinuierlich Logzeilen erzeugt, sollte der Collector nach seinem dokumentierten Fünf-Sekunden-Refresh Daten anliefern. Ergänze anschließend eigene Anwendungen schrittweise und kontrolliere jedes neue Label auf begrenzte Werte.

Dokumentiere bei diesem Test auch, welche Abfrage du benutzt hast und wann sie erstmals Ergebnisse lieferte. Das ist kein Ersatz für eine automatisierte Überwachung, aber eine klare Abnahme für Loki Docker Compose: Quelle vorhanden, Collector verbunden, Schreibpfad bereit, Lesepfad bereit und Daten in Grafana sichtbar. Treten später Lücken auf, lässt sich mit denselben fünf Punkten gezielt vergleichen.

Für die nächste Ausbaustufe helfen der Beitrag Grafana Alloy mit Docker Compose und die Anleitung Kubernetes Monitoring mit Grafana und Prometheus. So bleiben Metriken, Logs und eine spätere Kubernetes-Architektur fachlich sauber verbunden.

Fazit

Loki Docker Compose ist ein nachvollziehbarer Weg, Docker-Logs mit Loki, Alloy und Grafana zu erkunden. Die offizielle Beispielarchitektur zeigt den kompletten Fluss vom Docker-Socket über Alloy und Gateway bis zur Abfrage. Halte Labels klein und stabil, behandle den Docker-Socket als privilegierten Zugriff und prüfe die getrennten Readiness-Endpunkte. Für produktive Anforderungen führt der dokumentierte nächste Schritt zu Helm oder Tanka. Damit bleibt der Laboraufbau nützlich, ohne seine dokumentierten Grenzen zu verschleiern.

Quellen

Häufige Fragen

Ist Loki Docker Compose für Produktion geeignet?

Die Grafana-Dokumentation ordnet Docker und Docker Compose für Loki Evaluation, Tests und Entwicklung zu. Für Produktion empfiehlt sie Helm oder Tanka.

Welche Ports prüfe ich beim offiziellen Loki-Compose-Beispiel?

Der Lesepfad ist auf http://localhost:3101/ready erreichbar, der Schreibpfad auf http://localhost:3102/ready. Die jeweiligen Metriken liegen unter /metrics.

Warum nutzt das Beispiel Grafana Alloy?

Alloy entdeckt Docker-Container über den Docker-Socket und leitet ihre Logs an Loki weiter. Die Loki-Dokumentation verweist für das Senden von Logs auf Alloy.

Welche Labels sollte ich in Loki verwenden?

Nutze begrenzte, langlebige Werte wie Anwendung, Umgebung, Server oder Container. Request-IDs und andere kurzlebige Werte solltest du in der Logzeile filtern statt sie als Label zu indexieren.

Warum fehlen Docker-Logs in Grafana?

Prüfe zuerst, ob Alloy Zugriff auf /var/run/docker.sock hat und die Collector-Konfiguration geladen wurde. Danach prüfst du die Readiness des Schreibpfads und die Loki-Datenquelle in Grafana.