Saltar al contenido principal

Monitoreo

Descripción general​

Immich proporciona una variedad de métricas de rendimiento para permitir el monitoreo local y obtener insights. Esta integración es principalmente en la forma de métricas de Prometheus. Sin embargo, también es posible exportar rastros gracias al uso de instrumentación OpenTelemetry.

nota

Esta es una función de activación opcional destinada a que usted supervise el rendimiento de immich. Estos datos no se envían a ningún lugar más allá de lo que usted haya configurado.

Prometheus​

Prometheus es una herramienta que recopila métricas de varias fuentes que usted configura. Funciona con una estrategia de "pull" - es decir, solicita métricas periódicamente de cada fuente definida. Esto significa que la fuente no envía nada hasta que se solicite. También significa que la fuente -- en este caso, immich -- debe exponer un endpoint para que Prometheus lo apunte cuando solicite métricas.

Métricas​

Estas métricas vienen en variadas formas:

  • Contadores, que solo pueden aumentar. Ejemplo: la cantidad de veces que se ha llamado a un endpoint.
  • Medidores, que pueden aumentar o disminuir dentro de un cierto rango. Ejemplo: uso de CPU.
  • Histogramas, donde cada observación se asigna a un cierto número de "buckets". Ejemplo: tiempo de respuesta, donde cada bucket es un número de milisegundos. Este es un poco más complicado.
    • Los buckets en este caso son cumulativos; es decir, una observación se coloca no solo en el bucket más pequeño que la contiene, sino también en todos los buckets más grandes que este. Por ejemplo, si un histograma tiene tres buckets para 1ms, 5ms y 10ms, una observación de 3ms se colocará en los buckets de 5ms y 10ms.

Las métricas en immich se agrupan en API (llamadas de endpoints y tiempos de respuesta), host (uso de memoria y CPU) e IO (consultas internas a la base de datos, procesamiento de imágenes, etcétera). Cada grupo de métricas puede habilitarse o deshabilitarse de forma independiente.

Configuración​

Immich no expondrá un endpoint para métricas de forma predeterminada. Para habilitar este endpoint, puede agregar la variable ambiental IMMICH_TELEMETRY_INCLUDE=all en su archivo .env. Tenga en cuenta que actualmente solo el contenedor del servidor usa esta variable.

consejo

IMMICH_TELEMETRY_INCLUDE=all habilita todas las métricas. Para una configuración más granular, puede enumerar las métricas de telemetría que se deben incluir como una lista separada por comas (por ejemplo, IMMICH_TELEMETRY_INCLUDE=repo,api). Alternativamente, también puede excluir métricas específicas con IMMICH_TELEMETRY_EXCLUDE. Para más información, consulte la sección de entorno.

El siguiente paso es configurar una instancia nueva o existente de Prometheus para extraer este endpoint. Los pasos siguientes asumen que no tiene una instancia existente de Prometheus, pero los pasos serán similares de cualquier manera.

Puede comenzar definiendo un servicio de Prometheus en el archivo Compose:

immich-prometheus:
  container_name: immich_prometheus
  ports:
    # esto expone el puerto predeterminado para Prometheus para que pueda interactuar con él
    - 9090:9090
  image: prom/prometheus
  volumes:
    # el archivo de configuración de Prometheus - se proporciona uno básico para empezar
    - ./prometheus.yml:/etc/prometheus/prometheus.yml
    # un volumen con nombre definido en el final del archivo Compose; también puede ser una carpeta montada
    - prometheus-data:/prometheus

También necesitará agregar prometheus-data a la lista de volúmenes en el final del archivo Compose:

volumes:
  model-cache:
  prometheus-data:

La última parte es el archivo de configuración. Este archivo define (entre otras cosas) las fuentes que Prometheus debería apuntar. Descárguelo y colóquelo en la misma carpeta que el archivo Compose.

consejo

El archivo proporcionado es solo un punto de partida. Hay muchas maneras de configurar Prometheus, ¡así que siéntase libre de experimentar!

Después de detener los contenedores con docker compose down y volver a levantarlos con docker compose up -d, una instancia de Prometheus ahora recopilará métricas de los contenedores del servidor y microservicios de immich. Tenga en cuenta que no necesitábamos exponer nuevos puertos para estos contenedores: la comunicación se maneja en la red interna de Docker.

nota

Para ver exactamente qué métricas están disponibles, también puede agregar 8081:8081 a los puertos del contenedor del servidor y 8082:8082 a los puertos del contenedor de microservicios. Visitar el endpoint /metrics para estos servicios mostrará los mismos datos crudos que Prometheus recopila. Para configurar estos puertos, vea IMMICH_API_METRICS_PORT & IMMICH_MICROSERVICES_METRICS_PORT.

Uso​

Entonces, después de configurar Prometheus, ¿cómo ve realmente las métricas? La forma más sencilla es usar Prometheus directamente. Visitar Prometheus le mostrará una interfaz web donde puede buscar y visualizar métricas. También puede ver el estado de sus fuentes de datos y configurar ajustes, pero esto está fuera del alcance de esta guía.

Grafana​

Para una herramienta dedicada con una mejor presentación, puede usar Grafana en su lugar. Esto se conecta a Prometheus (y posiblemente a otras fuentes) para una visualización sofisticada de datos.

Configurar Grafana es similar a Prometheus. Puede agregar un servicio para ello:

immich-grafana:
  container_name: immich_grafana
  command: ['./run.sh', '-disable-reporting'] # esto es para deshabilitar la telemetría de Grafana
  ports:
    - 3000:3000
  image: grafana/grafana
  volumes:
    # almacena sus bonitos tableros y paneles
    - grafana-data:/var/lib/grafana

Y agregar otro volumen para ello:

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

Después de detener los servicios y volver a levantarlos, ahora puede visitar Grafana para ver sus métricas. En el primer inicio de sesión, ingrese admin tanto para el nombre de usuario como para la contraseña y actualice su contraseña. Luego puede ir a la configuración y agregar una fuente de datos con http://immich-prometheus:9090 para apuntar Grafana a su instancia de Prometheus.

Uso​

Puede hacer su primer tablero para comenzar. ¡No olvide guardarlo frecuentemente, o perderá todo su progreso!

Luego puede crear un nuevo panel, especificando Prometheus como la fuente de datos para este.

-- TODO: agregar imágenes y más detalles aquí