監控

概覽

Immich 提供了多種效能指標，允許進行本地監控和洞察。這些整合主要以 Prometheus 指標的形式提供。然而，由於使用了 OpenTelemetry 工具，也可以匯出追踪資訊。

注释

這是一個選擇性功能，旨在供您監控 Immich 的效能。這些數據只會送至您設定的地方。

Prometheus

Prometheus 是一種工具，可從您配置的多個來源收集指標。它採用 "拉式" 策略，也就是說，它定期從每個定義的來源請求指標資料。這意味着來源在被請求之前不會發送任何資料。因此，來源（在此為 Immich）需要公開一個端點以供 Prometheus 在請求指標時定位。

指標

這些指標以多種形式呈現：

• 計數器，它只能遞增。例如：某個端點被呼叫的次數。
• 測量儀表，可以在某個範圍內升高或降低。例如：CPU 使用率。
• 直方圖，每個觀察值被分配到一定數量的 "桶" 中。例如：響應時間，其中每個桶的單位為毫秒。這一類稍微複雜些。
  • 這些桶是累加的；即，一個觀察值不僅被放置於包含它的最小桶內，也會被放入所有大於該桶的桶。例如，如果一個直方圖有三個桶，分別為 1ms、5ms 和 10ms，那麼一個 3ms 的觀察值將被放入桶 5ms 和桶 10ms。

在 Immich 中，指標分為 API (端點呼叫和響應時間)、主機 (記憶體和 CPU 使用率)，以及 IO (內部資料庫查詢、影像處理等)。每組指標都可獨立啟用或停用。

配置

默認情況下，Immich 不會公開指標端點。要啟用該端點，您可以將 IMMICH_TELEMETRY_INCLUDE=all 環境變數添加到 .env 文件中。注意，目前僅伺服器容器會使用此變數。

提示

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。它連接到 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，登錄後請更新密碼。然後，您可以進入設定，添加一個資料來源，URL 為 http://immich-prometheus:9090，以使 Grafana 指向您的 Prometheus 實例。

使用

您可以製作第一個儀表板以開始使用。別忘了經常保存，否則將丟失所有進度！

然後，您可以新建一個面板，指定 Prometheus 為其資料來源。

-- TODO: 添加圖片和更多細節於此處