> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Prometheus

> OpenTelemetry receiver for Prometheus

# Prometheus Receiver

![Status](https://img.shields.io/badge/status-beta-yellow)

**Available in:** `core`, `contrib`, `k8s`

**Maintainers:** [@Aneurysm9](https://github.com/Aneurysm9), [@dashpole](https://github.com/dashpole), [@ArthurSens](https://github.com/ArthurSens), [@krajorama](https://github.com/krajorama)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/prometheusreceiver)

## Supported Telemetry

![Metrics](https://img.shields.io/badge/metrics-beta-green)

## Overview

See the [Design](DESIGN.md) for additional information on this receiver.

## ⚠️ Warning

Note: This component is currently work in progress. It has several limitations
and please don't use it if the following limitations are a concern:

* Collector cannot auto-scale the scraping yet when multiple replicas of the
  collector are run.
* When running multiple replicas of the collector with the same config, it will
  scrape the targets multiple times.
* Users need to configure each replica with different scraping configuration
  if they want to manually shard the scraping.

## Unsupported features

The Prometheus receiver is meant to minimally be a drop-in replacement for Prometheus. However,
there are advanced features of Prometheus that we don't support and thus explicitly will return
an error for if the receiver's configuration YAML/code contains any of the following

* [x] alert\_config.alertmanagers
* [x] alert\_config.relabel\_configs
* [x] remote\_read
* [x] remote\_write
* [x] rule\_files

## External Dependencies

This receiver uses the scrape manager and parser implementation from
[`prometheus/prometheus`](https://github.com/prometheus/prometheus). Compatibility with Prometheus scrape behavior follows the version pinned in [`go.mod`](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/prometheusreceiver/go.mod).

Supported scrape protocol and exposition formats are those accepted by the Prometheus scrape configuration:

* `PrometheusProto`
* `OpenMetricsText1.0.0`
* `OpenMetricsText0.0.1`
* `PrometheusText1.0.0`
* `PrometheusText0.0.4`

If `fallback_scrape_protocol` is not set, the receiver defaults it to `PrometheusText0.0.4` for compatibility with targets that do not return a proper content type.

For native histogram details and protocol requirements, see [Prometheus native histograms](#prometheus-native-histograms).

## Getting Started

This receiver is a drop-in replacement for getting Prometheus to scrape your
services. It supports [the full set of Prometheus configuration in `scrape_config`][sc],
including service discovery. Just like you would write in a YAML configuration
file before starting Prometheus, such as with:

**Note**: Since the collector configuration supports env variable substitution
`$` characters in your prometheus configuration are interpreted as environment
variables.  If you want to use \$ characters in your prometheus configuration,
you must escape them using `$$`.

```shell theme={null}
prometheus --config.file=prom.yaml
```

You can copy and paste that same configuration under the `config` attribute:

```yaml theme={null}
receivers:
    prometheus:
      config:
        scrape_configs:
          - job_name: 'otel-collector'
            scrape_interval: 5s
            static_configs:
              - targets: ['0.0.0.0:8888']
          - job_name: k8s
            kubernetes_sd_configs:
            - role: pod
            relabel_configs:
            - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
              regex: "true"
              action: keep
            metric_relabel_configs:
            - source_labels: [__name__]
              regex: "(request_duration_seconds.*|response_duration_seconds.*)"
              action: keep
```

## Configuration

| Field                         | Default | Description                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config`                      |         | Embedded [Prometheus scrape configuration](https://prometheus.io/docs/prometheus/latest/configuration/configuration/) (`global`, `scrape_configs`, `scrape_config_files`, and related sections). Uses the same YAML structure as Prometheus; any field you omit picks up the default documented there for that setting. Service discovery and relabeling behave like Prometheus. |
| `target_allocator`            |         | Optional Target Allocator client configuration used to fetch dynamically assigned scrape targets. See [OpenTelemetry Operator](#opentelemetry-operator).                                                                                                                                                                                                                         |
| `trim_metric_suffixes`        | `false` | \[**Experimental**] Trims unit and some counter type suffixes from metric names, for example `singing_duration_seconds_total` -> `singing_duration`. Useful when trying to restore metric names closer to OpenTelemetry instrumentation.                                                                                                                                         |
| `api_server`                  |         | Optional nested block for a local Prometheus agent-mode API server (debugging targets, configuration, and service discovery). See [Prometheus API Server](#prometheus-api-server).                                                                                                                                                                                               |
| `scrape_on_shutdown`          | `false` | Enables a final scrape before the receiver closes. This final scrape ignores the configured scrape interval.                                                                                                                                                                                                                                                                     |
| `discovery_reload_on_startup` | `false` | Enables discovering targets immediately on start up as opposed to waiting for the configured interval before initializing the scrape pools.                                                                                                                                                                                                                                      |
| `initial_scrape_offset`       | `0s`    | Adds a fixed delay before the initial scrape of targets. This duration is applied on top of the receiver's internal load balancing offset. It avoids readiness races and backend rate limits immediately after startup.                                                                                                                                                          |

At least one of `config.scrape_configs`, `config.scrape_config_files`, or `target_allocator` must be set.

Example configuration:

```yaml theme={null}
receivers:
    prometheus:
      trim_metric_suffixes: true
      config:
        scrape_configs:
          - job_name: 'otel-collector'
            scrape_interval: 5s
            static_configs:
              - targets: ['0.0.0.0:8888']
```

## Complete Configuration Example

The following example demonstrates a complete end-to-end configuration showing how to use the Prometheus receiver with processors and exporters in a service pipeline:

```yaml theme={null}
receivers:
  prometheus:
    config:
      scrape_configs:
        - job_name: 'my-service'
          scrape_interval: 5s
          static_configs:
            - targets: ['localhost:9090']
          # Filter metrics to keep only those matching the regex pattern
          metric_relabel_configs:
            - source_labels: [__name__]
              regex: 'http_request_duration_seconds.*'
              action: keep

processors:
  resource:
    attributes:
      # Note: service.name is automatically set by the prometheus receiver from job_name
      - key: deployment.environment
        value: production
        action: upsert

exporters:
  otlp_grpc:
    endpoint: otel-collector:4317
    tls:
      insecure: false
      # For local testing only you may set `insecure: true`, but avoid this in production.
    sending_queue:
      batch:
        timeout: 10s
        send_batch_size: 1000
  prometheus_remote_write:
    endpoint: https://prometheus:9090/api/v1/write
    sending_queue:
      batch:
        timeout: 10s
        send_batch_size: 1000

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [resource]
      exporters: [otlp_grpc, prometheus_remote_write]
```

This configuration:

* Scrapes metrics from a service running on `localhost:9090` every 5 seconds
* Filters metrics to keep only those matching `http_request_duration_seconds.*` using `metric_relabel_configs`
* Adds resource attributes (`deployment.environment`) to all metrics (note: `service.name` is automatically set from the job name)
* Uses exporter-level batching via `sending_queue.batch` to improve efficiency when multiple scrapes occur
* Exports metrics to both an OTLP endpoint and Prometheus remote write endpoint

## Prometheus native histograms

Native histograms are a data type in Prometheus, for more information see the [specification](https://prometheus.io/docs/specs/native_histograms/).

The Prometheus receiver automatically converts native histograms to OpenTelemetry exponential histograms. To enable scraping and ingestion of native histograms, you need to configure two things in your Prometheus scrape config:

1. **Enable native histogram scraping**: Set `scrape_native_histograms: true` (globally or per-job)
2. **Use the protobuf scrape protocol**: Include `PrometheusProto` in `scrape_protocols` (required until Prometheus supports native histograms over text formats)

```yaml theme={null}
receivers:
  prometheus:
    config:
      global:
        # Required: Include PrometheusProto to scrape native histograms
        scrape_protocols: [ PrometheusProto, OpenMetricsText1.0.0, OpenMetricsText0.0.1, PrometheusText0.0.4 ]
        # Enable native histogram scraping globally
        scrape_native_histograms: true
      scrape_configs:
        - job_name: 'my-app'
          # Per-job setting takes precedence over global
          # scrape_native_histograms: true
          static_configs:
            - targets: ['localhost:8080']
```

This feature applies to the most common integer counter histograms; gauge histograms are dropped.
In case a metric has both the conventional (aka classic) buckets and also native histogram buckets, only the native histogram buckets will be
taken into account to create the corresponding exponential histogram. To scrape the classic buckets instead use the
[scrape option](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) `always_scrape_classic_histograms`.

## OpenTelemetry Operator

Additional to this static job definitions this receiver allows to query a list of jobs from the
OpenTelemetryOperators TargetAllocator or a compatible endpoint.

```yaml theme={null}
receivers:
  prometheus:
    target_allocator:
      endpoint: http://my-targetallocator-service
      interval: 30s
      collector_id: collector-1
```

The `target_allocator` section embeds the full [confighttp client configuration][confighttp].

[confighttp]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/config/confighttp/README.md#client-configuration

[confighttp-server]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/config/confighttp/README.md#server-configuration

## Exemplars

This receiver accepts exemplars coming in Prometheus format and converts it to OTLP format.

1. Value is expected to be received in `float64` format
2. Timestamp is expected to be received in `ms`
3. Labels with key `span_id` in prometheus exemplars are set as OTLP `span id` and labels with key `trace_id` are set as `trace id`
4. Rest of the labels are copied as it is to OTLP format

[sc]: https://github.com/prometheus/prometheus/blob/v2.28.1/docs/configuration/configuration.md#scrape_config

## Resource and Scope

This receiver drops the `target_info` prometheus metric, if present, and uses attributes on
that metric to populate the OpenTelemetry Resource.

It drops `otel_scope_name` and `otel_scope_version` labels, if present, from metrics, and uses them to populate
the OpenTelemetry Instrumentation Scope name and version. It drops the `otel_scope_info` metric,
and uses attributes (other than `otel_scope_name` and `otel_scope_version`) to populate Scope
Attributes.

### Resource Attribute Mapping

In addition to attributes derived from `target_info`, this receiver maps scrape target metadata to OpenTelemetry resource attributes. These mappings follow OpenTelemetry semantic conventions.

For the current detailed mapping list, see [`resource_attribute_mapping.md`](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/prometheusreceiver/resource_attribute_mapping.md).

We are incrementally adding mappings for additional Prometheus service discovery labels and
welcome contributions aligned with OpenTelemetry semantic conventions.

## Scrape Metadata Metrics

Scrape metadata metrics are automatically generated by Prometheus during scraping and are
emitted alongside the target metrics.

For the full list of scrape metadata metrics and their semantics, refer to the Prometheus
documentation on [automatically generated labels and time series](https://prometheus.io/docs/concepts/jobs_instances/#automatically-generated-labels-and-time-series).

When `extra_scrape_metrics` is enabled in Prometheus `global` or `scrape_config`,
additional scrape metadata metrics are emitted as described in the same Prometheus
documentation.

## Prometheus API Server

The Prometheus API server hosts information about active targets, service discovery, metrics, and the rendered Prometheus config. Set `api_server.enabled: true` to expose these debugging endpoints. The server is disabled by default.

| Field             | Type                                                                                          | Default                                          | Description                                                         |
| ----------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------- |
| `enabled`         | bool                                                                                          | `false`                                          | Whether the API server is enabled.                                  |
| `max_connections` | int                                                                                           | `512`                                            | Maximum number of simultaneous HTTP connections the server accepts. |
| `server_config`   | [confighttp.ServerConfig](https://pkg.go.dev/go.opentelemetry.io/collector/config/confighttp) | endpoint: `127.0.0.1:9090`, read\_timeout: `10m` | HTTP server settings including endpoint, TLS, CORS, and timeouts.   |

```yaml theme={null}
receivers:
  prometheus:
    api_server:
      enabled: true
      max_connections: 512
      server_config:
        endpoint: "127.0.0.1:9090"
```

The API server hosts the same paths as the Prometheus agent-mode API. These include:

* [/api/v1/targets](https://prometheus.io/docs/prometheus/latest/querying/api/#targets)
* [/api/v1/targets/metadata](https://prometheus.io/docs/prometheus/latest/querying/api/#querying-target-metadata)
* [/api/v1/status/config](https://prometheus.io/docs/prometheus/latest/querying/api/#config)
* /api/v1/scrape\_pools
* /metrics

More info about querying `/api/v1/` and the data format that is returned can be found in the [Prometheus documentation](https://prometheus.io/docs/prometheus/latest/querying/api/).

## Feature gates

See [documentation.md](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/prometheusreceiver/documentation.md) for the complete list of feature gates supported by this receiver.

Feature gates can be enabled using the `--feature-gates` flag:

```shell theme={null}
"--feature-gates=<feature-gate>"
```

## Benchmark Results

Current Prometheus receiver benchmark results are published on the [Collector Benchmarks page](https://open-telemetry.github.io/opentelemetry-collector-contrib/benchmarks/loadtests/). The table below links directly to the current Prometheus receiver charts by scenario and metric type.

| Scenario                           | CPU                                                                                                                                                 | Memory                                                                                                                                          |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Baseline, 1k metrics               | [CPU](https://open-telemetry.github.io/opentelemetry-collector-contrib/benchmarks/loadtests/#prometheusreceiver-baseline-1k-cpu-percentage)         | [Memory](https://open-telemetry.github.io/opentelemetry-collector-contrib/benchmarks/loadtests/#prometheusreceiver-baseline-1k-ram-mib)         |
| Baseline, 10k metrics              | [CPU](https://open-telemetry.github.io/opentelemetry-collector-contrib/benchmarks/loadtests/#prometheusreceiver-baseline-10k-cpu-percentage)        | [Memory](https://open-telemetry.github.io/opentelemetry-collector-contrib/benchmarks/loadtests/#prometheusreceiver-baseline-10k-ram-mib)        |
| Native histograms, 10k metrics     | [CPU](https://open-telemetry.github.io/opentelemetry-collector-contrib/benchmarks/loadtests/#prometheusreceiver-nativehistogram-10k-cpu-percentage) | [Memory](https://open-telemetry.github.io/opentelemetry-collector-contrib/benchmarks/loadtests/#prometheusreceiver-nativehistogram-10k-ram-mib) |
| `target_info` enabled, 10k metrics | [CPU](https://open-telemetry.github.io/opentelemetry-collector-contrib/benchmarks/loadtests/#prometheusreceiver-withtargetinfo-10k-cpu-percentage)  | [Memory](https://open-telemetry.github.io/opentelemetry-collector-contrib/benchmarks/loadtests/#prometheusreceiver-withtargetinfo-10k-ram-mib)  |

## Configuration

### config.yaml (testdata)

```yaml theme={null}
prometheus:
prometheus/customname:
  trim_metric_suffixes: true
  target_allocator:
    endpoint: http://my-targetallocator-service
    interval: 30s
    collector_id: collector-1
    # imported struct from the Prometheus code base. Can be used optionally to configure the jobs as seen in the docs
    # https://prometheus.io/docs/prometheus/latest/configuration/configuration/#http_sd_config
    http_sd_config:
      refresh_interval: 60s
      basic_auth:
        username: "prometheus"
        password: "changeme"
    http_scrape_config:
      basic_auth:
        username: "scrape_prometheus"
        password: "scrape_changeme"
  config:
    scrape_configs:
      - job_name: 'demo'
        scrape_interval: 5s
```

### config.yaml (testdata)

```yaml theme={null}
config:
  scrape_configs:
    - job_name: 'kong'
      scrape_interval: 1s
      static_configs:
        - targets:
            - "localhost:18001"
```

***

*Last generated: 2026-07-06*