---
title: "prometheus.receive_http | Grafana Alloy documentation"
description: "Learn about prometheus.receive_http"
---

# `prometheus.receive_http`

`prometheus.receive_http` listens for HTTP requests containing Prometheus metric samples and forwards them to other components capable of receiving metrics.

The HTTP API exposed is compatible with [Prometheus `remote_write` API](https://prometheus.io/docs/prometheus/latest/querying/api/#remote-write-receiver). This means that other [`prometheus.remote_write`](../prometheus.remote_write/) components can be used as a client and send requests to `prometheus.receive_http` which enables using Alloy as a proxy for Prometheus metrics.

## Usage

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
prometheus.receive_http "<LABEL>" {
  http {
    listen_address = "<LISTEN_ADDRESS>"
    listen_port = <PORT>
  }
  forward_to = <RECEIVER_LIST>
}
```

The component starts an HTTP server supporting the following endpoint:

- `POST /api/v1/metrics/write`: Sends metrics to the component, which in turn is forwarded to the receivers as configured in `forward_to` argument. The request format must be compatible with the [Prometheus remote\_write API](https://prometheus.io/docs/prometheus/latest/querying/api/#remote-write-receiver) and can use either the v1 or v2 format. One way to send valid requests to this component is to use another Alloy with a [`prometheus.remote_write`](../prometheus.remote_write/) component.

## Arguments

You can use the following arguments with `prometheus.receive_http`:

Expand table

| Name                                      | Type                    | Description                                           | Default                       | Required |
|-------------------------------------------|-------------------------|-------------------------------------------------------|-------------------------------|----------|
| `forward_to`                              | `list(MetricsReceiver)` | List of receivers to send metrics to.                 |                               | yes      |
| `accepted_remote_write_protobuf_messages` | `list(string)`          | Accepted remote write protobuf message types.         | `["prometheus.WriteRequest"]` | no       |
| `append_metadata`                         | `bool`                  | Pass metric metadata to downstream components.        | `false`                       | no       |
| `enable_type_and_unit_labels`             | `bool`                  | Add the metric type and unit as labels to the metric. | `false`                       | no       |

> **EXPERIMENTAL**: The `append_metadata`, `enable_type_and_unit_labels`, and using `"io.prometheus.write.v2.Request"` in `accepted_remote_write_protobuf_messages` are [experimental](/docs/release-life-cycle/) features.
> 
> The `append_metadata` and `enable_type_and_unit_labels` arguments only apply to remote write v2 payloads and only when metadata is included in those payloads. Enabling support for remote write v2 payloads requires that `"io.prometheus.write.v2.Request"` is included in `accepted_remote_write_protobuf_messages`. Remote write v1 payloads (`accepted_remote_write_protobuf_messages = ["prometheus.WriteRequest"]`) cannot support these features.
> 
> Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental feature, you must set the `stability.level` [flag](/docs/alloy/latest/reference/cli/run/) to `experimental`.

## Blocks

You can use the following blocks with `prometheus.receive_http`:

No valid configuration blocks found.

### `http`

The `http` block configures the HTTP server.

You can use the following arguments to configure the `http` block. Any omitted fields take their default values.

Expand table

| Name                   | Type       | Description                                                                                                      | Default  | Required |
|------------------------|------------|------------------------------------------------------------------------------------------------------------------|----------|----------|
| `conn_limit`           | `int`      | Maximum number of simultaneous HTTP connections. Defaults to no limit.                                           | `0`      | no       |
| `listen_address`       | `string`   | Network address on which the server listens for new connections. Defaults to accepting all incoming connections. | `""`     | no       |
| `listen_port`          | `int`      | Port number on which the server listens for new connections.                                                     | `8080`   | no       |
| `server_idle_timeout`  | `duration` | Idle timeout for HTTP server.                                                                                    | `"120s"` | no       |
| `server_read_timeout`  | `duration` | Read timeout for HTTP server.                                                                                    | `"30s"`  | no       |
| `server_write_timeout` | `duration` | Write timeout for HTTP server.                                                                                   | `"30s"`  | no       |

### `tls`

The `tls` block configures TLS for the HTTP server.

Expand table

| Name               | Type     | Description                                                      | Default          | Required |
|--------------------|----------|------------------------------------------------------------------|------------------|----------|
| `cert_pem`         | `string` | PEM data of the server TLS certificate.                          | `""`             | no       |
| `cert_file`        | `string` | Path to the server TLS certificate on disk.                      | `""`             | no       |
| `client_auth_type` | `string` | Client authentication to use.                                    | `"NoClientCert"` | no       |
| `client_ca_file`   | `string` | Path to the client CA file on disk to validate requests against. | `""`             | no       |
| `client_ca_pem`    | `string` | PEM data of the client CA to validate requests against.          | `""`             | no       |
| `key_file`         | `string` | Path to the server TLS key on disk.                              | `""`             | no       |
| `key_pem`          | `secret` | PEM data of the server TLS key.                                  | `""`             | no       |

The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:

- `cert_pem` and `cert_file`
- `key_pem` and `key_file`

When configuring client authentication, both the client certificate (using `cert_pem` or `cert_file`) and the client key (using `key_pem` or `key_file`) must be provided.

## Exported fields

`prometheus.receive_http` doesn’t export any fields.

## Component health

`prometheus.receive_http` is reported as unhealthy if it’s given an invalid configuration.

## Debug metrics

The following are some of the metrics that are exposed when this component is used. The metrics include labels such as `status_code` where relevant, which can be used to measure request success rates.

- `prometheus_fanout_latency` (histogram): Write latency for sending metrics to other components.
- `prometheus_forwarded_samples_total` (counter): Total number of samples sent to downstream components.
- `prometheus_receive_http_request_duration_seconds` (histogram): Time (in seconds) spent serving HTTP requests.
- `prometheus_receive_http_request_message_bytes` (histogram): Size (in bytes) of messages received in the request.
- `prometheus_receive_http_response_message_bytes` (histogram): Size (in bytes) of messages sent in response.
- `prometheus_receive_http_tcp_connections` (gauge): Current number of accepted TCP connections.

## Example

### Receive metrics over HTTP

The following example creates a `prometheus.receive_http` component which starts an HTTP server listening on port `9999` on all network interfaces. The server receives metrics and forwards them to a `prometheus.remote_write` component which writes these metrics to the specified HTTP endpoint.

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
// Receives metrics over HTTP
prometheus.receive_http "api" {
  http {
    listen_address = "0.0.0.0"
    listen_port = 9999
  }
  forward_to = [prometheus.remote_write.local.receiver]
}

// Send metrics to a locally running Mimir.
prometheus.remote_write "local" {
  endpoint {
    url = "http://mimir:9009/api/v1/push"

    basic_auth {
      username = "example-user"
      password = "example-password"
    }
  }
}
```

### Proxy metrics

To send metrics to the `prometheus.receive_http` component defined in the previous example, another Alloy can run with the following configuration:

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
// Collects metrics of localhost:12345
prometheus.scrape "self" {
  targets = [
    {"__address__" = "localhost:12345", "job" = "alloy"},
  ]
  forward_to = [prometheus.remote_write.local.receiver]
}

// Writes metrics to localhost:9999/api/v1/metrics/write - e.g. served by
// the prometheus.receive_http component from the example above.
prometheus.remote_write "local" {
  endpoint {
    url = "http://localhost:9999/api/v1/metrics/write"
  }
}
```

## Technical details

`prometheus.receive_http` uses [snappy](https://en.wikipedia.org/wiki/Snappy_%28compression%29) for compression.

## Compatible components

`prometheus.receive_http` can accept arguments from the following components:

- Components that export [Prometheus `MetricsReceiver`](../../../compatibility/#prometheus-metricsreceiver-exporters)

> Note
> 
> Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.