Registry / observability / prometheus-client

prometheus-client

JSON →
library0.24.1pypypi✓ verified 52d ago

Python client for the Prometheus monitoring system, currently at version 0.24.1. It is actively maintained with frequent updates for enhancements and bug fixes.

observabilitydevops
pip install prometheus-client
Install & Compatibility
Where this runs
tested against v0.25.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.925 runs
installs and imports cleanly · install 0.0s · import 0.226s · 18.3MB
glibc
py 3.103.925 runs
installs and imports cleanly · install 1.6s · import 0.212s · 19MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

CollectorRegistry
from prometheus_client import CollectorRegistry
Ensure you import from prometheus_client, not any incorrect paths.

Start a Prometheus server on port 8000.

from prometheus_client import start_http_server, CollectorRegistry import time registry = CollectorRegistry() start_http_server(8000) while True: time.sleep(1)
Debug
Known issues
breakingBreaking changes in HTTP method validation introduced in v0.21.0.
fix
Ensure your HTTP methods conform to GET or OPTIONS to avoid requests being rejected.
affects: < 0.21.0
gotchaIncorrect usage of CollectorRegistry may lead to metrics not appearing.
fix
Always create and use a CollectorRegistry instance for metric registration.
affects: all
gotchaA timeout occurred during test execution, indicating a potential long-running operation, deadlock, or resource exhaustion.
fix
Investigate application logs, system metrics, and resource usage for the tests. Consider increasing timeouts, optimizing code, or checking for infinite loops/deadlocks.
affects: all
breakingThe test timed out, indicating a potential infinite loop, deadlock, or an exceptionally long-running operation.
fix
Investigate the application's execution flow for potential deadlocks, infinite loops, or resource contention that could cause extended execution times.
affects: unknown
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'prometheus_client'
This error occurs when the `prometheus-client` library is not installed, not installed in the active Python environment, or imported incorrectly. A common mistake is trying to import `prometheus.client` instead of `prometheus_client`.
fix
Ensure the library is installed using `pip install prometheus-client` and then import it correctly using `import prometheus_client` or `from prometheus_client import ...`
AttributeError: 'Gauge' object has no attribute 'labels'
This error typically arises when attempting to access a `.labels()` method directly on a metric object (like a `Gauge` or `Counter`) that was created without specifying label names in its constructor. Labels must be defined when the metric is initialized to allow setting their values later.
fix
When creating the metric, define the label names as a list of strings. Then, to set label values, call the `.labels()` method with the corresponding values. For example: `my_gauge = Gauge('my_gauge', 'Description', ['label_name'])` and then `my_gauge.labels('value').set(10)`
ValueError: Duplicated timeseries in CollectorRegistry
Collector already registered that provides name: <metric_name>
This error indicates that you are attempting to register a metric with the same name multiple times within the same `CollectorRegistry`. Prometheus metrics must have unique names within a registry. This often happens when metrics are defined globally and imported multiple times, or when a function creating metrics is called repeatedly.
fix
Ensure each metric is registered only once. Define metrics at the module level or use a pattern to prevent re-registration, especially in tests or applications with hot-reloading. You can pass a specific `registry` to the metric constructor to avoid interfering with the default global registry. For example: `my_gauge = Gauge('my_unique_gauge_name', 'Help text')` (defined once) or use `REGISTRY.unregister(metric)` for testing scenarios, though it's generally discouraged in production.
OSError: [Errno 98] Address already in use
This error occurs when `prometheus_client.start_http_server()` is called, but the specified port is already in use by another process on the system.
fix
Change the port number passed to `start_http_server()` to an available one, or identify and terminate the process currently using the desired port. You can use OS commands like `netstat -tulnp | grep <port>` (Linux) or `lsof -i :<port>` (macOS) to find the offending process.
Upgrade
Version history
0.25.0latest on PyPI
Audit
Dependencies

No dependency data recorded yet.

Agent activity
18 hits · last 30 days
node
8
seranking-bot
3
ahrefsbot
2
Resources