# Prometheus Receiver

<!-- status autogenerated section -->
| Status        |           |
| ------------- |-----------|
| Stability     | [beta]: metrics   |
| Distributions | [core], [contrib], [aws], [grafana], [observiq], [splunk], [sumo] |
| Issues        | [![Open issues](https://img.shields.io/github/issues-search/open-telemetry/opentelemetry-collector-contrib?query=is%3Aissue%20is%3Aopen%20label%3Areceiver%2Fprometheus%20&label=open&color=orange&logo=opentelemetry)](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues?q=is%3Aopen+is%3Aissue+label%3Areceiver%2Fprometheus) [![Closed issues](https://img.shields.io/github/issues-search/open-telemetry/opentelemetry-collector-contrib?query=is%3Aissue%20is%3Aclosed%20label%3Areceiver%2Fprometheus%20&label=closed&color=blue&logo=opentelemetry)](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues?q=is%3Aclosed+is%3Aissue+label%3Areceiver%2Fprometheus) |
| [Code Owners](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/CONTRIBUTING.md#becoming-a-code-owner)    | [@Aneurysm9](https://www.github.com/Aneurysm9), [@dashpole](https://www.github.com/dashpole) |

[beta]: https://github.com/open-telemetry/opentelemetry-collector#beta
[core]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol
[contrib]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib
[aws]: https://github.com/aws-observability/aws-otel-collector
[grafana]: https://github.com/grafana/agent
[observiq]: https://github.com/observIQ/observiq-otel-collector
[splunk]: https://github.com/signalfx/splunk-otel-collector
[sumo]: https://github.com/SumoLogic/sumologic-otel-collector
<!-- end autogenerated section -->

Receives metric data in [Prometheus](https://prometheus.io/) format. 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 is a concern:

* Collector cannot auto-scale the scraping yet when multiple replicas of the
  collector is 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.
* The Prometheus receiver is a stateful component.

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


## 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
prometheus --config.file=prom.yaml
```

**Feature gates**:

- `receiver.prometheusreceiver.UseCreatedMetric`: Start time for Summary, Histogram 
  and Sum metrics can be retrieved from `_created` metrics. Currently, this behaviour
  is disabled by default. To enable it, use the following feature gate option:

```shell
"--feature-gates=receiver.prometheusreceiver.UseCreatedMetric"
```

- `report_extra_scrape_metrics`: Extra Prometheus scrape metrics can be reported by setting this parameter to `true`

You can copy and paste that same configuration under:

```yaml
receivers:
  prometheus:
    config:
```

For example:

```yaml
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
```

The prometheus receiver also supports additional top-level options:

- **trim_metric_suffixes**: [**Experimental**] When set to true, this enables trimming unit and some counter type suffixes from metric names. For example, it would cause `singing_duration_seconds_total` to be trimmed to `singing_duration`. This can be useful when trying to restore the original metric names used in OpenTelemetry instrumentation. Defaults to false.
- **use_start_time_metric**: When set to true, this enables retrieving the start time of all counter metrics from the process_start_time_seconds metric. This is only correct if all counters on that endpoint started after the process start time, and the process is the only actor exporting the metric after the process started. It should not be used in "exporters" which export counters that may have started before the process itself. Use only if you know what you are doing, as this may result in incorrect rate calculations. Defaults to false.
- **start_time_metric_regex**: The regular expression for the start time metric, and is only applied when use_start_time_metric is enabled.  Defaults to process_start_time_seconds.

For example,

```yaml
receivers:
    prometheus:
      trim_metric_suffixes: true
      use_start_time_metric: true
      start_time_metric_regex: foo_bar_.*
      config:
        scrape_configs:
          - job_name: 'otel-collector'
            scrape_interval: 5s
            static_configs:
              - targets: ['0.0.0.0:8888']
```

## 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
receivers:
  prometheus:
    target_allocator:
      endpoint: http://my-targetallocator-service
      interval: 30s
      collector_id: collector-1
```
## 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.