Registry /
observability / opentelemetry-exporter-prometheus-remote-write
Install & Compatibility
Where this runs
tested against v0.65b0 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.844s · 31.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.3s · import 0.570s · 32MB
30MB installed
● package 30MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PrometheusRemoteWriteMetricsExporter
✓ from opentelemetry.exporter.prometheus_remote_write import PrometheusRemoteWriteMetricsExporter
MeterProvider
✓ from opentelemetry.sdk.metrics import MeterProvider
PeriodicExportingMetricReader
✓ from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
This quickstart demonstrates how to configure the Prometheus Remote Write exporter with a `MeterProvider` and a `PeriodicExportingMetricReader`. It creates a simple counter and adds observations, then gracefully shuts down the provider to ensure all metrics are exported. Remember to adjust the `endpoint` to your actual Prometheus remote write receiver.
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_remote_write import PrometheusRemoteWriteMetricsExporter
# Configure the Prometheus Remote Write exporter
# The endpoint should point to your Prometheus-compatible remote write receiver
# e.g., Prometheus with remote_write enabled, Mimir, Thanos, Cortex.
# Use os.environ.get for sensitive info like API keys/tokens if headers are needed.
exporter = PrometheusRemoteWriteMetricsExporter(
endpoint=os.environ.get('OTEL_PROMETHEUS_REMOTE_WRITE_ENDPOINT', 'http://localhost:9090/api/v1/write'),
# headers={'Authorization': f'Bearer {os.environ.get("PROMETHEUS_API_TOKEN", "")}'},
timeout=30
)
# Configure the MeterProvider with a PeriodicExportingMetricReader
# The reader exports metrics to the exporter at a specified interval (default 60s).
reader = PeriodicExportingMetricReader(exporter, export_interval_millis=5000) # Export every 5 seconds for demonstration
meter_provider = MeterProvider(metric_readers=[reader])
# Set the global MeterProvider (optional, but good practice)
metrics.set_meter_provider(meter_provider)
# Get a meter from the provider
meter = metrics.get_meter(__name__)
# Create a counter
request_counter = meter.create_counter(
"http_requests_total",
description="Total number of HTTP requests",
unit="1"
)
# Record some observations
print("Recording metrics...")
request_counter.add(1, {"method": "GET", "path": "/home"})
time.sleep(1) # Give some time for the reader to potentially queue for export
request_counter.add(2, {"method": "POST", "path": "/data"})
time.sleep(1) # More time
request_counter.add(1, {"method": "GET", "path": "/home"})
print("Metrics recorded. Waiting for export...")
# In a real application, you'd keep the application running
# For this example, we'll wait a bit longer to ensure export happens.
time.sleep(6) # Wait for at least one export cycle (5 seconds + buffer)
# Shutdown the meter provider to ensure all buffered metrics are exported gracefully
# This is crucial in short-lived applications or before exiting.
print("Shutting down MeterProvider...")
meter_provider.shutdown()
print("Application finished.")
Debug
Known issues
gotchaThe package is in beta (indicated by `b0` in the version number). This means the API and behavior might change in future versions without adhering to strict semantic versioning, potentially introducing breaking changes.fixAlways pin to a specific beta version (`==0.62b0`) and thoroughly test when upgrading to newer beta releases. Monitor OpenTelemetry Python Contrib release notes for changes.
affects: 0.62b0 and earlier beta versions
gotchaThis exporter only handles OpenTelemetry Metrics. It does not export Traces or Logs. For those signals, you would need to configure separate exporters (e.g., OTLP exporter for traces/logs).fixEnsure you understand which signals each exporter handles. If you need to export multiple signal types, configure a dedicated exporter for each.
affects: All versions
gotchaThe `PeriodicExportingMetricReader` exports metrics asynchronously at intervals. If your application is short-lived, you must ensure it runs long enough for at least one export cycle to complete and call `meter_provider.shutdown()` before exiting to flush any remaining metrics.fixFor short-lived scripts, add `time.sleep()` calls after recording metrics and always call `meter_provider.shutdown()` at the end of your application's lifecycle to guarantee metric delivery.
affects: All versions
gotchaConfiguration of the Prometheus Remote Write `endpoint` and any required `headers` (e.g., for authentication or proxy routing) is crucial. Incorrect endpoint URLs or missing authentication headers are common reasons for metrics not appearing in the receiver.fixDouble-check the `endpoint` URL. If your Prometheus remote write receiver requires authentication or specific routing headers, pass them via the `headers` dictionary to the `PrometheusRemoteWriteMetricsExporter` constructor. Test connectivity and authentication independently if issues arise.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'opentelemetry.exporter.prometheus_remote_write'
The `opentelemetry-exporter-prometheus-remote-write` package is either not installed in your Python environment or there is a typo in the import statement.
fixInstall the package using pip: `pip install opentelemetry-exporter-prometheus-remote-write`. Ensure the import statement in your code is `from opentelemetry.exporter.prometheus_remote_write import PrometheusRemoteWriteMetricsExporter`.
AttributeError: '_ProxyMeterProvider' object has no attribute 'start_pipeline'
This error indicates an attempt to use the deprecated `start_pipeline` method, which was part of an older OpenTelemetry Python SDK API. The modern approach uses `MeterProvider` with a `PeriodicExportingMetricReader` to manage the metrics pipeline.
fixRefactor your metrics pipeline setup to use `PeriodicExportingMetricReader` with `MeterProvider`. Example:
```python
from opentelemetry import metrics
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.exporter.prometheus_remote_write import PrometheusRemoteWriteMetricsExporter
from opentelemetry.sdk.resources import SERVICE_NAME, Resource
resource = Resource.create(attributes={SERVICE_NAME: "my-service"})
exporter = PrometheusRemoteWriteMetricsExporter(endpoint="http://localhost:9090/api/v1/write")
reader = PeriodicExportingMetricReader(exporter)
provider = MeterProvider(resource=resource, metric_readers=[reader])
metrics.set_meter_provider(provider)
# Your meter and instruments can now be created via metrics.get_meter(__name__)
``` remote write returned HTTP status 400 Bad Request; err = <nil>: user=...: err: out of order sample.
Prometheus remote write endpoints expect metric samples for a given time series to arrive with strictly increasing timestamps. This error occurs when the exporter sends samples out of sequence or with duplicate timestamps, often under heavy load or due to incorrect metric processing.
fixEnsure that the timestamps generated for your metrics are strictly monotonic for each unique time series. If using an OpenTelemetry Collector, review its configuration for any processors that might inadvertently reorder or duplicate samples. Confirm that your application's metric updates do not assign older or identical timestamps to existing series.
No metrics were sent to the remote write destination (from logs) / Metrics not appearing in Prometheus backend
This issue typically arises from a misconfiguration of the exporter's `endpoint` URL, missing or incorrect authentication, network connectivity problems (firewall, DNS), or the Prometheus server not being properly enabled to receive remote writes. Additionally, Prometheus expects cumulative temporality for counters, and if the SDK is configured to send delta temporality, metrics might be ignored.
fix1. Verify the `endpoint` URL is correct and accessible (e.g., `http://localhost:9090/api/v1/write`).
2. Check network connectivity and firewall rules between your application and the Prometheus remote write endpoint.
3. Ensure the Prometheus server (or compatible backend) is configured to accept remote writes; for Prometheus, this often means enabling the `--enable-feature=remote-write-receiver` flag.
4. Review your exporter's configuration for any required `headers` (e.g., for `Authorization` or `X-Scope-Org-ID`) and ensure they are correctly set.
5. Confirm that OpenTelemetry SDK metrics are configured with `cumulative` temporality for Prometheus compatibility, although most SDKs default to this for OTLP export.
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
opentelemetry-sdkrequiredRequired for core OpenTelemetry SDK functionalities, including MeterProvider and MetricReader.
opentelemetry-apirequiredRequired for OpenTelemetry API definitions, such as Meter and Counter.
prometheus_clientrequiredUsed internally for handling Prometheus specific data structures and serialization.
protobufrequiredRequired for serializing metrics into Prometheus Remote Write protocol buffer format.