Menu

Caution

Grafana Alloy is the new name for our distribution of the OTel collector. Grafana Agent has been deprecated and is in Long-Term Support (LTS) through October 31, 2025. Grafana Agent will reach an End-of-Life (EOL) on November 1, 2025. Read more about why we recommend migrating to Grafana Alloy.

Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Open source

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. This means that other prometheus.remote_write components can be used as a client and send requests to prometheus.receive_http which enables using the Agent as a proxy for prometheus metrics.

Usage

river
prometheus.receive_http "LABEL" {
  http {
    listen_address = "LISTEN_ADDRESS"
    listen_port = PORT 
  }
  forward_to = RECEIVER_LIST
}

The component will start an HTTP server supporting the following endpoint:

  • POST /api/v1/metrics/write - send metrics to the component, which in turn will be forwarded to the receivers as configured in forward_to argument. The request format must match that of Prometheus remote_write API. One way to send valid requests to this component is to use another Grafana Agent with a prometheus.remote_write component.

Arguments

prometheus.receive_http supports the following arguments:

NameTypeDescriptionDefaultRequired
forward_tolist(receiver)List of receivers to send metrics to.yes

Blocks

The following blocks are supported inside the definition of prometheus.receive_http:

HierarchyNameDescriptionRequired
httphttpConfigures the HTTP server that receives requests.no

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.

NameTypeDescriptionDefaultRequired
conn_limitintMaximum number of simultaneous HTTP connections. Defaults to no limit.0no
listen_addressstringNetwork address on which the server listens for new connections. Defaults to accepting all incoming connections.""no
listen_portintPort number on which the server listens for new connections.8080no
server_idle_timeoutdurationIdle timeout for HTTP server."120s"no
server_read_timeoutdurationRead timeout for HTTP server."30s"no
server_write_timeoutdurationWrite timeout for HTTP server."30s"no

Exported fields

prometheus.receive_http does not export any fields.

Component health

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

Debug metrics

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

  • 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.
  • agent_prometheus_fanout_latency (histogram): Write latency for sending metrics to other components.
  • agent_prometheus_forwarded_samples_total (counter): Total number of samples sent to downstream components.

Example

Receiving metrics over HTTP

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

river
// 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"
    }
  }
}

Proxying metrics

In order to send metrics to the prometheus.receive_http component defined in the previous example, another Grafana Agent can run with the following configuration:

river
// Collects metrics of localhost:12345
prometheus.scrape "agent_self" {
  targets = [
    {"__address__" = "localhost:12345", "job" = "agent"},
  ]
  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 for compression.