immich-prometheus-exporter (3.0.0)

Published 2026-08-10 22:21:04 +00:00 by finkregh in finkregh/immich-prometheus-exporter

To install the package using pip, run the following command:

pip install --index-url  immich-prometheus-exporter

For more information on the PyPI registry, see the documentation.

A Python script that exports Immich statistics as Prometheus metrics

Immich Prometheus Exporter

A Python script that exports Immich statistics as Prometheus metrics using the Immich OpenAPI specification.

Grafana

Dashboard.json

Breaking Changes

The server-stats and health-metrics refactor introduces the following breaking changes vs. the previous release:

Removed: immich_user_total_assets, immich_user_images_count, immich_user_videos_count. Use immich_user_photos + immich_user_videos (or their sum for the old "total").
Removed label: user_email is no longer emitted on any immich_user_* metric. Use user_id / user_name for aggregation.
The N+1 /admin/users/{id}/statistics scraping loop has been replaced by a single /server/statistics call.

Features

This exporter collects and exports the following metrics:

User Metrics

immich_user_photos - Number of photo assets owned by user
immich_user_videos - Number of video assets owned by user
immich_user_usage_bytes - Total storage used by user, in bytes
immich_user_usage_photos_bytes - Storage used by user's photo assets, in bytes
immich_user_usage_videos_bytes - Storage used by user's video assets, in bytes
immich_user_quota_bytes - User quota in bytes (if configured)
immich_user_quota_usage_bytes - User quota usage in bytes (if configured)
immich_user_admin - 1 if the user has admin privileges, else 0
immich_user_status{status} - User account status (stateset: emitted once per user with the current status as a label)
immich_user_deleted - 1 if the user has a non-null deletedAt timestamp, else 0

The user_email label has been removed from every immich_user_* metric; use user_id / user_name for aggregation.

Server Statistics

immich_server_photos - Total photo assets across the Immich instance
immich_server_videos - Total video assets across the Immich instance
immich_server_usage_bytes - Total storage used by assets across the instance, in bytes
immich_server_usage_photos_bytes - Storage used by photos across the instance, in bytes
immich_server_usage_videos_bytes - Storage used by videos across the instance, in bytes

Health & Maintenance

immich_up - 1 if the Immich API responded to /server/ping successfully, else 0
immich_maintenance_active{action,task} - 1 if an Immich maintenance action is currently in progress, else 0
immich_maintenance_progress{action,task} - Progress of the current Immich maintenance action, 0–100

Album Metrics

immich_albums_owned_total - Total number of albums owned by users
immich_albums_shared_total - Total number of shared albums
immich_albums_not_shared_total - Total number of albums not shared

Library Metrics

immich_library_total_assets - Total number of assets per library
immich_library_photos_count - Number of photos per library
immich_library_videos_count - Number of videos per library
immich_library_usage_bytes - Library usage in bytes

Storage Metrics

immich_storage_disk_size_bytes - Total disk size in bytes
immich_storage_disk_use_bytes - Used disk space in bytes
immich_storage_disk_available_bytes - Available disk space in bytes
immich_storage_disk_usage_percentage - Disk usage percentage

Job Metrics

immich_job_queue_count{queue,state} - Job counts per Immich queue and state (state ∈ {active, waiting, completed, failed, delayed, paused})
immich_job_queue_active{queue} - 1 if the queue is active, else 0
immich_job_queue_paused{queue} - 1 if the queue is paused, else 0

Example PromQL:

# Total failed jobs across all queues
sum(immich_job_queue_count{state="failed"})

# Queues currently backlogged (waiting > 0)
immich_job_queue_count{state="waiting"} > 0

# Free capacity ratio
1 - (immich_storage_disk_use_bytes / immich_storage_disk_size_bytes)

# Storage by user, top 10
topk(10, immich_user_usage_bytes)

# Alert: Immich unreachable for 5 minutes
avg_over_time(immich_up[5m]) < 1

System Metrics

immich_exporter_last_scrape_timestamp_ms - Timestamp of last successful scrape

Alternative projects

https://github.com/eithan1231/immich-exporter
https://github.com/patte/immich_stats_exporter
https://github.com/KryptionX/immich-prometheus-exporter - based on this project
https://github.com/victorarias/immich-prometheus-exporter - also includes job statistics

Compatibility

Tested against Immich server v3.1.0. All previously used API endpoints (/admin/users, /admin/users/{id}/statistics, /albums/statistics, /libraries, /libraries/{id}/statistics, /server/storage) are unchanged between v1.137.3 and v3.1.0. For older Immich v1.x / v2.x compatibility, use exporter versions prior to this release.

The /api/jobs endpoint used for job metrics is present in both v1.137.3 and v3.1.0 with an identical response shape (in v3.1.0 the operationId was renamed to getQueuesLegacy, but the payload is unchanged). It requires an admin API key.

Requirements

Python 3.7+
typer and requests libraries (included in requirements.txt)
Immich server with API access
Admin API key for accessing user statistics

Installation

Option 1: Install as a Package (Recommended)

Clone or download this repository
Install the package:
```
pip install .
```
Or for development:
```
pip install -e .
```

Option 2: Install Dependencies Only

Clone or download this repository
Install dependencies:
```
pip install -r requirements.txt
```

Usage

Basic Export (one-time)

If installed as a package:

immich-prometheus-exporter export --url http://localhost:2283 --api-key YOUR_API_KEY

If running directly:

python3 immich-prometheus-exporter.py export --url http://localhost:2283 --api-key YOUR_API_KEY

Export metrics to a file:

immich-prometheus-exporter export --url http://localhost:2283 --api-key YOUR_API_KEY --output metrics.txt

Continuous Export

Export metrics every 60 seconds:

immich-prometheus-exporter export --url http://localhost:2283 --api-key YOUR_API_KEY --interval 60

Test Connection

Test your connection and API key:

immich-prometheus-exporter test-connection --url http://localhost:2283 --api-key YOUR_API_KEY

Command Line Options

--url, -u: Immich server URL (required)
--api-key, -k: Immich API key (required)
--output, -o: Output file path (optional, defaults to stdout)
--interval, -i: Continuous export interval in seconds (optional)

Help

Get help for all commands:

immich-prometheus-exporter --help

Get help for a specific command:

immich-prometheus-exporter export --help

API Key Setup

Log into your Immich web interface
Go to Account Settings → API Keys
Create a new API key with the following permissions:
- Name: statistics_server_system_adminread (or any descriptive name)
- Required Permissions:
  - activity.statistics - Access to activity statistics
  - asset.statistics - Access to asset statistics
  - album.statistics - Access to album statistics
  - library.statistics - Access to library statistics
  - memory.statistics - Access to memory statistics
  - person.statistics - Access to person statistics
  - server.statistics - Access to server statistics
  - server.about - Access to server information
  - server.storage - Access to storage information
  - adminUser.read - Read access to admin user data
  - library.read - Read access to library data
Copy the generated key and use it with the --api-key parameter

Note: The API key must have admin privileges and the specific permissions listed above to access all user statistics, library information, and system metrics that this exporter collects.

Prometheus Integration

Using with Prometheus

Add this job to your prometheus.yml:

scrape_configs:
  - job_name: 'immich'
    static_configs:
      - targets: ['localhost:8000']  # Adjust as needed
    scrape_interval: 60s

Running as HTTP Server

You can use a simple HTTP server to serve the metrics:

# Export to file every 30 seconds (using installed package)
immich-prometheus-exporter export --url http://localhost:2283 --api-key YOUR_API_KEY --output /tmp/immich_metrics.txt --interval 30 &

# Serve the file via HTTP
cd /tmp && python3 -m http.server 8000

Then Prometheus can scrape from http://localhost:8000/immich_metrics.txt

Docker Usage

The project includes a Dockerfile that installs the package properly. Build and run:

docker build -t immich-exporter .
docker run -e IMMICHEXPORTER_EXPORT_URL=http://your-immich-server:2283 -e IMMICHEXPORTER_EXPORT_API_KEY=your-api-key immich-exporter

Or use docker-compose:

docker-compose up

Environment Variables

The exporter supports environment variables with the prefix IMMICHEXPORTER_. Each command has its own set of environment variables:

Global Options

IMMICHEXPORTER_INSTALL_COMPLETION - Install completion for the current shell
IMMICHEXPORTER_SHOW_COMPLETION - Show completion for the current shell

Export Command

IMMICHEXPORTER_EXPORT_URL - Immich server URL (required)
IMMICHEXPORTER_EXPORT_API_KEY - Immich API key (required)
IMMICHEXPORTER_EXPORT_OUTPUT - Output file path (optional)
IMMICHEXPORTER_EXPORT_INTERVAL - Continuous export interval in seconds (optional)
IMMICHEXPORTER_EXPORT_LOG_LEVEL - Logging level (default: INFO)
IMMICHEXPORTER_EXPORT_LOG_FILE - Log file path (optional)
IMMICHEXPORTER_EXPORT_LOG_TO_STDOUT - Log to stdout instead of stderr (optional)

Serve Command

IMMICHEXPORTER_SERVE_URL - Immich server URL (required)
IMMICHEXPORTER_SERVE_API_KEY - Immich API key (required)
IMMICHEXPORTER_SERVE_PORT - Port to serve metrics on (default: 8000)
IMMICHEXPORTER_SERVE_LOG_LEVEL - Logging level (default: INFO)
IMMICHEXPORTER_SERVE_LOG_FILE - Log file path (optional)

Test Connection Command

IMMICHEXPORTER_TEST_CONNECTION_URL - Immich server URL (required)
IMMICHEXPORTER_TEST_CONNECTION_API_KEY - Immich API key (required)

Example Usage with Environment Variables

# Export using environment variables
export IMMICHEXPORTER_EXPORT_URL=http://localhost:2283
export IMMICHEXPORTER_EXPORT_API_KEY=your-api-key
export IMMICHEXPORTER_EXPORT_INTERVAL=60
immich-prometheus-exporter export

# Serve using environment variables
export IMMICHEXPORTER_SERVE_URL=http://localhost:2283
export IMMICHEXPORTER_SERVE_API_KEY=your-api-key
export IMMICHEXPORTER_SERVE_PORT=8000
immich-prometheus-exporter serve

Example Output

# HELP immich_exporter_last_scrape_timestamp_ms Timestamp of last successful scrape
# TYPE immich_exporter_last_scrape_timestamp_ms gauge
immich_exporter_last_scrape_timestamp_ms 1704067200000

# HELP immich_user_total_assets Total number of assets for user
# TYPE immich_user_total_assets gauge
immich_user_total_assets{user_id="123e4567-e89b-12d3-a456-426614174000",user_name="john_doe",user_email="john@example.com"} 1250

# HELP immich_user_images_count Number of images for user
# TYPE immich_user_images_count gauge
immich_user_images_count{user_id="123e4567-e89b-12d3-a456-426614174000",user_name="john_doe",user_email="john@example.com"} 1000

# HELP immich_user_videos_count Number of videos for user
# TYPE immich_user_videos_count gauge
immich_user_videos_count{user_id="123e4567-e89b-12d3-a456-426614174000",user_name="john_doe",user_email="john@example.com"} 250

# HELP immich_albums_owned_total Total number of albums owned by users
# TYPE immich_albums_owned_total gauge
immich_albums_owned_total 15

# HELP immich_storage_disk_size_bytes Total disk size in bytes
# TYPE immich_storage_disk_size_bytes gauge
immich_storage_disk_size_bytes 1000000000000

Troubleshooting

Connection Issues

Verify your Immich server URL is correct and accessible
Check that your API key is valid and has admin privileges
Ensure Immich server is running and responding

Permission Issues

Make sure your API key has admin privileges
Some endpoints require specific permissions - check Immich logs for details

Missing Metrics

If user quotas are not configured, quota metrics won't appear
Libraries are only available if you have external libraries configured
Some metrics may be 0 if no data exists

Development

The script is built using:

typer for CLI interface
requests for HTTP requests (reliable and user-friendly HTTP library)
json for API response parsing
Type hints for better code quality

License

MIT, see LICENSE.md

Requires Python: >=3.10

Details

PyPI

finkregh/immich-prometheus-exporter

2026-08-10 22:21:04 +00:00

Oluf Lorenzen

Project website

MIT

32 KiB

Assets (2)

immich_prometheus_exporter-3.0.0-py3-none-any.whl 16 KiB

immich_prometheus_exporter-3.0.0.tar.gz 16 KiB

Versions (94) View all

3.0.1

2026-08-11

3.0.1.dev0

2026-08-11

3.0.0

2026-08-10

2.0.46.dev0

2026-08-07

2.0.45

2026-08-07

Issues

immich-prometheus-exporter (3.0.0)

Installation

About this package

Immich Prometheus Exporter

Grafana

Breaking Changes

Features

User Metrics

Server Statistics

Health & Maintenance

Album Metrics

Library Metrics

Storage Metrics

Job Metrics

System Metrics

Alternative projects

Compatibility

Requirements

Installation

Option 1: Install as a Package (Recommended)

Option 2: Install Dependencies Only

Usage

Basic Export (one-time)

Continuous Export

Test Connection

Command Line Options

Help

API Key Setup

Prometheus Integration

Using with Prometheus

Running as HTTP Server

Docker Usage

Environment Variables

Global Options

Export Command

Serve Command

Test Connection Command

Example Usage with Environment Variables

Example Output

Troubleshooting

Connection Issues

Permission Issues

Missing Metrics

Development

License

Requirements