OpenTelemetry Prometheus Exporter

This library allows export of metrics data to Prometheus.

Usage

The OpenTelemetry Prometheus Exporter allows export of OpenTelemetry metrics to Prometheus.

from prometheus_client import start_http_server

from opentelemetry.exporter.prometheus import PrometheusMetricReader
from opentelemetry.metrics import get_meter_provider, set_meter_provider
from opentelemetry.sdk.metrics import MeterProvider

# Start Prometheus client
start_http_server(port=8000, addr="localhost")

# Exporter to export metrics to Prometheus
prefix = "MyAppPrefix"
reader = PrometheusMetricReader(prefix=prefix)

# Meter is responsible for creating and recording metrics
set_meter_provider(MeterProvider(metric_readers=[reader]))
meter = get_meter_provider().get_meter("myapp", "0.1.2")

counter = meter.create_counter(
    "requests",
    "requests",
    "number of requests",
)

# Labels are used to identify key-values that are associated with a specific
# metric that you want to record. These are useful for pre-aggregation and can
# be used to store custom dimensions pertaining to a metric
labels = {"environment": "staging"}

counter.add(25, labels)
input("Press any key to exit...")

API

class opentelemetry.exporter.prometheus.PrometheusMetricReader(disable_target_info=False, prefix='', scope_info_enabled=True, *, resource_attribute_filter=None, registry=<prometheus_client.registry.CollectorRegistry object>)[source]

Bases: MetricReader

Prometheus metric exporter for OpenTelemetry.

Parameters:

  • disable_target_info (bool) – Whether to disable the target_info metric.

  • prefix (str) – Prefix added to exported Prometheus metric names.

  • scope_info_enabled (bool) – Whether to include instrumentation scope labels on exported metrics. Scope labels are exported by default.

  • resource_attribute_filter (Callable[[str], bool] | None) – Optional callback to select resource attributes that are copied as labels on exported metrics. The callback receives the original resource attribute key. Selected keys are sanitized to valid Prometheus label names.

shutdown(timeout_millis=30000, **kwargs)[source]

Shuts down the MetricReader. This method provides a way for the MetricReader to do any cleanup required. A metric reader can only be shutdown once, any subsequent calls are ignored and return failure status.

When a MetricReader is registered on a MeterProvider, shutdown() will invoke this automatically.

Return type:

None

Installation

The OpenTelemetry Prometheus Exporter package is available on PyPI:

pip install opentelemetry-exporter-prometheus

Usage

The Prometheus exporter starts an HTTP server that collects metrics and serializes them to Prometheus text format on request:

from prometheus_client import start_http_server

from opentelemetry import metrics
from opentelemetry.exporter.prometheus import PrometheusMetricReader
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.resources import SERVICE_NAME, Resource

# Service name is required for most backends
resource = Resource.create(attributes={
    SERVICE_NAME: "your-service-name"
})

# Start Prometheus client
start_http_server(port=9464, addr="localhost")
# Initialize PrometheusMetricReader which pulls metrics from the SDK
# on-demand to respond to scrape requests
reader = PrometheusMetricReader()
provider = MeterProvider(resource=resource, metric_readers=[reader])
metrics.set_meter_provider(provider)

Scope labels

By default, the Prometheus exporter adds instrumentation scope information as labels on every exported metric. These labels include otel_scope_name, otel_scope_version, and otel_scope_schema_url. Instrumentation scope attributes are exported with the otel_scope_ prefix:

from prometheus_client import start_http_server

from opentelemetry import metrics
from opentelemetry.exporter.prometheus import PrometheusMetricReader
from opentelemetry.sdk.metrics import MeterProvider

start_http_server(port=9464, addr="localhost")
reader = PrometheusMetricReader()
provider = MeterProvider(metric_readers=[reader])
metrics.set_meter_provider(provider)

meter = metrics.get_meter(
    "checkout",
    "1.2.3",
    schema_url="https://opentelemetry.io/schemas/1.21.0",
    attributes={"region": "us-east-1"},
)
counter = meter.create_counter("orders")
counter.add(1, {"environment": "production"})

The exported metric includes labels such as otel_scope_name="checkout", otel_scope_version="1.2.3", otel_scope_schema_url="https://opentelemetry.io/schemas/1.21.0", otel_scope_region="us-east-1", and environment="production".

To omit instrumentation scope labels from exported metrics, set scope_info_enabled to False:

reader = PrometheusMetricReader(scope_info_enabled=False)

Resource labels

By default, resource attributes are exported on the target_info metric. To also add selected resource attributes as Prometheus labels on every exported metric, pass a resource_attribute_filter callback to PrometheusMetricReader. The callback receives the original resource attribute key and returns True for attributes that should be copied to metric labels:

from prometheus_client import start_http_server

from opentelemetry import metrics
from opentelemetry.exporter.prometheus import PrometheusMetricReader
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.resources import SERVICE_NAME, Resource

resource = Resource.create(
    attributes={
        SERVICE_NAME: "checkout-service",
        "service.namespace": "shop",
        "deployment.environment": "production",
    }
)

start_http_server(port=9464, addr="localhost")
included_resource_attrs = {SERVICE_NAME, "service.namespace"}
reader = PrometheusMetricReader(
    resource_attribute_filter=lambda key: key in included_resource_attrs
)
provider = MeterProvider(resource=resource, metric_readers=[reader])
metrics.set_meter_provider(provider)

meter = metrics.get_meter(__name__)
counter = meter.create_counter("orders")
counter.add(1)

The exported metric includes service_name="checkout-service" and service_namespace="shop" labels. Resource attribute keys are sanitized to valid Prometheus label names, and metric attributes with the same sanitized name take precedence over copied resource attributes.

Configuration

The following environment variables are supported:

  • OTEL_EXPORTER_PROMETHEUS_HOST (default: “localhost”): The host to bind to

  • OTEL_EXPORTER_PROMETHEUS_PORT (default: 9464): The port to bind to

Limitations

  • No multiprocessing support: The Prometheus exporter is not designed to operate in multiprocessing environments (see #3747).

References