概览

Immich 提供多种性能指标，便于在本地监控和分析。集成主要采用 Prometheus 指标；由于使用了 OpenTelemetry 插桩，也可以导出追踪数据。

Prometheus

Prometheus 会从配置的多个数据源收集指标。它采用拉取模式，定期向各个来源请求指标；数据源在收到请求前不会主动发送数据。因此，Immich 必须开放一个供 Prometheus 抓取指标的端点。

指标

指标有多种形式：

• 计数器（Counter）：只会递增，例如某个端点被调用的次数。
• 仪表（Gauge）：可在一定范围内增减，例如 CPU 利用率。
• 直方图（Histogram）：将每次观测分配到若干个桶中。例如响应时间的各个桶以毫秒为边界。其桶是累积的：观测值不仅进入能容纳它的最小桶，也进入所有更大的桶。例如，桶边界为 1ms、5ms、10ms 时，3ms 的观测会同时进入 5ms 与 10ms 的桶。

Immich 的指标分为 API（端点调用与响应时间）、主机（内存与 CPU 利用率）和 IO（内部数据库查询、图像处理等）几组。每组都可以独立启用或关闭。

配置

默认情况下，Immich 不开放指标端点。要启用它，可以在 .env 文件中添加环境变量 IMMICH_TELEMETRY_INCLUDE=all。目前只有服务器容器使用这个变量。

接下来配置新的或已有的 Prometheus 实例来抓取这个端点。以下假定你还没有 Prometheus，已有实例的配置方式也类似。

首先在 Compose 文件中定义 Prometheus 服务：

immich-prometheus:
  container_name: immich_prometheus
  ports:
    # this exposes the default port for Prometheus so you can interact with it
    - 9090:9090
  image: prom/prometheus
  volumes:
    # the Prometheus configuration file - a barebones one is provided to get started
    - ./prometheus.yml:/etc/prometheus/prometheus.yml
    # a named volume defined in the bottom of the Compose file; it can also be a mounted folder
    - prometheus-data:/prometheus

还需要在 Compose 文件底部的卷列表中加入 prometheus-data：

volumes:
  model-cache:
  prometheus-data:

最后准备配置文件。它定义 Prometheus 应抓取的数据源等内容。下载原文所链接的配置文件，放到 Compose 文件所在的目录。

运行 docker compose down 关闭容器，再运行 docker compose up -d 启动后，Prometheus 就会收集 Immich 服务器与微服务的指标。无需为这些容器额外映射端口，因为通信通过 Docker 内部网络完成。

使用

配置完成后，最简单的查看方式是直接访问 Prometheus 的 Web 界面，搜索指标并将其可视化。也可以查看数据源状态和调整设置，但这些内容超出本指南范围。

Grafana

如果希望使用更专门、展示效果更丰富的工具，可以选择 Grafana。它连接 Prometheus 以及其他数据源，提供更复杂的数据可视化。

Grafana 的配置与 Prometheus 类似，先添加服务：

immich-grafana:
  container_name: immich_grafana
  command: ['./run.sh', '-disable-reporting'] # this is to disable Grafana's telemetry
  ports:
    - 3000:3000
  image: grafana/grafana
  volumes:
    # stores your pretty dashboards and panels
    - grafana-data:/var/lib/grafana

再为它添加一个卷：

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

重启服务后即可访问 Grafana。首次登录的用户名和密码均为 admin，登录后应更新密码。接着进入设置，添加 URL 为 http://immich-prometheus:9090 的数据源，让 Grafana 连接 Prometheus。

使用

可以先创建一个仪表板。记得经常保存，否则可能丢失工作。

然后新建面板，将数据源设置为 Prometheus。

原文此处尚待补充图片和更多细节。

结构化日志

除了 Prometheus 指标，Immich 还支持结构化 JSON 日志，适合 Grafana Loki、ELK Stack、Datadog、Splunk 等日志聚合系统。

配置

Immich 默认输出方便人阅读的控制台日志。要启用 JSON 日志，请设置 IMMICH_LOG_FORMAT：

IMMICH_LOG_FORMAT=json

JSON 日志格式

启用后，日志以结构化 JSON 输出：

{"level":"log","pid":36,"timestamp":1766533331507,"message":"Initialized websocket server","context":"WebsocketRepository"}
{"level":"warn","pid":48,"timestamp":1766533331629,"message":"Unable to open /build/www/index.html, skipping SSR.","context":"ApiService"}
{"level":"error","pid":36,"timestamp":1766533331690,"message":"Failed to load plugin immich-core:","context":"Error"}

此格式包含：

• level：日志级别，如 log、warn、error。
• pid：进程 ID。
• timestamp：以毫秒表示的 Unix 时间戳。
• message：日志消息。
• context：生成日志的服务或组件。

日志格式的更多信息见 IMMICH_LOG_FORMAT 文档。