Zum Hauptinhalt springen

Überwachung

Übersicht​

Immich bietet eine Vielzahl an Leistungsmetriken, um lokale Überwachung und Einblicke zu ermöglichen. Diese Integration erfolgt hauptsächlich in Form von Prometheus-Metriken. Es ist jedoch auch möglich, Traces zu exportieren, da OpenTelemetry-Instrumentierung verwendet wird.

Notiz

Dies ist eine Opt-in-Funktion, die es Ihnen ermöglicht, die Leistung von Immich zu überwachen. Diese Daten werden nicht über das hinaus gesendet, was Sie konfiguriert haben.

Prometheus​

Prometheus ist ein Tool, das Metriken von mehreren von Ihnen konfigurierten Quellen sammelt. Es arbeitet nach einer "Pull"-Strategie - das heißt, es fordert periodisch Metriken von jeder definierten Quelle an. Das bedeutet, dass die Quelle nichts sendet, bis sie angefordert wird. Es bedeutet auch, dass die Quelle – in diesem Fall Immich – einen Endpunkt bereitstellen muss, auf den Prometheus zugreifen kann, wenn es Metriken anfordert.

Metriken​

Diese Metriken haben unterschiedliche Formen:

  • Zähler (Counters), die nur steigen können. Beispiel: Die Anzahl der Aufrufe eines Endpunkts.
  • Messgeräte (Gauges), die innerhalb eines bestimmten Bereichs steigen oder fallen können. Beispiel: CPU-Auslastung.
  • Histogramme, bei denen jede Beobachtung einer bestimmten Anzahl von "Buckets" zugeordnet wird. Beispiel: Antwortzeit, bei der jeder Bucket eine Anzahl von Millisekunden ist. Dieses ist etwas komplizierter.
    • Buckets sind in diesem Fall kumulativ; das heißt, eine Beobachtung wird nicht nur in den kleinsten Bucket eingeordnet, der sie enthält, sondern auch in alle größeren Buckets. Zum Beispiel, wenn ein Histogramm drei Buckets für 1 ms, 5 ms und 10 ms hat, wird eine Beobachtung von 3 ms sowohl in den 5 ms- als auch den 10 ms-Bucket eingeordnet.

Die Metriken in Immich sind in die Kategorien API (Endpunktaufrufe und Antwortzeiten), Host (Speicher- und CPU-Auslastung), und IO (interne Datenbankabfragen, Bildverarbeitung usw.) unterteilt. Jede dieser Gruppen kann unabhängig voneinander aktiviert oder deaktiviert werden.

Konfiguration​

Immich wird standardmäßig keinen Endpunkt für Metriken bereitstellen. Um diesen Endpunkt zu aktivieren, können Sie die Umgebungsvariable IMMICH_TELEMETRY_INCLUDE=all in Ihre .env-Datei hinzufügen. Beachten Sie, dass derzeit nur der Server-Container diese Variable verwendet.

Tipp

IMMICH_TELEMETRY_INCLUDE=all aktiviert alle Metriken. Für eine detailliertere Konfiguration können Sie die Telemetrie-Metriken, die eingeschlossen werden sollen, als kommaseparierte Liste aufzählen (z. B. IMMICH_TELEMETRY_INCLUDE=repo,api). Alternativ können Sie auch bestimmte Metriken mit IMMICH_TELEMETRY_EXCLUDE ausschließen. Weitere Informationen finden Sie im Abschnitt Umgebungsvariablen.

Der nächste Schritt besteht darin, eine neue oder bestehende Prometheus-Instanz zu konfigurieren, die diesen Endpunkt abfragt. Die folgenden Schritte gehen davon aus, dass Sie keine bestehende Prometheus-Instanz haben, aber die Schritte sind ähnlich.

Sie können beginnen, indem Sie einen Prometheus-Dienst in der Compose-Datei definieren:

immich-prometheus:
  container_name: immich_prometheus
  ports:
    # Dies öffnet den Standardport für Prometheus, damit Sie damit interagieren können
    - 9090:9090
  image: prom/prometheus
  volumes:
    # Die Prometheus-Konfigurationsdatei - eine minimal vorbereitete wird bereitgestellt
    - ./prometheus.yml:/etc/prometheus/prometheus.yml
    # Ein benanntes Volume, das unten in der Compose-Datei definiert ist; es kann auch ein gemounteter Ordner sein
    - prometheus-data:/prometheus

Sie müssen außerdem prometheus-data der Liste der Volumes unten in der Compose-Datei hinzufügen:

volumes:
  model-cache:
  prometheus-data:

Das letzte Stück ist die Konfigurationsdatei. Diese Datei definiert (unter anderem), welche Quellen Prometheus ansteuern sollte. Laden Sie sie herunter und platzieren Sie sie im gleichen Ordner wie die Compose-Datei.

Tipp

Die bereitgestellte Datei ist nur ein Ausgangspunkt. Es gibt zahlreiche Möglichkeiten, Prometheus zu konfigurieren, also zögern Sie nicht, zu experimentieren!

Nachdem Sie die Container mit docker compose down gestoppt und mit docker compose up -d neu gestartet haben, wird eine Prometheus-Instanz nun Metriken aus den Immich-Server- und Mikroservice-Containern sammeln. Beachten Sie, dass wir keine neuen Ports für diese Container öffnen mussten - die Kommunikation wird im internen Docker-Netzwerk gehandhabt.

Notiz

Um genau zu sehen, welche Metriken verfügbar sind, können Sie zusätzlich 8081:8081 zu den Ports des Server-Containers und 8082:8082 zu den Ports des Mikroservice-Containers hinzufügen. Der Besuch des /metrics-Endpunkts für diese Dienste zeigt die gleichen Rohdaten, die Prometheus sammelt. Um diese Ports zu konfigurieren, siehe IMMICH_API_METRICS_PORT & IMMICH_MICROSERVICES_METRICS_PORT.

Verwendung​

Wie können Sie nach der Einrichtung von Prometheus die Metriken anzeigen? Der einfachste Weg ist, Prometheus direkt zu verwenden. Wenn Sie Prometheus besuchen, wird eine Web-Oberfläche angezeigt, in der Sie nach Metriken suchen und diese visualisieren können. Sie können auch den Status Ihrer Datenquellen anzeigen und Einstellungen konfigurieren, aber dies liegt außerhalb des Umfangs dieser Anleitung.

Grafana​

Für ein spezialisiertes Tool mit ansprechender Darstellung können Sie stattdessen Grafana verwenden. Dieses verbindet sich mit Prometheus (und möglicherweise anderen Quellen), um anspruchsvolle Datenvisualisierungen zu ermöglichen.

Die Einrichtung von Grafana ist ähnlich wie bei Prometheus. Sie können einen Dienst dafür hinzufügen:

immich-grafana:
  container_name: immich_grafana
  command: ['./run.sh', '-disable-reporting'] # Dies deaktiviert die Telemetrie von Grafana
  ports:
    - 3000:3000
  image: grafana/grafana
  volumes:
    # Speichert Ihre Dashboards und Panels
    - grafana-data:/var/lib/grafana

Und fügen Sie ein weiteres Volume hinzu:

volumes:
  model-cache:
  prometheus-data:
  grafana-data:

Nachdem Sie die Dienste gestoppt und erneut gestartet haben, können Sie Grafana besuchen, um Ihre Metriken anzuzeigen. Beim ersten Login geben Sie admin für Benutzername und Passwort ein und aktualisieren Ihr Passwort. Sie können dann zu den Einstellungen gehen und eine Datenquelle mit http://immich-prometheus:9090 hinzufügen, um Grafana mit Ihrer Prometheus-Instanz zu verbinden.

Verwendung​

Sie können Ihr erstes Dashboard erstellen, um zu beginnen. Vergessen Sie nicht, es regelmäßig zu speichern, sonst verlieren Sie Ihren Fortschritt!

Sie können dann ein neues Panel erstellen und Prometheus als Datenquelle dafür angeben.

-- TODO: Bilder und weitere Details hier hinzufügen