{"id":548,"library":"opentelemetry-exporter-prometheus","title":"OpenTelemetry Prometheus Exporter","description":"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.","status":"active","version":"0.61b0","language":"python","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python","tags":["observability","metrics","prometheus","opentelemetry","exporter"],"install":[{"cmd":"pip install opentelemetry-exporter-prometheus opentelemetry-sdk prometheus_client","lang":"bash","label":"Install with SDK and Prometheus client"}],"dependencies":[{"reason":"Required for OpenTelemetry metric collection and MeterProvider setup.","package":"opentelemetry-sdk"},{"reason":"Used by the exporter to start the HTTP server for Prometheus scraping.","package":"prometheus_client"}],"imports":[{"symbol":"PrometheusMetricReader","correct":"from opentelemetry.exporter.prometheus import PrometheusMetricReader"},{"symbol":"MeterProvider","correct":"from opentelemetry.sdk.metrics import MeterProvider"},{"symbol":"PeriodicExportingMetricReader","correct":"from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader"},{"symbol":"Resource, SERVICE_NAME","correct":"from opentelemetry.sdk.resources import Resource, SERVICE_NAME"},{"symbol":"start_http_server","correct":"from prometheus_client import start_http_server"}],"quickstart":{"code":"import os\nimport time\nfrom opentelemetry import metrics\nfrom opentelemetry.sdk.metrics import MeterProvider\nfrom opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader\nfrom opentelemetry.exporter.prometheus import PrometheusMetricReader\nfrom opentelemetry.sdk.resources import Resource, SERVICE_NAME\nfrom prometheus_client import start_http_server\n\n# Configure the MeterProvider with the PrometheusMetricReader\n# PrometheusMetricReader starts an HTTP server, typically on port 9464.\n# Ensure this port is available or configure a different one.\nreader = PrometheusMetricReader()\nprovider = MeterProvider(\n    resource=Resource.create({\n        SERVICE_NAME: os.environ.get('OTEL_SERVICE_NAME', 'my-prometheus-service')\n    }),\n    metric_readers=[reader]\n)\nmetrics.set_meter_provider(provider)\n\n# Start the Prometheus HTTP server for scraping\n# By default, it serves on 0.0.0.0:9464/metrics\nstart_http_server(port=9464, addr='0.0.0.0')\n\n# Get a meter from the MeterProvider\nmeter = metrics.get_meter(__name__)\n\n# Create a counter instrument\nrequests_counter = meter.create_counter(\n    name='requests_total',\n    description='Total number of requests',\n    unit='1'\n)\n\nprint(\"Prometheus exporter running on http://localhost:9464/metrics\")\nprint(\"Press Ctrl+C to exit\")\n\n# Simulate work and increment the counter\nwhile True:\n    requests_counter.add(1, {\"route\": \"/\", \"method\": \"GET\"})\n    time.sleep(1)\n","lang":"python","description":"This quickstart demonstrates how to set up the OpenTelemetry Prometheus Exporter. It initializes a `MeterProvider` with a `PrometheusMetricReader` which automatically starts an HTTP server on port 9464 (by default) that Prometheus can scrape. It then creates a simple counter and increments it periodically, exposing the metric for Prometheus to collect. Remember to set the `OTEL_SERVICE_NAME` environment variable for better metric identification."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0"},{"fix":"Be aware of the translation rules when querying metrics in Prometheus. Consult the OpenTelemetry documentation on Prometheus compatibility and metric naming normalization.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T14:59:04.575Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Update your import statement and metric reader registration to use `PrometheusMetricReader` and configure it via `MeterProvider`'s `metric_readers` argument.\n\n```python\nfrom opentelemetry.exporter.prometheus import PrometheusMetricReader\nfrom opentelemetry.sdk.metrics import MeterProvider\n\nreader = PrometheusMetricReader()\nprovider = MeterProvider(metric_readers=[reader])\n# ... then set as global provider: metrics.set_meter_provider(provider)\n```","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.","error":"ImportError: cannot import name 'PrometheusMetricsExporter' from 'opentelemetry.exporter.prometheus'"},{"fix":"Ensure that all values in the `Resource` attributes you provide to the `MeterProvider` are strings.\n\n```python\nfrom opentelemetry.sdk.resources import SERVICE_NAME, Resource\n\nresource = Resource(attributes={\n    SERVICE_NAME: \"your-service-name\",\n    \"foo\": \"bar_string_value\",\n    \"hist\": \"1\" # Convert non-string values to strings\n})\n```","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.","error":"AttributeError: (\"'int' object has no attribute 'replace'\", Metric(target, Target metadata, info ...)"},{"fix":"Install the correct package using pip: `pip install opentelemetry-exporter-prometheus`. Verify your Python environment and virtual environment setup.","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.","error":"ModuleNotFoundError: No module named 'opentelemetry.exporter.prometheus'"},{"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.","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.","error":"\"metric XXX was collected before with the same name and label values\""}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.71,"mem_mb":15.6,"disk_size":"22.8M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.63,"mem_mb":15.6,"disk_size":"23M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.26,"mem_mb":16.5,"disk_size":"25.2M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.86,"mem_mb":16.5,"disk_size":"26M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.08,"mem_mb":16.6,"disk_size":"16.9M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.41,"mem_mb":16.6,"disk_size":"17M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.56,"mem_mb":16.7,"disk_size":"16.5M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.8,"mem_mb":16.7,"disk_size":"17M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.7,"mem_mb":15.3,"disk_size":"22.3M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.77,"mem_mb":15.3,"disk_size":"23M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":-1},{"runtime":"python:3.10-slim","exit_code":-1},{"runtime":"python:3.11-alpine","exit_code":-1},{"runtime":"python:3.11-slim","exit_code":-1},{"runtime":"python:3.12-alpine","exit_code":-1},{"runtime":"python:3.12-slim","exit_code":-1},{"runtime":"python:3.13-alpine","exit_code":-1},{"runtime":"python:3.13-slim","exit_code":-1},{"runtime":"python:3.9-alpine","exit_code":-1},{"runtime":"python:3.9-slim","exit_code":-1}]}}