Skip to main content

​
Prometheus Receiver

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

​
Supported Telemetry

Metrics

​
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
  • alert_config.alertmanagers
  • alert_config.relabel_configs
  • remote_read
  • remote_write
  • rule_files

​
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

FieldDefaultDescription
configEmbedded 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_allocatorOptional Target Allocator client configuration used to fetch dynamically assigned scrape targets. See OpenTelemetry Operator.
trim_metric_suffixesfalse[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_serverOptional nested block for a local Prometheus agent-mode API server (debugging targets, configuration, and service discovery). See Prometheus API Server.
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:
  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)
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.
  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

​
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 can be enabled to host info about the Prometheus targets, config, service discovery, and metrics. The server_config can be specified using the OpenTelemetry confighttp package. An example configuration would be: 
receivers:
  prometheus:
    api_server:
      enabled: true
      server_config:
        endpoint: "localhost: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.
ScenarioCPUMemory
Baseline, 1k metricsCPUMemory
Baseline, 10k metricsCPUMemory
Native histograms, 10k metricsCPUMemory
target_info enabled, 10k metricsCPUMemory

​
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-06-01