How to Turn Prometheus Histograms Into OTLP Metrics With the OpenTelemetry Collector

If you run an application that already exposes Prometheus metrics, at some point you will probably want to send that data somewhere that only understands OTLP (the OpenTelemetry Protocol): a vendor observability platform, a self-hosted OpenTelemetry backend, or a pipeline that also carries your traces and logs. The problem is that Prometheus and OpenTelemetry do not describe a histogram the same way on the wire. If you forward Prometheus text straight into an OTLP-only backend, or hand-write the mapping yourself, you can quietly corrupt your own latency data.

In this tutorial you will build a small Python API that exposes a real Prometheus histogram, run the actual OpenTelemetry Collector (the open source tool that does this conversion for you) against it with no Docker involved, and then read the Collector’s own debug output and OTLP JSON to see, with real numbers, exactly how a Prometheus histogram becomes an OpenTelemetry histogram. Along the way you will also learn what a Prometheus histogram actually is under the hood, since that is the part most guides skip and the part that causes the most confusion later.

What You Will Build, and Why the Conversion Matters

Before writing any code, it helps to be precise about three terms that get used loosely.

Prometheus is both a metrics storage system and a text-based wire format. Applications instrumented with a Prometheus client library expose a /metrics HTTP endpoint. A Prometheus server (or, in our case, the OpenTelemetry Collector wearing a Prometheus hat) periodically sends an HTTP GET to that endpoint and parses whatever plain text comes back. This pull-based act of fetching is called a scrape.

OTLP is the OpenTelemetry Protocol: a schema and wire format (usually Protocol Buffers over gRPC or HTTP) for shipping metrics, traces, and logs to any backend that speaks OTLP. It is vendor-neutral by design, which is why so many observability products accept it.

The OpenTelemetry Collector is a standalone process that sits between your applications and your backend. It has three kinds of building blocks wired together in a pipeline: receivers pull or accept data (our Prometheus receiver scrapes your app), processors optionally transform it in flight, and exporters send it onward (to a real backend, or in our case to the terminal and a local file so we can inspect exactly what would have been sent).

The specific wrinkle we are here to solve involves histograms, a metric type used for anything you want to measure as a distribution rather than a single number, like request latency. Prometheus’s histogram wire format is cumulative: it publishes a running count of “how many observations were less than or equal to X seconds” for each of several thresholds. OpenTelemetry’s histogram data model is not cumulative in the same way: it stores the count of observations that fell within each range. The Prometheus receiver has to do real subtraction to get from one to the other, and by the end of this tutorial you will have proven that arithmetic yourself, with your own captured numbers, not just read about it.

Prerequisites

• A 64-bit Windows, macOS, or Linux machine. Everything here runs as a plain executable; no Docker or container runtime is required, even though most walkthroughs for this topic assume you have one.
• Python 3.10 or newer with pip. This tutorial was built and verified against Python 3.13.14.
• Comfort running commands in a terminal and reading JSON or YAML. No prior OpenTelemetry knowledge is assumed; every field in the config file is explained as we go.
• About 400 MB of free disk space (the Collector’s Contrib distribution is a large single binary because it bundles dozens of optional components).

Step 1: Build a Demo App With a Real Prometheus Histogram

We will simulate a small order-fulfillment API: a warehouse system that processes orders with a realistic mix of fast and occasionally slow requests. Create a project folder, then a virtual environment, and install three packages: fastapi and uvicorn to serve HTTP, and prometheus-client, the official Python client library that implements the actual Prometheus metric types and text format.

mkdir otel-prom-tutorial
cd otel-prom-tutorial
python -m venv venv

# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate

pip install fastapi uvicorn prometheus-client

This tutorial was verified against fastapi 0.141.1, uvicorn 0.52.4, and prometheus-client 0.26.0. Now create app.py:

import random
import time

from fastapi import FastAPI, Response
from prometheus_client import Counter, Histogram, generate_latest, CONTENT_TYPE_LATEST

app = FastAPI()

ORDER_DURATION = Histogram(
    "order_processing_duration_seconds",
    "Time spent processing a fulfillment order, in seconds",
    buckets=(0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0),
)

ORDERS_TOTAL = Counter(
    "orders_processed_total",
    "Total number of fulfillment orders processed",
    ["status"],
)


def do_fulfillment_work():
    # Most orders are fast. A slice are moderately slow. A rare few
    # hit a cold inventory lookup and take much longer, which is what
    # a real latency distribution usually looks like.
    if random.random() < 0.08:
        time.sleep(random.uniform(1.5, 3.0))
    elif random.random() < 0.20:
        time.sleep(random.uniform(0.4, 0.9))
    else:
        time.sleep(random.uniform(0.02, 0.2))


@app.post("/process/{order_id}")
def process_order(order_id: str):
    start = time.perf_counter()
    do_fulfillment_work()
    elapsed = time.perf_counter() - start
    ORDER_DURATION.observe(elapsed)
    ORDERS_TOTAL.labels(status="success").inc()
    return {"order_id": order_id, "elapsed_seconds": round(elapsed, 4)}


@app.get("/metrics")
def metrics():
    return Response(generate_latest(), media_type=CONTENT_TYPE_LATEST)


@app.get("/")
def root():
    return {"service": "order-fulfillment-demo"}

Two design choices in this file matter for what comes next. First, buckets=(0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0) defines the histogram’s bucket boundaries in seconds. A histogram with N explicit boundaries always has N+1 buckets, because there is an implicit final bucket that catches everything larger than the last boundary. Here that means 8 buckets total. Second, ORDER_DURATION.observe(elapsed) is the entire instrumentation API: you hand the client library one number, and it decides which bucket that observation falls into and updates the running totals.

Start the server:

uvicorn app:app --host 127.0.0.1 --port 8000

In a second terminal, confirm it is alive:

curl http://127.0.0.1:8000/

{"service":"order-fulfillment-demo"}

Step 2: Read the Raw Prometheus Text Format Before Converting Anything

Generate exactly 20 requests, so the numbers in this walkthrough match what you will see on your own screen if you follow along with the same random seed conditions:

for i in $(seq 1 20); do
  curl -s -X POST "http://127.0.0.1:8000/process/ORD-$i" > /dev/null
done

Now fetch the raw metrics endpoint directly, before any OpenTelemetry component is involved:

curl http://127.0.0.1:8000/metrics

Among the output you will see a block that looks like this (real output, captured from exactly this setup):

# HELP order_processing_duration_seconds Time spent processing a fulfillment order, in seconds
# TYPE order_processing_duration_seconds histogram
order_processing_duration_seconds_bucket{le="0.05"} 2.0
order_processing_duration_seconds_bucket{le="0.1"} 6.0
order_processing_duration_seconds_bucket{le="0.25"} 13.0
order_processing_duration_seconds_bucket{le="0.5"} 14.0
order_processing_duration_seconds_bucket{le="1.0"} 17.0
order_processing_duration_seconds_bucket{le="2.5"} 19.0
order_processing_duration_seconds_bucket{le="5.0"} 20.0
order_processing_duration_seconds_bucket{le="+Inf"} 20.0
order_processing_duration_seconds_count 20.0
order_processing_duration_seconds_sum 11.142739900038578
# HELP order_processing_duration_seconds_created Time spent processing a fulfillment order, in seconds
# TYPE order_processing_duration_seconds_created gauge
order_processing_duration_seconds_created 1.787773619262937e+09

Read this carefully, because everything downstream depends on understanding it. Each _bucket{le="X"} line is a running total of observations less than or equal to X seconds, and the label le literally stands for “less than or equal.” Critically, these counts are cumulative: the le="0.25" bucket’s value of 13 already includes the 2 observations counted in le="0.05" and the 6 counted in le="0.1". The final le="+Inf" bucket always equals the overall _count, because every observation is, trivially, less than or equal to infinity. Alongside the buckets, Prometheus also publishes _count (the total number of observations) and _sum (the total of all observed values, which lets you compute an average if you divide the two).

Notice the extra _created series too. The Python client automatically adds this gauge, recording the Unix timestamp when the metric was first created. You did not ask for it and will not call any method to produce it; it just appears. Keep this in mind, because it resurfaces as its own oddity once the data reaches OpenTelemetry’s side.

Step 3: Install the OpenTelemetry Collector, No Docker Required

Almost every walkthrough for this topic tells you to run the Collector inside Docker. You do not need to. The opentelemetry-collector-releases project publishes the Collector as a single self-contained executable for Windows, macOS, and Linux, and running it is no different from running any other command-line tool you download.

There are two official distributions. The plain otelcol distribution ships a smaller, curated set of components. The otelcol-contrib distribution bundles a much larger set of community-maintained receivers, processors, and exporters, which is why it is the one most tutorials (including this one) reach for by default while you are still exploring what is available. As it happens, both distributions’ current manifests already include the Prometheus receiver and the debug and file exporters this tutorial uses, so you are not locked into Contrib for this specific pipeline; you would only need it once you start reaching for a less common component.

Download the release that matches your platform (this example uses Windows; substitute linux_amd64 or darwin_arm64 as needed) from the GitHub releases page, along with its published checksum:

curl -sL -o otelcol-contrib.tar.gz "https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.159.0/otelcol-contrib_0.159.0_windows_amd64.tar.gz"
curl -sL -o otelcol-contrib.tar.gz.sha256 "https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.159.0/otelcol-contrib_0.159.0_windows_amd64.tar.gz.sha256"

Always verify a downloaded binary against its published checksum before running it. This is a habit worth having for any tool you pull from the internet, not just this one:

sha256sum otelcol-contrib.tar.gz
cat otelcol-contrib.tar.gz.sha256

86434cf172aa91a5fc148978dad9bfaacd25a80bd2df93f19015814e7c5359bb *otelcol-contrib.tar.gz
86434cf172aa91a5fc148978dad9bfaacd25a80bd2df93f19015814e7c5359bb

Both hashes match, so the download is intact. Extract it and confirm the binary runs:

tar -xzf otelcol-contrib.tar.gz
./otelcol-contrib --version

otelcol-contrib version 0.159.0

Step 4: Write a Collector Configuration for This Pipeline

The Collector reads a single YAML file describing its receivers, exporters, and how they connect. Create otel-collector-config.yaml:

receivers:
  prometheus:
    config:
      scrape_configs:
        - job_name: order-fulfillment-demo
          scrape_interval: 5s
          static_configs:
            - targets: ["127.0.0.1:8000"]

exporters:
  debug:
    verbosity: detailed
  file:
    path: ./otlp-output.json

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      exporters: [debug, file]

Walking through each part: under receivers.prometheus.config.scrape_configs, job_name is a label used to group everything this receiver collects, scrape_interval controls how often it polls the target (5 seconds here so you do not have to wait long while testing; a real deployment usually uses 15 to 60 seconds), and targets lists one or more host:port pairs exposing a /metrics endpoint. This is precisely the same configuration shape a standalone Prometheus server uses, because the Prometheus receiver’s own documentation confirms it “uses the scrape manager and parser implementation from prometheus/prometheus” directly, rather than reimplementing scraping itself.

The exporters section defines two destinations we will inspect directly instead of paying for or signing up with a real backend. The debug exporter prints every metric it receives to the Collector’s own console output; setting verbosity: detailed is what makes it print full bucket-level detail instead of just a summary count. The file exporter writes the exact same data as newline-delimited OTLP JSON to disk, which is the closest thing to seeing the real wire payload without standing up a gRPC listener yourself. Finally, service.pipelines.metrics wires it all together: one metrics pipeline, reading from the prometheus receiver and writing to both exporters at once.

Step 5: Run the Collector and Confirm It Found Your App

./otelcol-contrib --config otel-collector-config.yaml

You should see startup log lines ending with confirmation that the scrape job was registered and the Collector is running:

info    [email protected]/metrics_receiver.go:159 Starting discovery manager
info    targetallocator/manager.go:228 Scrape job added    {"jobName": "order-fulfillment-demo"}
info    [email protected]/service.go:282 Everything is ready. Begin running and processing data.

Leave this running in its own terminal window. Every 5 seconds it will scrape your demo app and push whatever it finds through the debug and file exporters.

Step 6: Watch the Actual Conversion Happen, and Verify the Arithmetic Yourself

With the app still holding the same 20 requests from Step 2 (do not send any more yet), wait a few seconds for the Collector’s next scrape, then look at its console output. You will find a block naming your histogram metric:

Metric #3
Descriptor:
     -> Name: order_processing_duration_seconds
     -> Description: Time spent processing a fulfillment order, in seconds
     -> DataType: Histogram
     -> AggregationTemporality: Cumulative
HistogramDataPoints #0
Count: 20
Sum: 11.142740
ExplicitBounds #0: 0.050000
ExplicitBounds #1: 0.100000
ExplicitBounds #2: 0.250000
ExplicitBounds #3: 0.500000
ExplicitBounds #4: 1.000000
ExplicitBounds #5: 2.500000
ExplicitBounds #6: 5.000000
Buckets #0, Count: 2
Buckets #1, Count: 4
Buckets #2, Count: 7
Buckets #3, Count: 1
Buckets #4, Count: 3
Buckets #5, Count: 2
Buckets #6, Count: 1
Buckets #7, Count: 0

Now put this side by side with the raw Prometheus text from Step 2, which reported the same 20-request snapshot as cumulative buckets: 2, 6, 13, 14, 17, 19, 20, 20 at thresholds 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, and +Inf. Subtract each cumulative value from the one before it, and you get exactly the OpenTelemetry bucket counts above: 2 minus 0 is 2, 6 minus 2 is 4, 13 minus 6 is 7, 14 minus 13 is 1, 17 minus 14 is 3, 19 minus 17 is 2, 20 minus 19 is 1, and 20 minus 20 is 0. That is the entire conversion: Prometheus’s “how many so far” running totals become OpenTelemetry’s “how many landed in exactly this range” counts. As a sanity check, OpenTelemetry’s per-bucket counts must always sum back to the overall Count: 2 + 4 + 7 + 1 + 3 + 2 + 1 + 0 is 20, which matches.

One field is easy to misread here: AggregationTemporality: Cumulative does not mean “the buckets are cumulative.” It describes a different axis entirely, whether each data point covers the time range from the metric’s creation up to now (cumulative temporality) or only the time range since the previous report (delta temporality). Because Prometheus counters and histograms never reset and only grow for the life of the process, the receiver correctly reports this as cumulative temporality, even though, as you just proved, the bucket counts themselves are not stored cumulatively anymore.

Step 7: Inspect the Real OTLP JSON Payload

The file exporter wrote the same data as OTLP JSON to otlp-output.json, one JSON object per export batch. Pretty-print the histogram entry from the matching batch:

{
  "name": "order_processing_duration_seconds",
  "description": "Time spent processing a fulfillment order, in seconds",
  "histogram": {
    "dataPoints": [
      {
        "timeUnixNano": "1787773640630000000",
        "count": "20",
        "sum": 11.142739900038578,
        "bucketCounts": ["2", "4", "7", "1", "3", "2", "1", "0"],
        "explicitBounds": [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5]
      }
    ],
    "aggregationTemporality": 2
  }
}

This is the shape any real OTLP-speaking backend actually receives: bucketCounts and explicitBounds as parallel arrays, plus count and sum. Note aggregationTemporality: 2: the OTLP wire format encodes this field as a small integer rather than a word, and 2 is the numeric code for cumulative temporality (1 would mean delta), matching the human-readable label the debug exporter printed in Step 6.

Step 8: Understand the Metrics You Did Not Ask For

If you scroll through the Collector’s debug output, you will see more than just your one histogram. Two categories of surprise metrics show up, and both are worth recognizing rather than being confused by later.

First, the Prometheus receiver adds its own scrape-health metrics for every target: up (1 if the last scrape succeeded, 0 if it failed), scrape_duration_seconds, scrape_samples_scraped, and a couple of others. These did not come from your app; they describe the act of scraping itself, and they are genuinely useful, since up is usually the first thing worth checking when a metric mysteriously stops appearing in a backend.

Second, remember the order_processing_duration_seconds_created gauge from Step 2? It does not merge into your histogram. It becomes its own separate Gauge-type metric in the OpenTelemetry data, still carrying the _created suffix, with its value being the raw Unix creation timestamp rather than a proper timestamp field. If you are instrumenting a real application with the Python client, expect one of these stray gauges per counter and per histogram you define, quietly showing up in whatever dashboard or metric explorer you check next.

Step 9: Troubleshooting a Down Target

It helps to deliberately break something once, so you recognize the failure mode instead of guessing at it later. Stop the demo app (in its terminal, press Ctrl+C, or find and stop the process listening on port 8000), then watch the Collector’s own log:

warn  internal/transaction.go:132  Failed to scrape Prometheus endpoint
  {"error": "Get \"http://127.0.0.1:8000/metrics\": dial tcp 127.0.0.1:8000: connectex: No connection could be made because the target machine actively refused it.",
   "target_labels": "{__name__=\"up\", instance=\"127.0.0.1:8000\", job=\"order-fulfillment-demo\"}"}

And in the same batch, the up gauge for this target reports:

Metric
Descriptor:
     -> Name: up
     -> Description: The scraping was successful
     -> DataType: Gauge
NumberDataPoints #0
Value: 0.000000

This is the single most important debugging signal this pipeline gives you. Your application’s own metrics, like the histogram, simply disappear from the export entirely during an outage; the Collector still exports the handful of scrape self-metrics (including up), which is exactly what confirms the target was checked and found unreachable rather than never being scraped at all.

Restart the app:

uvicorn app:app --host 127.0.0.1 --port 8000

Within one scrape interval, up returns to 1.000000 and your histogram reappears in the export. One honest caveat worth knowing: because prometheus_client‘s default registry lives entirely in your process’s memory, restarting the app resets every counter and histogram back to zero. That is expected behavior for this pull-based, in-process design, not a bug in anything you configured; if you need history to survive a restart, that is a job for whatever system stores the scraped data downstream, not for the instrumented process itself.

Common Mistakes and Gotchas

A short list of the things most likely to trip you up, all of which you have now seen firsthand rather than just been warned about: expecting your OTLP backend to show cumulative-looking bucket numbers and being confused when they look smaller than the Prometheus values you remember; forgetting that _created gauges will clutter a metric picker and need to be filtered out or simply ignored; assuming a missing metric means a broken pipeline when it is actually just a target that failed to scrape, which is why checking up first saves time; and setting scrape_interval far below what your application can comfortably serve, which is harmless for a demo but worth tuning deliberately in production.

How to Confirm It All Works End to End

Before moving on, you should be able to walk through this sequence yourself and see every result described above: the demo app answers on port 8000 and its raw /metrics output shows cumulative le= buckets; the Collector’s startup log confirms the scrape job was added; after generating traffic, the Collector’s debug output shows a Histogram-type metric whose Buckets values are the differences between consecutive Prometheus thresholds and sum back to the overall count; the otlp-output.json file contains the same data as real OTLP JSON; and stopping the app flips up to 0 with a logged connection error, then flips back to 1 once you restart it.

Next Steps

From here, the natural next step is pointing the exporters section at a real backend instead of the terminal and a local file: the same Contrib distribution already includes otlp and otlphttp exporters that send this identical data over the network using standard OTLP transport. For production use, it is also worth adding the standard batch processor (to group data points into fewer, larger network requests) and memory_limiter (to protect the Collector itself from unbounded memory growth under load), both of which ship in the same distribution you already downloaded. If you want to go deeper on the receiver side, try adding a second static_configs target to scrape more than one application from the same Collector, which is the normal way a single Collector ends up centralizing metrics for an entire small fleet.