Prometheus Receiver

Available in: core, contrib, k8s Maintainers: @Aneurysm9, @dashpole, @ArthurSens, @krajorama Source: opentelemetry-collector-contrib

Supported Telemetry

Overview

See the Design 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

External Dependencies

This receiver uses the scrape manager and parser implementation from prometheus/prometheus. Compatibility with Prometheus scrape behavior follows the version pinned in 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.

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, 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 $$.

prometheus --config.file=prom.yaml

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

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 (`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.
`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.
`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:

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:

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. 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:

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

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 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.

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.

Exemplars

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

Value is expected to be received in float64 format
Timestamp is expected to be received in ms
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
Rest of the labels are copied as it is to OTLP format

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. 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. 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	endpoint: `127.0.0.1:9090`, read_timeout: `10m`	HTTP server settings including endpoint, TLS, CORS, and timeouts.

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:

More info about querying /api/v1/ and the data format that is returned can be found in the Prometheus documentation.

Feature gates

See documentation.md for the complete list of feature gates supported by this receiver. Feature gates can be enabled using the --feature-gates flag:

"--feature-gates=<feature-gate>"

Benchmark Results

Current Prometheus receiver benchmark results are published on the Collector Benchmarks page. The table below links directly to the current Prometheus receiver charts by scenario and metric type.

Scenario	CPU	Memory
Baseline, 1k metrics	CPU	Memory
Baseline, 10k metrics	CPU	Memory
Native histograms, 10k metrics	CPU	Memory
`target_info` enabled, 10k metrics	CPU	Memory

Configuration

config.yaml (testdata)

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)

config:
  scrape_configs:
    - job_name: 'kong'
      scrape_interval: 1s
      static_configs:
        - targets:
            - "localhost:18001"

Last generated: 2026-08-24

​Prometheus Receiver

​Supported Telemetry

​Overview

​⚠️ Warning

​Unsupported features

​External Dependencies

​Getting Started

​Configuration

​Complete Configuration Example

​Prometheus native histograms

​OpenTelemetry Operator

​Exemplars

​Resource and Scope

​Resource Attribute Mapping

​Scrape Metadata Metrics

​Prometheus API Server

​Feature gates

​Benchmark Results

​Configuration

​config.yaml (testdata)

​config.yaml (testdata)

Prometheus Receiver

Supported Telemetry

Overview

⚠️ Warning

Unsupported features

External Dependencies

Getting Started

Configuration

Complete Configuration Example

Prometheus native histograms

OpenTelemetry Operator

Exemplars

Resource and Scope

Resource Attribute Mapping

Scrape Metadata Metrics

Prometheus API Server

Feature gates

Benchmark Results

Configuration

config.yaml (testdata)

config.yaml (testdata)