Monitoramento
Visão Geral
O Immich fornece uma variedade de métricas de desempenho para permitir o monitoramento local e geração de insights. Essa integração ocorre principalmente na forma de métricas do Prometheus. No entanto, a exportação de rastreamentos também é possível graças ao uso de instrumentação OpenTelemetry.
Este é um recurso optativo destinado a você monitorar o desempenho do Immich. Esses dados não são enviados para nenhum lugar além do que você configurou.
Prometheus
O Prometheus é uma ferramenta que coleta métricas de diversas fontes configuradas. Ele opera com uma estratégia de "pull" - isto é, periodicamente solicita métricas de cada fonte definida. Isso significa que a fonte não envia nada até ser requisitada. Também significa que a fonte -- Immich, neste caso -- precisa expor um endpoint para o Prometheus direcionar suas solicitações de métricas.
Métricas
Essas métricas estão disponíveis em diferentes formas:
- Contadores, que só podem aumentar. Exemplo: o número de vezes que um endpoint foi chamado.
- Medidores, que podem aumentar ou diminuir dentro de um certo intervalo. Exemplo: utilização de CPU.
- Histogramas, onde cada observação é atribuída a um número específico de "buckets". Exemplo: tempo de resposta, onde cada bucket é um número de milissegundos. Este é um pouco mais complicado.
- Buckets, neste caso, são cumulativos; ou seja, uma observação é colocada não apenas no menor bucket que a contém, mas também em todos os buckets maiores que ele. Por exemplo, se um histograma tiver três buckets para 1ms, 5ms e 10ms, uma observação de 3ms será colocada nos buckets de 5ms e 10ms.
As métricas no Immich estão agrupadas em API (chamadas de endpoints e tempos de resposta), host (utilização de memória e CPU) e IO (consultas internas ao banco de dados, processamento de imagens, etc.). Cada grupo de métricas pode ser habilitado ou desabilitado independentemente.
Configuração
O Immich não irá expor um endpoint para métricas por padrão. Para habilitar esse endpoint, você pode adicionar a variável de ambiente IMMICH_TELEMETRY_INCLUDE=all no arquivo .env. Note que apenas o container do servidor atualmente usa essa variável.
IMMICH_TELEMETRY_INCLUDE=all habilita todas as métricas. Para uma configuração mais granular, você pode enumerar as métricas de telemetria que devem ser incluídas como uma lista separada por vírgulas (por exemplo, IMMICH_TELEMETRY_INCLUDE=repo,api). Alternativamente, você também pode excluir métricas específicas com IMMICH_TELEMETRY_EXCLUDE. Para mais informações, consulte a seção de ambiente.
O próximo passo é configurar uma nova instância do Prometheus ou uma já existente para coletar dados deste endpoint. Os passos a seguir assumem que você não tem uma instância do Prometheus já configurada, mas o processo será similar em ambos os casos.
Você pode começar definindo um serviço do Prometheus no arquivo Compose:
immich-prometheus:
container_name: immich_prometheus
ports:
# isso expõe a porta padrão do Prometheus para interação
- 9090:9090
image: prom/prometheus
volumes:
# arquivo de configuração do Prometheus - um básico fornecido para começar
- ./prometheus.yml:/etc/prometheus/prometheus.yml
# um volume nomeado definido no final do arquivo Compose; também pode ser uma pasta montada
- prometheus-data:/prometheus
Você também precisará adicionar prometheus-data à lista de volumes no final do arquivo Compose:
volumes:
model-cache:
prometheus-data:
A última peça é o arquivo de configuração. Este arquivo define (entre outras coisas) as fontes que o Prometheus deve direcionar. Baixe-o e coloque-o na mesma pasta do arquivo Compose.
O arquivo fornecido é apenas um ponto de partida. Há muitas formas de configurar o Prometheus, então sinta-se livre para experimentar!
Depois de parar os containers com docker compose down e reiniciá-los com docker compose up -d, uma instância do Prometheus começará a coletar métricas dos containers do servidor e microservices do Immich. Note que não foi necessário expor portas adicionais para esses containers - a comunicação é realizada na rede interna do Docker.
Para ver exatamente quais métricas estão disponíveis, você pode adicionalmente adicionar 8081:8081 às portas do container do servidor e 8082:8082 às portas do container de microservices.
Visitar o endpoint /metrics desses serviços mostrará os mesmos dados brutos que o Prometheus coleta.
Para configurar essas portas, consulte IMMICH_API_METRICS_PORT & IMMICH_MICROSERVICES_METRICS_PORT.
Uso
Depois de configurar o Prometheus, como você visualiza as métricas? A maneira mais simples é usar o Prometheus diretamente. Visitar o Prometheus exibirá uma interface web onde você pode buscar e visualizar métricas. Você também pode ver o status das suas fontes de dados e configurar definições, mas isso está fora do escopo deste guia.
Grafana
Para uma ferramenta dedicada com apresentação aprimorada, você pode usar o Grafana. Ele se conecta ao Prometheus (e possivelmente outras fontes) para visualização sofisticada de dados.
Configurar o Grafana é semelhante ao Prometheus. Você pode adicionar um serviço para ele:
immich-grafana:
container_name: immich_grafana
command: ['./run.sh', '-disable-reporting'] # isso desabilita a telemetria do Grafana
ports:
- 3000:3000
image: grafana/grafana
volumes:
# armazena seus dashboards e painéis personalizados
- grafana-data:/var/lib/grafana
E adicionar outro volume para ele:
volumes:
model-cache:
prometheus-data:
grafana-data:
Depois de parar os serviços e reiniciá-los, você poderá visitar o Grafana para visualizar suas métricas. No primeiro login, insira admin como nome de usuário e senha e atualize sua senha. Você pode então acessar as configurações e adicionar uma fonte de dados com http://immich-prometheus:9090, apontando o Grafana para sua instância do Prometheus.
Uso
Você pode criar seu primeiro dashboard para começar. Não se esqueça de salvá-lo frequentemente ou perderá todo o progresso!
Depois, você pode criar um novo painel, especificando o Prometheus como a fonte de dados.
-- TODO: adicionar imagens e mais detalhes aqui