Passer au contenu principal

Surveillance

Aperçu​

Immich fournit une variété de métriques de performance permettant une surveillance locale et des insights. Cette intégration prend principalement la forme de métriques Prometheus. Cependant, l'exportation de traces est également possible grâce à l'utilisation de l'instrumentation OpenTelemetry.

note

Cette fonctionnalité est facultative et est conçue pour que vous puissiez surveiller les performances d'immich. Ces données ne sont pas envoyées ailleurs que ce que vous avez configuré.

Prometheus​

Prometheus est un outil qui collecte des métriques à partir d'un certain nombre de sources que vous configurez. Il fonctionne selon une stratégie de "pull" - c'est-à-dire qu'il demande périodiquement des métriques à chaque source définie. Cela signifie que la source ne transmet rien tant qu'elle n'est pas sollicitée. Cela implique également que la source -- immich, dans ce cas -- doit exposer un point de terminaison pour que Prometheus puisse cibler lorsqu'il demande des métriques.

Métriques​

Ces métriques se présentent sous différentes formes :

  • Compteurs, qui ne peuvent qu'augmenter. Exemple : le nombre de fois qu'un point de terminaison a été appelé.
  • Jauges, qui peuvent augmenter ou diminuer dans une certaine gamme. Exemple : l'utilisation du processeur.
  • Histogrammes, où chaque observation est assignée à un certain nombre de "seaux". Exemple : le temps de réponse, où chaque seau correspond à un nombre de millisecondes. Ce type est un peu plus complexe.
    • Les seaux sont dans ce cas cumulatifs; c'est-à-dire qu'une observation est placée non seulement dans le plus petit seau qui la contient, mais aussi dans tous les seaux plus grands. Par exemple, si un histogramme contient trois seaux pour 1ms, 5ms et 10ms, une observation de 3ms sera classée à la fois dans les seaux 5ms et 10ms.

Les métriques d'immich sont regroupées en API (appels de points de terminaison et temps de réponse), hôte (utilisation de la mémoire et du processeur), et IO (requêtes internes à la base de données, traitement d'images, etc.). Chaque groupe de métriques peut être activé ou désactivé indépendamment.

Configuration​

Par défaut, Immich n'expose pas de point de terminaison pour les métriques. Pour activer ce point de terminaison, vous pouvez ajouter la variable d'environnement IMMICH_TELEMETRY_INCLUDE=all à votre fichier .env. Notez que seule la conteneur du serveur utilise actuellement cette variable.

astuce

IMMICH_TELEMETRY_INCLUDE=all active toutes les métriques. Pour une configuration plus granulaire, vous pouvez énumérer les métriques de télémétrie à inclure sous forme de liste séparée par des virgules (par ex. IMMICH_TELEMETRY_INCLUDE=repo,api). Alternativement, vous pouvez également exclure certaines métriques spécifiques avec IMMICH_TELEMETRY_EXCLUDE. Pour plus d'informations, consultez la section sur les variables d'environnement.

L'étape suivante consiste à configurer une instance Prometheus nouvelle ou existante pour interroger ce point de terminaison. Les étapes suivantes supposent que vous n'avez pas d'instance Prometheus existante, mais elles seront similaires dans tous les cas.

Vous pouvez commencer par définir un service Prometheus dans le fichier Compose :

immich-prometheus:
  container_name: immich_prometheus
  ports:
    # Cela expose le port par défaut de Prometheus pour que vous puissiez interagir avec lui
    - 9090:9090
  image: prom/prometheus
  volumes:
    # Le fichier de configuration Prometheus - un fichier minimal est fourni pour commencer
    - ./prometheus.yml:/etc/prometheus/prometheus.yml
    # Un volume nommé défini en bas du fichier Compose ; il peut également s'agir d'un dossier monté
    - prometheus-data:/prometheus

Vous devez également ajouter prometheus-data à la liste des volumes en bas du fichier Compose :

volumes:
  model-cache:
  prometheus-data:

Le dernier élément est le fichier de configuration. Ce fichier définit (entre autres) les sources que Prometheus doit cibler. Téléchargez-le et placez-le dans le même dossier que le fichier Compose.

astuce

Le fichier fourni est juste un point de départ. Il existe de nombreuses façons de configurer Prometheus, donc n'hésitez pas à expérimenter !

Après avoir arrêté les conteneurs avec docker compose down et les avoir relancés avec docker compose up -d, une instance Prometheus collectera désormais les métriques des conteneurs serveur et microservices d'immich. Notez que nous n'avons pas eu besoin d'exposer de nouveaux ports pour ces conteneurs - la communication s'effectue via le réseau interne de Docker.

note

Pour voir exactement quelles métriques sont disponibles, vous pouvez en plus ajouter 8081:8081 aux ports du conteneur serveur et 8082:8082 aux ports du conteneur microservices. Visiter le point de terminaison /metrics pour ces services affichera les mêmes données brutes que Prometheus collecte. Pour configurer ces ports, consultez IMMICH_API_METRICS_PORT & IMMICH_MICROSERVICES_METRICS_PORT.

Utilisation​

Après avoir configuré Prometheus, comment visualiser les métriques ? Le moyen le plus simple est d'utiliser directement Prometheus. En visitant Prometheus, vous verrez une interface web où vous pouvez rechercher et visualiser des métriques. Vous pouvez également consulter l'état de vos sources de données et configurer des paramètres, mais cela dépasse le cadre de ce guide.

Grafana​

Pour un outil dédié avec une belle présentation, vous pouvez utiliser Grafana à la place. Cela se connecte à Prometheus (et éventuellement à d'autres sources) pour une visualisation avancée des données.

La configuration de Grafana est similaire à celle de Prometheus. Vous pouvez ajouter un service pour cela :

immich-grafana:
  container_name: immich_grafana
  command: ['./run.sh', '-disable-reporting'] # Ceci désactive la télémétrie de Grafana
  ports:
    - 3000:3000
  image: grafana/grafana
  volumes:
    # Stocke vos beaux tableaux de bord et panneaux
    - grafana-data:/var/lib/grafana

Et ajoutez un autre volume pour cela :

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

Après avoir arrêté les services et les avoir relancés, vous pouvez maintenant visiter Grafana pour consulter vos métriques. Lors de la première connexion, entrez admin pour le nom d'utilisateur et le mot de passe, puis mettez à jour votre mot de passe. Vous pouvez ensuite accéder aux paramètres et ajouter une source de données avec http://immich-prometheus:9090 pour pointer Grafana vers votre instance Prometheus.

Utilisation​

Vous pouvez créer votre premier tableau de bord pour commencer. N'oubliez pas de le sauvegarder fréquemment, sinon vous perdrez tout votre travail !

Vous pouvez ensuite créer un nouveau panneau, en spécifiant Prometheus comme source de données pour celui-ci.

-- TODO : ajouter des images et plus de détails ici