Worum es geht
Container-Umgebungen wachsen schnell. Ein einzelner Host kann zehn, zwanzig oder mehr Services gleichzeitig betreiben, jeder mit eigenem Lebenszyklus. Klassische Überwachung über statische Konfigurationsdateien hält damit kaum Schritt, weil jede Änderung einen manuellen Eintrag erfordert.
Label-basierte Erkennung dreht das Prinzip um. Statt eine zentrale Liste zu pflegen, trägst du die Information direkt am Container ein, etwa über ein Docker-Label wie monitor.enable=true. Ein Collector liest diese Labels periodisch aus und entscheidet selbst, was überwacht werden muss. Das Konzept ist nicht neu, Traefik und Caddy nutzen es seit Jahren für Routing-Entscheidungen. Für Monitoring-Zwecke ist es trotzdem noch nicht überall etabliert.
Der Vorteil liegt in der Lokalität der Konfiguration. Wer einen Dienst deployt, entscheidet in derselben Compose-Datei, ob und wie er überwacht wird. Das reduziert den Abstand zwischen Deployment und Observability, zwei Bereiche, die in vielen kleinen Setups sonst getrennt gepflegt werden.
Anforderungen
Bevor du Label-Erkennung in deine Pipeline integrierst, solltest du drei Dinge klären. Erstens: Zugriff auf den Docker-Socket oder die Docker-API. Ohne diesen Zugriff kannst du keine Labels auslesen, und der Zugriff selbst ist ein Sicherheitsthema, das du nicht unterschätzen solltest.
Zweitens: ein Datenmodell für erkannte Dienste. Die Referenzarchitektur aus Collector, SQLite, Klassifikation und Benachrichtigung setzt voraus, dass erkannte Container in einer Tabelle landen, die sich wie jeder andere Feed-Eintrag behandeln lässt. Ohne diese Normalisierung musst du für Container-Events eine komplett eigene Logik bauen, was den Wartungsaufwand erhöht.
Drittens: eine klare Definition von "gesund". Ein Label sagt nur, dass ein Dienst überwacht werden soll, nicht wie. Du brauchst zusätzlich einen Healthcheck, einen Port-Check oder einen HTTP-Endpunkt, den die Pipeline regelmäßig abfragt. Ohne diese zweite Ebene überwachst du nur die Existenz des Containers, nicht seinen tatsächlichen Zustand.
Wenn Container zusätzlich über ein Overlay-Netzwerk wie Tailscale erreichbar gemacht werden, kommt eine vierte Anforderung hinzu: Die Pipeline muss wissen, über welche Adresse ein Dienst innerhalb des Tailnets erreichbar ist, nicht nur über die interne Docker-IP. Das ist der Punkt, an dem Label-basierte Service-Discovery und Netzwerk-Overlay zusammentreffen.
Möglichkeiten im Vergleich
Es gibt grundsätzlich drei Wege, Container-Dienste in eine Alert-Pipeline einzuspeisen. Der erste ist die manuelle Pflege einer Konfigurationsdatei, in der jeder zu überwachende Dienst explizit aufgeführt wird. Das ist robust und nachvollziehbar, skaliert aber schlecht, sobald die Anzahl der Dienste zweistellig wird.
Der zweite Weg ist Label-basierte Erkennung, wie sie eingangs beschrieben wurde. Sie skaliert gut, erfordert aber Disziplin bei der Label-Vergabe. Vergisst du ein Label, fehlt der Dienst in der Überwachung, ohne dass eine Fehlermeldung erscheint. Das ist ein stiller Fehler, der sich erst bemerkbar macht, wenn der Dienst tatsächlich ausfällt.
Der dritte Weg ist vollautomatische Erkennung über die Docker-Events-API, bei der jeder neue Container unabhängig von Labels erfasst wird. Das deckt alles ab, erzeugt aber auch Rauschen durch kurzlebige Container, etwa aus CI-Pipelines, die nie überwacht werden sollten.
In der Praxis ist eine Kombination aus Label-basierter Erkennung und einem Healthcheck-Layer der pragmatischste Mittelweg. Du behältst die explizite Opt-in-Logik der Labels, automatisierst aber das Einsammeln und die Weiterverarbeitung.
Umsetzung
Der folgende Code zeigt, wie du Container-Labels auslesen, in eine SQLite-Tabelle schreiben und anschließend einen einfachen Healthcheck durchführen kannst. Der Collector läuft idealerweise über einen systemd-Timer, etwa alle zwei Minuten.
from __future__ import annotations
import json
import logging
import sqlite3
import subprocess
from dataclasses import dataclass
from pathlib import Path
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("label_collector")
DB_PATH = Path("/var/lib/watchpipe/services.db")
LABEL_KEY = "monitor.enable"
PORT_LABEL = "monitor.port"
@dataclass
class DiscoveredService:
container_id: str
name: str
port: int | None
def init_db(db_path: Path) -> None:
db_path.parent.mkdir(parents=True, exist_ok=True)
with sqlite3.connect(db_path) as conn:
conn.execute(
"""
CREATE TABLE IF NOT EXISTS services (
container_id TEXT PRIMARY KEY,
name TEXT NOT NULL,
port INTEGER,
last_seen TEXT DEFAULT CURRENT_TIMESTAMP,
status TEXT DEFAULT 'unknown'
)
"""
)
def list_containers() -> list[str]:
result = subprocess.run(
["docker", "ps", "--format", "{{.ID}}"],
capture_output=True,
text=True,
check=True,
)
return [line.strip() for line in result.stdout.splitlines() if line.strip()]
def read_labels(container_id: str) -> dict[str, str]:
fmt = "{{json .Config.Labels}}"
result = subprocess.run(
["docker", "inspect", "--format", fmt, container_id],
capture_output=True,
text=True,
check=True,
)
raw = result.stdout.strip()
return json.loads(raw) if raw and raw != "null" else {}
def discover_services() -> list[DiscoveredService]:
discovered: list[DiscoveredService] = []
for container_id in list_containers():
labels = read_labels(container_id)
if labels.get(LABEL_KEY) != "true":
continue
name = labels.get("com.docker.compose.service", container_id[:12])
port_raw = labels.get(PORT_LABEL)
port = int(port_raw) if port_raw and port_raw.isdigit() else None
discovered.append(
DiscoveredService(container_id=container_id, name=name, port=port)
)
return discovered
def store_services(db_path: Path, services: list[DiscoveredService]) -> None:
conn = None
try:
conn = sqlite3.connect(db_path)
for service in services:
conn.execute(
"""
INSERT INTO services (container_id, name, port, last_seen)
VALUES (?, ?, ?, CURRENT_TIMESTAMP)
ON CONFLICT(container_id) DO UPDATE SET
name = excluded.name,
port = excluded.port,
last_seen = CURRENT_TIMESTAMP
""",
(service.container_id, service.name, service.port),
)
conn.commit()
except sqlite3.Error as exc:
logger.error("Datenbankfehler beim Speichern: %s", exc)
finally:
if conn is not None:
conn.close()
def main() -> None:
init_db(DB_PATH)
services = discover_services()
logger.info("Erkannte Dienste: %d", len(services))
store_services(DB_PATH, services)
if __name__ == "__main__":
main()
Dieser Collector ersetzt keine Healthcheck-Logik. Er liefert nur die Liste der zu überwachenden Dienste. Der nächste Schritt in der Pipeline liest diese Tabelle aus, prüft Port oder HTTP-Endpunkt, schreibt den Status zurück und löst bei Bedarf eine Benachrichtigung über ntfy, Telegram oder E-Mail aus. Die Klassifikation, ob ein Ausfall kritisch ist oder ignoriert werden kann, bleibt ein separater Schritt, der auf denselben SQLite-Daten aufsetzt.
Typische Fallstricke
Der häufigste Fehler ist, den Docker-Socket ungefiltert in einen Collector-Container zu mounten. Damit hat dieser Prozess faktisch Root-Rechte auf dem Host. Nutze stattdessen einen Proxy wie einen schreibgeschützten Socket-Reverse-Proxy oder beschränke den Collector auf den Host selbst statt auf einen Container.
Ein weiterer Fallstrick ist die Inkonsistenz zwischen Label und tatsächlichem Zustand. Ein Container kann laufen, aber der Dienst innerhalb antwortet nicht mehr. Reine Label-Erkennung sagt dir nichts über diesen Zustand, du brauchst zwingend einen aktiven Check zusätzlich zur passiven Erkennung.
Auch Namenskonflikte sind ein Problem. Wenn zwei Compose-Projekte denselben Service-Namen verwenden, landen beide unter demselben Namen in der Tabelle, sofern du die Container-ID nicht als eindeutigen Schlüssel nutzt. Der Code oben verwendet deshalb die Container-ID als Primärschlüssel, nicht den Namen.
Schließlich vergessen viele, dass gestoppte oder entfernte Container nicht automatisch aus der Tabelle verschwinden. Ohne eine Aufräumlogik, die verwaiste Einträge nach einer bestimmten Zeit entfernt, sammelt sich über Monate Datenmüll an, der falsche Alerts erzeugen kann, wenn du später versehentlich wieder auf den alten Eintrag zugreifst.
Wann sich das lohnt (und wann nicht)
Label-basierte Erkennung lohnt sich, wenn du regelmäßig neue Container-Dienste startest und die manuelle Pflege einer Konfigurationsliste zum Flaschenhals wird. Besonders in Umgebungen mit häufigen Compose-Änderungen reduziert sie den Koordinationsaufwand zwischen Deployment und Monitoring deutlich.
Sie lohnt sich weniger, wenn du nur eine Handvoll stabiler Dienste betreibst, die sich selten ändern. In diesem Fall ist eine statische Konfiguration übersichtlicher und weniger fehleranfällig, weil fehlende Labels keine stillen Lücken erzeugen können.
Wenn zusätzlich ein Overlay-Netzwerk wie Tailscale im Spiel ist, steigt der Nutzen weiter, weil die Erreichbarkeit eines Dienstes ohnehin dynamisch von der Netzwerkkonfiguration abhängt. Die Kombination aus Label-Discovery und Netzwerk-Overlay ist in solchen Fällen konsistenter als zwei getrennte, manuell gepflegte Listen.