Docker: Promtail für Loki Log-Aggregation konfigurieren

Einführung

Willkommen zu diesem praktischen Lab zum Thema Loki-Konfiguration. Loki ist ein horizontal skalierbares, hochverfügbares, mandantenfähiges Log-Aggregationssystem, das von Prometheus inspiriert wurde. Es wurde entwickelt, um sehr kosteneffizient und einfach zu betreiben zu sein.

In diesem Lab konzentrieren wir uns auf den vollständigen, grundlegenden Workflow zum Sammeln und Anzeigen von Logs. Wir werden drei Schlüsselkomponenten verwenden:

Loki: Der Hauptserver, der für die Speicherung und Verarbeitung von Logs verantwortlich ist.
Promtail: Ein Agent, der lokale Log-Dateien erkennt und diese an eine Loki-Instanz sendet.
Grafana: Eine Visualisierungsplattform, mit der wir uns mit Loki verbinden, um unsere Logs zu erkunden und abzufragen.

Sie laden Loki und Grafana selbst herunter, starten sie, konfigurieren Promtail und untersuchen die Protokolle in Grafana. Die Downloads bleiben in Terminal sichtbar und können wiederholt werden.

Promtail hat am 2. März 2026 sein Lebensende erreicht. Dieses Lab behält es bei, um bestehende Promtail-Bereitstellungen zu erklären; verwenden Sie Grafana Alloy für neue Protokoll-Collector im Produktivbetrieb.

Images herunterladen und Loki und Grafana starten

In diesem Schritt bereiten Sie die Protokolldienste vor, bevor Sie den Collector konfigurieren. Loki speichert Protokolle, Grafana fragt sie ab und Promtail sendet lokale Dateien an Loki. Die Initialisierung lädt diese Dienste weder herunter noch startet sie sie.

cd /home/labex/project

Jedes feste Tag wählt die in diesem Lab verwendete Version. Downloads können mehrere Minuten dauern. Warten Sie bei jedem Befehl auf die Eingabeaufforderung. Schlägt ein Download fehl, führen Sie denselben Pull-Befehl erneut aus; Docker verwendet fertige Schichten wieder. Fahren Sie nicht fort, solange ein Download unvollständig ist.

docker pull grafana/loki:3.5.0

docker pull grafana/grafana:11.6.0

docker pull grafana/promtail:3.5.0

docker network create erstellt ein Netzwerk, in dem Container ihre Namen gegenseitig auflösen können. docker run -d startet einen Container im Hintergrund; --name benennt ihn, --network verbindet ihn mit dem Netzwerk und -p ordnet einen Host-Port einem Container-Port zu. Verwenden Sie für Grafana den Host-Port 8080, um die Plattformdienste auf Port 3000 zu umgehen. Loki verwendet die mit dem Image gelieferte Standardkonfiguration für eine einzelne Instanz.

docker network create monitoring-net

docker run -d --name loki --network monitoring-net -p 3100:3100 grafana/loki:3.5.0

docker run -d --name grafana --network monitoring-net -p 8080:3000 grafana/grafana:11.6.0

Die curl-Optionen melden HTTP-Fehler und wiederholen vorübergehende Startfehler bis zu 30-mal im Abstand von zwei Sekunden. Ein laufender Container kann sich noch initialisieren; warten Sie daher auf einen erfolgreichen Zustandsprüfung. Loki kann während der Initialisierung seines Ingesters zunächst HTTP 503 zurückgeben.

curl --fail --silent --show-error --retry 30 --retry-delay 2 --retry-connrefused --retry-all-errors http://localhost:3100/ready

curl --fail --silent --show-error --retry 30 --retry-delay 2 --retry-connrefused --retry-all-errors http://localhost:8080/api/health

Fahren Sie erst fort, wenn Loki ready zurückgibt und Grafana "database": "ok" meldet. Wird ein Dienst nicht bereit, prüfen Sie zuerst docker ps -a und seine Container-Protokolle, etwa mit docker logs grafana.

Erstellen von promtail.yml zum Scraping von Systemprotokollen

In diesem Schritt erstellen Sie eine Konfigurationsdatei für Promtail. Diese YAML-Datei teilt Promtail mit, wo sich der Loki-Server befindet und welche Log-Dateien er überwachen soll. Alle Ihre Arbeiten sollten im Verzeichnis ~/project durchgeführt werden.

Erstellen Sie zunächst mit dem nano-Editor eine neue Datei mit dem Namen promtail.yml.

nano promtail.yml

Kopieren Sie nun die folgende Konfiguration und fügen Sie sie in den nano-Editor ein.

server:
  http_listen_port: 9080
  grpc_listen_port: 0

positions:
  filename: /tmp/positions.yaml

clients:
  - url: http://loki:3100/loki/api/v1/push

scrape_configs:
  - job_name: varlogs
    static_configs:
      - targets:
          - localhost
        labels:
          job: varlogs
          __path__: /var/log/*.log

Lassen Sie uns diese Konfiguration aufschlüsseln:

server: Konfiguriert den eigenen Webserver von Promtail, der in diesem Lab nicht verwendet wird.
positions: Gibt eine Datei an, in der Promtail den zuletzt gelesenen Ort in jeder Log-Datei aufzeichnet, damit er beim Neustart keine alten Logs erneut sendet.
clients: Definiert die Adresse der Loki-Instanz. Wir verwenden http://loki:3100, da sowohl Promtail als auch Loki im selben Docker-Netzwerk laufen und loki der Containername ist.
scrape_configs: Dies ist der Kernabschnitt. Wir definieren einen job namens varlogs, der alle Dateien im Verzeichnis /var/log/ durchsucht, die auf .log enden.

Nachdem Sie den Inhalt eingefügt haben, speichern Sie die Datei und beenden Sie nano, indem Sie Ctrl+X, dann Y und schließlich Enter drücken.

Promtail Container ausführen und auf Loki verweisen

In diesem Schritt starten Sie den Promtail-Container unter Verwendung der gerade erstellten Konfigurationsdatei. Der Befehl wird sowohl Ihre Konfigurationsdatei als auch das Log-Verzeichnis des Hosts in den Container einbinden (mounten).

Führen Sie den folgenden docker run-Befehl aus, um Promtail zu starten:

docker run -d --name promtail --network monitoring-net -v $(pwd)/promtail.yml:/etc/promtail/config.yml -v /var/log:/var/log grafana/promtail:3.5.0 -config.file=/etc/promtail/config.yml

Hier ist eine Erklärung der Flags des Befehls:

-d: Führt den Container im Detached-Modus (im Hintergrund) aus.
--name promtail: Weist dem Container einen Namen zur einfachen Referenzierung zu.
--network monitoring-net: Verbindet den Container mit demselben Netzwerk wie Loki und Grafana.
-v $(pwd)/promtail.yml:/etc/promtail/config.yml: Bindet Ihre lokale promtail.yml an der erwarteten Stelle in den Container ein.
-v /var/log:/var/log: Bindet das /var/log-Verzeichnis des Hosts in den Container ein, damit Promtail die Log-Dateien lesen kann.
-config.file=/etc/promtail/config.yml: Teilt dem Promtail-Prozess innerhalb des Containers mit, welche Konfigurationsdatei er verwenden soll.

Nach Ausführung des Befehls gibt Docker die eindeutige ID des neuen Containers aus. Sie können mit dem Befehl docker ps überprüfen, ob der Container läuft.

docker ps

Sie sollten promtail, loki und grafana in der Liste der laufenden Container sehen.

Schreiben Sie nach dem Start des Collectors eine neue Testnachricht. printf gibt die Nachricht aus und sudo tee -a hängt sie an die root gehörende Protokolldatei an. Die Option -a erhält vorhandene Protokolle.

printf 'labex test message\n' | sudo tee -a /var/log/test.log

Promtail entdeckt die Datei und sendet die Nachricht an Loki. Warten Sie einige Sekunden auf den ersten Stapel. Port 9080 ist intern für Promtail; der Befehl veröffentlicht ihn nicht auf der VM.

Loki als Datenquelle in Grafana hinzufügen

In diesem Schritt verbinden Sie Grafana mit dem von Ihnen gestarteten Loki-Dienst.

Wählen Sie nach erfolgreichen Zustandsprüfungen den Lab-Tab Grafana. Wird die eingebettete Anmeldung blockiert, verwenden Sie dessen Steuerelement zum Öffnen im Browser. Melden Sie sich mit Benutzername admin und Passwort admin an und klicken Sie beim Passwortwechsel auf Skip. Diese Zugangsdaten gelten nur für dieses temporäre Lab.

Öffnen Sie Connections → Data sources, klicken Sie auf Add data source und wählen Sie Loki. Setzen Sie Name auf Loki. Setzen Sie unter Connection die URL auf:

http://loki:3100

Der Hostname loki wird innerhalb des gemeinsamen Docker-Netzwerks aufgelöst, sodass Grafana Loki direkt erreichen kann. Ihr Browser muss diesen Containernamen nicht auflösen.

Klicken Sie auf Save & test. Warten Sie auf Data source successfully connected., bevor Sie fortfahren. Dies bestätigt, dass Grafana Loki abfragen kann.

Grundlegende Logs in der Grafana Explore-Ansicht abfragen

In diesem letzten Schritt verwenden Sie die "Explore"-Ansicht von Grafana, um eine einfache Abfrage auszuführen und die Logs anzuzeigen, die Promtail aus Ihrer Umgebung sendet.

Navigieren Sie in der Grafana UI zur linken Seitenleiste und klicken Sie auf das Kompass-Symbol (Explore).
Oben links auf der Explore-Seite sehen Sie ein Dropdown-Menü zur Auswahl der Datenquelle. Falls es noch nicht ausgewählt ist, wählen Sie Loki.
Sie sehen ein Eingabefeld namens "Log browser". Hier schreiben Sie Ihre LogQL-Abfragen.
Klicken Sie auf die Schaltfläche "Code", um zum Code-Editor zu wechseln.
Geben Sie die folgende Abfrage in das Eingabefeld ein:

{job="varlogs"}

Diese LogQL-Abfrage wählt alle Log-Streams aus, die das Label job mit dem Wert varlogs haben. Dieses Label haben wir in unserer promtail.yml-Datei definiert. 6. Drücken Sie Shift+Enter oder klicken Sie auf die blaue Schaltfläche Run query auf der rechten Seite des Bildschirms.

Nach Ausführung der Abfrage sollten im Hauptfenster unterhalb des Abfrage-Editors Logzeilen erscheinen. Sie sehen Logs aus verschiedenen Dateien in /var/log. Dies bestätigt, dass Promtail erfolgreich Logs erfasst und an Loki sendet und Grafana diese abfragen kann.

Die allgemeine Abfrage kann viele Systemmeldungen liefern. Ergänzen Sie den LogQL-Zeilenfilter |=, um Ihre Nachricht zu finden. Er behält Zeilen mit dem Text in Anführungszeichen:

{job="varlogs"} |= "labex test message"

Klicken Sie erneut auf Run query. Prüfen Sie, dass labex test message in den Ergebnissen erscheint. Damit ist bestätigt, dass Collector, Loki und Grafana zusammenarbeiten.

Zusammenfassung

Herzlichen Glückwunsch! Sie haben erfolgreich eine grundlegende Logging-Pipeline mit Loki, Promtail und Grafana konfiguriert.

In diesem Lab haben Sie gelernt, wie man:

Docker-Container für Log-Verarbeitungstools wie Promtail zieht und ausführt.
Eine Promtail-Konfigurationsdatei erstellt, um einen Loki-Server anzugeben und Log-Scraping-Jobs zu definieren.
Docker-Networking nutzt, um Dienste (Promtail, Loki und Grafana) zu verbinden.
Loki als Datenquelle innerhalb der Grafana-Benutzeroberfläche hinzufügt.
Eine einfache LogQL-Abfrage in der Explore-Ansicht von Grafana ausführt, um Ihre Logs zu finden und zu inspizieren.

Dieses Setup bildet die Grundlage für ein leistungsstarkes, skalierbares und kosteneffizientes Log-Aggregationssystem. Von hier aus könnten Sie fortgeschrittenere LogQL-Abfragen, Log-Parsing und das Einrichten von Alarmen (Alerts) in Grafana basierend auf dem Log-Inhalt erkunden.