jelly-metrics

Jelly Metrics

Jelly Metrics is a lightweight Prometheus exporter for Jellyfin. It exposes key metrics related to your Jellyfin instance, including:

• Media count by type.
• Connected clients by username.
• Actively playing streams by username.

I use this tool in my Ultimate Jellyfin on macOS guide. A grafana dashboard using metrics from this exporter and prometheus scrape config is provided in that guide.

Table of Contents

1. Features
2. Getting Started
   1. Prerequisites
   2. Installation
   3. Run the Exporter
3. Configuration
4. Available Metrics
   • jellyfin_media_count
   • jellyfin_connected_clients_count
   • jellyfin_stream_count
5. Contributing
6. Changelog
7. License

Features

• Prometheus Integration: Jelly Metrics exposes /metrics endpoint for easy scraping by Prometheus.
• Minimal Cardinality: The exporter aims to provide only essential metrics to prevent large data ingestion footprints.
• Lightweight: Uses Go’s built-in HTTP server and minimal external dependencies to run efficiently.

Getting Started

Prerequisites

• Go 1.23.6 or higher (if you intend to build from source)
• A running Jellyfin server
• A valid Jellyfin API key

Installation

go install github.com/Digital-Shane/jelly-metrics@latest

Run the Exporter

export JELLYFIN_TOKEN="YOUR_JELLYFIN_API_KEY"
# Optional environment variables:
# export JELLYFIN_HOST="http://localhost:8096"
# export PORT="8097"

./jelly-metrics

Configuration

Available Metrics

Jelly Metrics defines three primary metrics:

jellyfin_media_count

Gauge metric keyed by type. Reflects the number of different media types available on your Jellyfin server.

Example:

jellyfin_media_count{type="albums"} 120
jellyfin_media_count{type="movies"} 53

jellyfin_connected_clients_count

Gauge metric keyed by username. Shows the count of connected (but not necessarily playing) client sessions per user.

Example:

jellyfin_connected_clients_count{username="alice"} 1
jellyfin_connected_clients_count{username="bob"} 2

jellyfin_stream_count

Gauge metric keyed by username. Indicates the number of actively playing streams for each user.

Example:

jellyfin_stream_count{username="alice"} 1
jellyfin_stream_count{username="bob"} 0

Contributing

Contributions are welcome! If you have any suggestions or encounter a bug, please open an issue or submit a pull request.

When contributing:

1. Fork the repository and create a new feature branch.
2. Make your changes in a well-structured commit history.
3. Include tests (when applicable).
4. Submit a pull request with a clear description of your changes.

Changelog

A detailed list of changes and release notes is maintained in CHANGELOG.md. Refer to it for information about new features, fixes, and updates in each version.

License

Project uses MIT License, view the full details in the LICENSE file.

Happy monitoring!