OpenTelemetry Prometheus Exporter
raw JSON → 0.61b0 verified Tue May 12 auth: no python install: verified quickstart: stale
The `opentelemetry-exporter-prometheus` library provides a Prometheus Metric Exporter for OpenTelemetry, allowing applications instrumented with OpenTelemetry to expose their metrics in a format that a Prometheus server can scrape. It is part of the larger OpenTelemetry Python project, currently at version 0.61b0, and is under active development with frequent releases.
pip install opentelemetry-exporter-prometheus opentelemetry-sdk prometheus_client Common errors
error ImportError: cannot import name 'PrometheusMetricsExporter' from 'opentelemetry.exporter.prometheus' ↓
cause The class name for the Prometheus metrics exporter changed from `PrometheusMetricsExporter` to `PrometheusMetricReader` in newer versions of the OpenTelemetry Python SDK, and the metric pipeline configuration also evolved.
fix
Update your import statement and metric reader registration to use
PrometheusMetricReader and configure it via MeterProvider's metric_readers argument.
from opentelemetry.exporter.prometheus import PrometheusMetricReader
from opentelemetry.sdk.metrics import MeterProvider
reader = PrometheusMetricReader()
provider = MeterProvider(metric_readers=[reader])
# ... then set as global provider: metrics.set_meter_provider(provider)error AttributeError: ("'int' object has no attribute 'replace'", Metric(target, Target metadata, info ...) ↓
cause This error occurs when resource attributes, especially those intended for `target_info` metrics, contain non-string values (e.g., integers), as Prometheus client library expects all label key-value pairs to be strings.
fix
Ensure that all values in the
Resource attributes you provide to the MeterProvider are strings.
from opentelemetry.sdk.resources import SERVICE_NAME, Resource
resource = Resource(attributes={
SERVICE_NAME: "your-service-name",
"foo": "bar_string_value",
"hist": "1" # Convert non-string values to strings
})error ModuleNotFoundError: No module named 'opentelemetry.exporter.prometheus' ↓
cause The `opentelemetry-exporter-prometheus` package, or a necessary sub-module, is not installed in the current Python environment or the import path is incorrect.
fix
Install the correct package using pip:
pip install opentelemetry-exporter-prometheus. Verify your Python environment and virtual environment setup. error "metric XXX was collected before with the same name and label values" ↓
cause Prometheus strictly requires that each metric (identified by its name and a unique set of label values) is collected only once per scrape and has a consistent type. This error indicates that the exporter is attempting to register the same metric with conflicting definitions or duplicate timeseries.
fix
Review your OpenTelemetry instrumentation to ensure that metrics with identical names and label sets are not being created with different types or conflicting configurations. If using an OpenTelemetry Collector, check the collector configuration for metric renaming or aggregation that might lead to conflicts. This can also be caused by resource attributes (like
service.name or service.instance.id) not being distinct enough for different metric sources. Warnings
breaking The `opentelemetry-exporter-prometheus` package is currently in 'beta' and is marked as 'experimental'. New releases may introduce breaking changes to its API or behavior before it reaches a stable (1.0) release. ↓
fix Always pin to exact versions (`==x.y.z`) and review changelogs thoroughly during upgrades. Consider using the OpenTelemetry Collector for production environments if API stability is critical.
gotcha OpenTelemetry and Prometheus have different naming conventions. The exporter automatically translates OpenTelemetry metric and attribute names to comply with Prometheus rules (e.g., dots become underscores, units and `_total` suffixes are added for counters). This can lead to unexpected metric names in Prometheus. ↓
fix Be aware of the translation rules when querying metrics in Prometheus. Consult the OpenTelemetry documentation on Prometheus compatibility and metric naming normalization.
gotcha Prometheus primarily supports cumulative counter metrics. If OpenTelemetry metrics are configured to export as delta temporality, they may not be correctly interpreted or displayed in Prometheus. ↓
fix Ensure your OpenTelemetry SDK configuration for metrics uses cumulative temporality, which is often the default for OTLP export. Review temporality settings if metrics are missing or appear incorrect.
gotcha The direct SDK export of Prometheus metrics, while simple, may not scale well for large applications or complex deployments. It forces all metrics into a single scrape endpoint, potentially leading to performance and reliability issues. ↓
fix For production or larger scale environments, it is generally recommended to use an OpenTelemetry Collector. Applications can export metrics to the Collector via OTLP, and the Collector can then expose them to Prometheus via its own Prometheus exporter, offering more flexibility and control.
gotcha The PrometheusMetricReader starts an HTTP server to expose metrics, defaulting to port 9464. If another service is already using this port, the exporter will fail to start. ↓
fix Ensure the default port 9464 is available. If not, configure a different port for the `PrometheusMetricReader` when initializing it, or for the `start_http_server` call if used directly.
Install compatibility verified last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) - - 0.71s 22.8M
3.10 slim (glibc) - - 0.63s 23M
3.11 alpine (musl) - - 1.26s 25.2M
3.11 slim (glibc) - - 0.86s 26M
3.12 alpine (musl) - - 1.08s 16.9M
3.12 slim (glibc) - - 1.41s 17M
3.13 alpine (musl) - - 0.56s 16.5M
3.13 slim (glibc) - - 0.80s 17M
3.9 alpine (musl) - - 0.70s 22.3M
3.9 slim (glibc) - - 0.77s 23M
Imports
- PrometheusMetricReader
from opentelemetry.exporter.prometheus import PrometheusMetricReader - MeterProvider
from opentelemetry.sdk.metrics import MeterProvider - PeriodicExportingMetricReader
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader - Resource, SERVICE_NAME
from opentelemetry.sdk.resources import Resource, SERVICE_NAME - start_http_server
from prometheus_client import start_http_server
Quickstart stale last tested: 2026-04-23
import os
import time
from opentelemetry import metrics
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.exporter.prometheus import PrometheusMetricReader
from opentelemetry.sdk.resources import Resource, SERVICE_NAME
from prometheus_client import start_http_server
# Configure the MeterProvider with the PrometheusMetricReader
# PrometheusMetricReader starts an HTTP server, typically on port 9464.
# Ensure this port is available or configure a different one.
reader = PrometheusMetricReader()
provider = MeterProvider(
resource=Resource.create({
SERVICE_NAME: os.environ.get('OTEL_SERVICE_NAME', 'my-prometheus-service')
}),
metric_readers=[reader]
)
metrics.set_meter_provider(provider)
# Start the Prometheus HTTP server for scraping
# By default, it serves on 0.0.0.0:9464/metrics
start_http_server(port=9464, addr='0.0.0.0')
# Get a meter from the MeterProvider
meter = metrics.get_meter(__name__)
# Create a counter instrument
requests_counter = meter.create_counter(
name='requests_total',
description='Total number of requests',
unit='1'
)
print("Prometheus exporter running on http://localhost:9464/metrics")
print("Press Ctrl+C to exit")
# Simulate work and increment the counter
while True:
requests_counter.add(1, {"route": "/", "method": "GET"})
time.sleep(1)