모니터링

개요

Immich는 로컬 모니터링 및 인사이트를 제공하기 위해 다양한 성능 지표를 제공합니다. 이 통합은 주로 Prometheus 지표 형태로 제공됩니다. 또한 OpenTelemetry 계측을 사용하여 추적 데이터를 내보내는 것도 가능합니다.

참고

이것은 Immich의 성능을 모니터링하기 위한 선택적 기능입니다. 이 데이터는 사용자가 구성한 것 외의 다른 곳으로 전송되지 않습니다.

Prometheus

Prometheus는 구성한 여러 소스로부터 지표를 수집하는 도구입니다. "풀" 전략으로 동작하며, 이는 주기적으로 각 정의된 소스로부터 지표를 요청한다는 것을 의미합니다. 이는 소스가 요청되기 전까지 아무것도 전송하지 않으며, 또한 소스 -- 이 경우에는 Immich -- 가 Prometheus가 지표를 요청할 때 타겟으로 삼을 수 있는 엔드포인트를 공개해야 한다는 것을 의미합니다.

지표

이 지표는 다양한 형태로 제공됩니다:

• 카운터: 오직 증가만 할 수 있습니다. 예: 특정 엔드포인트가 호출된 횟수.
• 게이지: 특정 범위 내에서 증가하거나 감소할 수 있습니다. 예: CPU 사용량.
• 히스토그램: 각 관찰값이 일정한 수의 "버킷"에 할당됩니다. 예: 응답 시간, 각 버킷은 밀리초 단위로 구분됩니다. 이 항목은 조금 더 복잡합니다.
  • 버킷은 _누적적_으로 동작합니다; 즉, 관찰값은 자신을 포함하는 가장 작은 버킷뿐만 아니라 더 큰 모든 버킷에도 할당됩니다. 예를 들어, 히스토그램에 대해 1ms, 5ms 및 10ms의 버킷이 있는 경우, 3ms의 관찰값은 5ms와 10ms 버킷 모두에 할당됩니다.

Immich의 지표는 API (엔드포인트 호출 및 응답 시간), 호스트 (메모리 및 CPU 사용량), 그리고 IO (내부 데이터베이스 쿼리, 이미지 처리 등)로 그룹핑됩니다. 각 지표 그룹은 독립적으로 활성화 또는 비활성화할 수 있습니다.

구성

Immich는 기본적으로 지표를 위한 엔드포인트를 공개하지 않습니다. 이 엔드포인트를 활성화하려면 .env 파일에 IMMICH_TELEMETRY_INCLUDE=all 환경 변수를 추가하십시오. 현재 이 변수는 서버 컨테이너만 사용합니다.

팁

IMMICH_TELEMETRY_INCLUDE=all은 모든 지표를 활성화합니다. 더 세분화된 구성을 위해 포함해야 할 텔레메트리 지표를 쉼표로 구분된 목록으로 열거할 수 있습니다 (예: IMMICH_TELEMETRY_INCLUDE=repo,api). 또는, IMMICH_TELEMETRY_EXCLUDE를 사용하여 특정 지표를 제외할 수도 있습니다. 자세한 내용은 환경 변수 섹션을 참고하십시오.

다음 단계는 새로운 Prometheus 인스턴스를 구성하거나 기존 인스턴스를 업데이트하여 이 엔드포인트를 스크래핑하도록 설정하는 것입니다. 다음 단계는 기존 Prometheus 인스턴스가 없다고 가정하며, 기존 인스턴스가 있는 경우에도 유사한 단계가 적용됩니다.

Compose 파일에서 Prometheus 서비스를 정의하는 것으로 시작할 수 있습니다:

immich-prometheus:
  container_name: immich_prometheus
  ports:
    # Prometheus의 기본 포트를 공개하여 상호작용이 가능하게 합니다
    - 9090:9090
  image: prom/prometheus
  volumes:
    # 시작을 위한 초보적인 Prometheus 구성 파일
    - ./prometheus.yml:/etc/prometheus/prometheus.yml
    # Compose 파일 하단에 정의된 명명된 볼륨; 또한 마운트된 폴더일 수도 있습니다
    - prometheus-data:/prometheus

Compose 파일 하단의 볼륨 목록에 prometheus-data를 추가해야 합니다:

volumes:
  model-cache:
  prometheus-data:

마지막으로, 구성 파일입니다. 이 파일은 Prometheus가 타겟팅해야 하는 소스를 정의합니다. 다운로드하여 Compose 파일과 동일한 폴더에 배치합니다.

팁

제공된 파일은 시작점일 뿐입니다. Prometheus를 구성하는 다양한 방법이 있으므로 실험해 보세요!

docker compose down 명령으로 컨테이너를 중지하고 docker compose up -d 명령으로 다시 시작한 후, Prometheus 인스턴스는 immich 서버 및 마이크로서비스 컨테이너로부터 지표를 수집할 것입니다. 이 컨테이너에 대한 새로운 포트를 공개할 필요는 없습니다 - 통신은 내부 Docker 네트워크에서 처리됩니다.

참고

어떤 지표가 사용 가능한지 정확히 확인하려면 서버 컨테이너의 포트에 8081:8081을 추가하고 마이크로서비스 컨테이너의 포트에 8082:8082를 추가할 수 있습니다. 이러한 서비스의 /metrics 엔드포인트를 방문하면 Prometheus가 수집하는 동일한 원시 데이터를 확인할 수 있습니다. 이러한 포트를 구성하는 방법은 IMMICH_API_METRICS_PORT & IMMICH_MICROSERVICES_METRICS_PORT를 참조하십시오.

사용법

Prometheus 설정 후, 실제로 지표를 어떻게 볼 수 있을까요? 가장 간단한 방법은 Prometheus를 직접 사용하는 것입니다. Prometheus를 방문하면 웹 UI를 통해 지표를 검색하고 시각화할 수 있습니다. 또한 데이터 소스의 상태를 확인하고 설정을 구성할 수 있지만, 이는 본 가이드의 범위를 벗어납니다.

Grafana

보다 세련된 시각화를 제공하는 전용 도구로 Grafana를 사용할 수 있습니다. Grafana는 Prometheus (및 다른 소스)와 연결되어 복잡한 데이터 시각화를 제공합니다.

Grafana 설정은 Prometheus와 유사합니다. 아래와 같이 서비스를 추가할 수 있습니다:

immich-grafana:
  container_name: immich_grafana
  command: ['./run.sh', '-disable-reporting'] # Grafana의 텔레메트리를 비활성화합니다
  ports:
    - 3000:3000
  image: grafana/grafana
  volumes:
    # 아름다운 대시보드와 패널을 저장합니다
    - grafana-data:/var/lib/grafana

또한 추가 볼륨을 정의해야 합니다:

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

서비스를 중지하고 다시 시작한 후, 이제 Grafana를 방문하여 지표를 확인할 수 있습니다. 처음 로그인 시, 사용자 이름 및 비밀번호로 각각 admin을 입력한 후 비밀번호를 업데이트하십시오. 설정으로 이동하여 Grafana의 데이터 소스를 http://immich-prometheus:9090로 추가하여 Prometheus 인스턴스를 참조하도록 설정할 수 있습니다.

사용법

첫 대시보드를 만들어 시작할 수 있습니다. 자주 저장하는 것을 잊지 마세요, 작업을 잃게 될 수도 있습니다!

이후 새로운 패널을 만들어 Prometheus를 데이터 소스로 지정할 수 있습니다.

-- TODO: 이미지 및 자세한 내용을 추가하십시오