OpenTelemetry Prometheus Exporter

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

• pip install opentelemetry-exporter-prometheus opentelemetry-sdk prometheus_client Install with SDK and Prometheus client

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

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.

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)