---
title: "Alloy Health integration | Grafana Cloud documentation"
description: "Learn about Alloy Health Grafana Cloud integration."
---

# Alloy Health integration for Grafana Cloud

The Alloy health integration lets you monitor metrics and logs of Alloy instances.

It can be seen as an extended version of the Alloy Collector monitoring app available under the Connections menu, providing deeper insights over your Alloy deployment environment, including dashboards for Alloy clusters, OTel specific components, resource utilization, logs and more, together with bundled alerts.

This integration includes 14 useful alerts and 8 pre-built dashboards to help monitor and visualize Alloy Health metrics and logs.

## Before you begin

This integration relies on metrics emitted by Grafana Alloy. See the following sections for details.

## Install Alloy Health integration for Grafana Cloud

1. In your Grafana Cloud stack, click **Connections** in the left-hand menu.
2. Find **Alloy Health** and click its tile to open the integration.
3. Review the prerequisites in the **Configuration Details** tab and set up Grafana Alloy to send Alloy Health metrics and logs to your Grafana Cloud instance.
4. Click **Install** to add this integration’s pre-built dashboards and alerts to your Grafana Cloud instance, and you can start monitoring your Alloy Health setup.

## Configuration snippets for Grafana Alloy

### Simple mode

These snippets are configured to scrape a single Grafana alloy node running locally with default ports and log paths.

**Manually** copy and append the following snippets into your Grafana Alloy configuration file.

You can remove any component named `alloy_check` from your alloy configuration file, to avoid duplication of metrics.

### Integrations snippets

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

```alloy
prometheus.exporter.self "integrations_alloy_health" { }

discovery.relabel "integrations_alloy_health" {
  targets = prometheus.exporter.self.integrations_alloy_health.targets

  rule {
    replacement = constants.hostname
    target_label  = "instance"
  }

  rule {
    target_label = "job"
    replacement  = "integrations/alloy"
  }
}

prometheus.scrape "integrations_alloy_health" {
  targets    = discovery.relabel.integrations_alloy_health.output
  forward_to = [prometheus.remote_write.metrics_service.receiver]
  job_name   = "integrations/alloy"
}
```

### Logs snippets

#### darwin

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

```alloy
logging {
  write_to = [loki.process.logs_integrations_integrations_alloy_health.receiver]
}

loki.process "logs_integrations_integrations_alloy_health" {
  forward_to = [loki.relabel.logs_integrations_integrations_alloy_health.receiver]

  stage.regex {
    expression = "(level=(?P<log_level>[\\s]*debug|warn|info|error))"
  }
  
  stage.labels {
    values = {
      level = "log_level",
    }
  }
}

loki.relabel "logs_integrations_integrations_alloy_health" {

  forward_to = [loki.write.grafana_cloud_loki.receiver]

  rule {
    replacement = constants.hostname
    target_label  = "instance"
  }

  rule {
    target_label = "job"
    replacement  = "integrations/alloy"
  }
}
```

#### linux

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

```alloy
logging {
  write_to = [loki.process.logs_integrations_integrations_alloy_health.receiver]
}

loki.process "logs_integrations_integrations_alloy_health" {
  forward_to = [loki.relabel.logs_integrations_integrations_alloy_health.receiver]

  stage.regex {
    expression = "(level=(?P<log_level>[\\s]*debug|warn|info|error))"
  }
  
  stage.labels {
    values = {
      level = "log_level",
    }
  }
}

loki.relabel "logs_integrations_integrations_alloy_health" {

  forward_to = [loki.write.grafana_cloud_loki.receiver]

  rule {
    replacement = constants.hostname
    target_label  = "instance"
  }

  rule {
    target_label = "job"
    replacement  = "integrations/alloy"
  }
}
```

#### windows

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

```alloy
logging {
  write_to = [loki.process.logs_integrations_integrations_alloy_health.receiver]
}

loki.process "logs_integrations_integrations_alloy_health" {
  forward_to = [loki.relabel.logs_integrations_integrations_alloy_health.receiver]

  stage.regex {
    expression = "(level=(?P<log_level>[\\s]*debug|warn|info|error))"
  }
  
  stage.labels {
    values = {
      level = "log_level",
    }
  }
}

loki.relabel "logs_integrations_integrations_alloy_health" {

  forward_to = [loki.write.grafana_cloud_loki.receiver]

  rule {
    replacement = constants.hostname
    target_label  = "instance"
  }

  rule {
    target_label = "job"
    replacement  = "integrations/alloy"
  }
}
```

### Advanced mode

The following snippets provide examples to guide you through the configuration process.

**Manually** copy and append the snippets to your alloy configuration file, then follow subsequent instructions.

You can remove any component named `alloy_check` from your alloy configuration file, to avoid duplication of metrics.

### Advanced integrations snippets

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

```alloy
prometheus.exporter.self "integrations_alloy_health" { }

discovery.relabel "integrations_alloy_health" {
  targets = prometheus.exporter.self.integrations_alloy_health.targets

  rule {
    replacement = constants.hostname
    target_label  = "instance"
  }

  rule {
    target_label = "job"
    replacement  = "integrations/alloy"
  }
}

prometheus.scrape "integrations_alloy_health" {
  targets    = discovery.relabel.integrations_alloy_health.output
  forward_to = [prometheus.remote_write.metrics_service.receiver]
  job_name   = "integrations/alloy"
}
```

This integrations uses the [prometheus.exporter.self](/docs/alloy/latest/reference/components/prometheus.exporter.self/) component to generate metrics from the alloy instance itself.

For the full array of configuration options, refer to the [prometheus.exporter.self](/docs/alloy/latest/reference/components/prometheus.exporter.self/) component reference documentation.

This exporter must be linked with a [discovery.relabel](/docs/alloy/latest/reference/components/discovery.relabel/) component to apply the necessary relabeling rules.

Configure the following properties within the `discovery.relabel` component:

- `instance` label: `constants.hostname` sets the `instance` label to your Grafana Alloy server hostname. If that is not suitable, change it to a value uniquely identifies this alloy instance.

If you are running Grafana Alloy in [cluster mode](/docs/alloy/latest/concepts/clustering/), beware that you may need to change `instance` label as multiple instances might be running in your server.

You can then scrape them by including each `discovery.relabel` under `targets` within the [prometheus.scrape](/docs/alloy/latest/reference/components/prometheus.scrape/) component.

### Advanced logs snippets

#### darwin

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

```alloy
logging {
  write_to = [loki.process.logs_integrations_integrations_alloy_health.receiver]
}

loki.process "logs_integrations_integrations_alloy_health" {
  forward_to = [loki.relabel.logs_integrations_integrations_alloy_health.receiver]

  stage.regex {
    expression = "(level=(?P<log_level>[\\s]*debug|warn|info|error))"
  }
  
  stage.labels {
    values = {
      level = "log_level",
    }
  }
}

loki.relabel "logs_integrations_integrations_alloy_health" {

  forward_to = [loki.write.grafana_cloud_loki.receiver]

  rule {
    replacement = constants.hostname
    target_label  = "instance"
  }

  rule {
    target_label = "job"
    replacement  = "integrations/alloy"
  }
}
```

This integration uses the [logging](/docs/grafana-cloud/send-data/alloy/reference/config-blocks/logging/) configuration block to collect logs internally and direct it to a [loki.process](/docs/alloy/latest/reference/components/loki.process) and a [loki.relabel](/docs/alloy/latest/reference/components/loki.relabel) component to set necessary labels.

Beware that the `logging` configuration block is also used to set the logging level and format you want alloy to use. If you already have such a block in you configuration file, just include the `write_to` property to it, as just one should be present.

If you have installed a single Grafana Alloy instance in your server, it should be ready to use. Otherwise, configure the following property within the `loki.relabel` component:

- `instance` label: `constants.hostname` sets the `instance` label to your Grafana Alloy server hostname. If that is not suitable, change it to a value uniquely identifies this alloy instance.

If you are running Grafana Alloy in [cluster mode](/docs/alloy/latest/concepts/clustering/), beware that you may need to change `instance` label as multiple instances might be running in your server.

You can check the documentation linked above for the full array of options for each component.

#### linux

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

```alloy
logging {
  write_to = [loki.process.logs_integrations_integrations_alloy_health.receiver]
}

loki.process "logs_integrations_integrations_alloy_health" {
  forward_to = [loki.relabel.logs_integrations_integrations_alloy_health.receiver]

  stage.regex {
    expression = "(level=(?P<log_level>[\\s]*debug|warn|info|error))"
  }
  
  stage.labels {
    values = {
      level = "log_level",
    }
  }
}

loki.relabel "logs_integrations_integrations_alloy_health" {

  forward_to = [loki.write.grafana_cloud_loki.receiver]

  rule {
    replacement = constants.hostname
    target_label  = "instance"
  }

  rule {
    target_label = "job"
    replacement  = "integrations/alloy"
  }
}
```

This integration uses the [logging](/docs/grafana-cloud/send-data/alloy/reference/config-blocks/logging/) configuration block to collect logs internally and direct it to a [loki.process](/docs/alloy/latest/reference/components/loki.process) and a [loki.relabel](/docs/alloy/latest/reference/components/loki.relabel) component to set necessary labels.

Beware that the `logging` configuration block is also used to set the logging level and format you want alloy to use. If you already have such a block in you configuration file, just include the `write_to` property to it, as just one should be present.

If you have installed a single Grafana Alloy instance in your server, it should be ready to use. Otherwise, configure the following property within the `loki.relabel` component:

- `instance` label: `constants.hostname` sets the `instance` label to your Grafana Alloy server hostname. If that is not suitable, change it to a value uniquely identifies this alloy instance.

If you are running Grafana Alloy in [cluster mode](/docs/alloy/latest/concepts/clustering/), beware that you may need to change `instance` label as multiple instances might be running in your server.

You can check the documentation linked above for the full array of options for each component.

#### windows

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

```alloy
logging {
  write_to = [loki.process.logs_integrations_integrations_alloy_health.receiver]
}

loki.process "logs_integrations_integrations_alloy_health" {
  forward_to = [loki.relabel.logs_integrations_integrations_alloy_health.receiver]

  stage.regex {
    expression = "(level=(?P<log_level>[\\s]*debug|warn|info|error))"
  }
  
  stage.labels {
    values = {
      level = "log_level",
    }
  }
}

loki.relabel "logs_integrations_integrations_alloy_health" {

  forward_to = [loki.write.grafana_cloud_loki.receiver]

  rule {
    replacement = constants.hostname
    target_label  = "instance"
  }

  rule {
    target_label = "job"
    replacement  = "integrations/alloy"
  }
}
```

This integration uses the [logging](/docs/grafana-cloud/send-data/alloy/reference/config-blocks/logging/) configuration block to collect logs internally and direct it to a [loki.process](/docs/alloy/latest/reference/components/loki.process) and a [loki.relabel](/docs/alloy/latest/reference/components/loki.relabel) component to set necessary labels.

Beware that the `logging` configuration block is also used to set the logging level and format you want alloy to use. If you already have such a block in you configuration file, just include the `write_to` property to it, as just one should be present.

If you have installed a single Grafana Alloy instance in your server, it should be ready to use. Otherwise, configure the following property within the `loki.relabel` component:

- `instance` label: `constants.hostname` sets the `instance` label to your Grafana Alloy server hostname. If that is not suitable, change it to a value uniquely identifies this alloy instance.

If you are running Grafana Alloy in [cluster mode](/docs/alloy/latest/concepts/clustering/), beware that you may need to change `instance` label as multiple instances might be running in your server.

You can check the documentation linked above for the full array of options for each component.

## Kubernetes instructions

Instructions for Kubernetes

### Before you begin with Kubernetes

**Please note**: These instructions assume the use of the [Kubernetes Monitoring Helm chart](https://github.com/grafana/k8s-monitoring-helm)

### Configuration snippets for Kubernetes Helm chart

The following snippets provide examples to guide you through the configuration process.

To scrape your Alloy Health instances, **manually** modify your Kubernetes Monitoring Helm chart with these configuration snippets.

Replace any values between the angle brackets `<>` in the provided snippets with your desired configuration values.

#### Metrics snippets

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

```alloy
integrations:
alloy:
    instances:
    - name: <your_alloy_instance_name>
        labelSelectors:
        <alloy-pod-label>: <alloy-pod-label-value>
```

## Dashboards

The Alloy Health integration installs the following dashboards in your Grafana Cloud instance to help monitor your system.

- Alloy / Cluster Node
- Alloy / Cluster Overview
- Alloy / Controller
- Alloy / Logs Overview
- Alloy / Loki Components
- Alloy / OpenTelemetry
- Alloy / Prometheus Components
- Alloy / Resources

**Alloy resources usage overview**

**Prometheus related components overview**

**Overall components overview**

## Alerts

The Alloy Health integration includes the following useful alerts:

**alloy\_clustering**

Expand table

| Alert                       | Description                                                                              |
|-----------------------------|------------------------------------------------------------------------------------------|
| ClusterNotConverging        | Warning: Cluster is not converging.                                                      |
| ClusterNodeCountMismatch    | Warning: Nodes report different number of peers vs. the count of observed Alloy metrics. |
| ClusterNodeUnhealthy        | Warning: Cluster unhealthy.                                                              |
| ClusterNodeNameConflict     | Warning: Cluster Node Name Conflict.                                                     |
| ClusterNodeStuckTerminating | Warning: Cluster node stuck in Terminating state.                                        |
| ClusterConfigurationDrift   | Warning: Cluster configuration drifting.                                                 |

**alloy\_controller**

Expand table

| Alert                    | Description                                         |
|--------------------------|-----------------------------------------------------|
| SlowComponentEvaluations | Warning: Component evaluations are taking too long. |
| UnhealthyComponents      | Warning: Unhealthy components detected.             |

**alloy\_otelcol**

Expand table

| Alert                         | Description                                                                      |
|-------------------------------|----------------------------------------------------------------------------------|
| OtelcolReceiverRefusedSpans   | Warning: The receiver pushing spans to the pipeline success rate is below 95%.   |
| OtelcolReceiverRefusedMetrics | Warning: The receiver pushing metrics to the pipeline success rate is below 95%. |
| OtelcolReceiverRefusedLogs    | Warning: The receiver pushing logs to the pipeline success rate is below 95%.    |
| OtelcolExporterFailedSpans    | Warning: The exporter sending spans success rate is below 95%.                   |
| OtelcolExporterFailedMetrics  | Warning: The exporter sending metrics success rate is below 95%.                 |
| OtelcolExporterFailedLogs     | Warning: The exporter sending logs success rate is below 95%.                    |

## Metrics

The most important metrics provided by the Alloy Health integration, which are used on the pre-built dashboards and Prometheus alerts, are as follows:

- alloy\_build\_info
- alloy\_component\_controller\_running\_components
- alloy\_component\_dependencies\_wait\_seconds
- alloy\_component\_dependencies\_wait\_seconds\_bucket
- alloy\_component\_evaluation\_seconds
- alloy\_component\_evaluation\_seconds\_bucket
- alloy\_component\_evaluation\_seconds\_count
- alloy\_component\_evaluation\_seconds\_sum
- alloy\_component\_evaluation\_slow\_seconds
- alloy\_config\_hash
- alloy\_resources\_machine\_rx\_bytes\_total
- alloy\_resources\_machine\_tx\_bytes\_total
- alloy\_resources\_process\_cpu\_seconds\_total
- alloy\_resources\_process\_resident\_memory\_bytes
- cluster\_minimum\_size
- cluster\_node\_gossip\_health\_score
- cluster\_node\_gossip\_proto\_version
- cluster\_node\_gossip\_received\_events\_total
- cluster\_node\_info
- cluster\_node\_lamport\_time
- cluster\_node\_peers
- cluster\_node\_update\_observers
- cluster\_transport\_rx\_bytes\_total
- cluster\_transport\_rx\_packet\_queue\_length
- cluster\_transport\_rx\_packets\_failed\_total
- cluster\_transport\_rx\_packets\_total
- cluster\_transport\_stream\_rx\_bytes\_total
- cluster\_transport\_stream\_rx\_packets\_failed\_total
- cluster\_transport\_stream\_rx\_packets\_total
- cluster\_transport\_stream\_tx\_bytes\_total
- cluster\_transport\_stream\_tx\_packets\_failed\_total
- cluster\_transport\_stream\_tx\_packets\_total
- cluster\_transport\_streams
- cluster\_transport\_tx\_bytes\_total
- cluster\_transport\_tx\_packet\_queue\_length
- cluster\_transport\_tx\_packets\_failed\_total
- cluster\_transport\_tx\_packets\_total
- go\_gc\_duration\_seconds\_count
- go\_goroutines
- go\_memstats\_heap\_inuse\_bytes
- http\_client\_duration\_milliseconds\_bucket
- http\_server\_duration\_milliseconds\_bucket
- loki\_source\_file\_files\_active\_total
- loki\_source\_file\_read\_lines\_total
- loki\_source\_journal\_target\_lines\_total
- loki\_write\_dropped\_bytes\_total
- loki\_write\_request\_duration\_seconds\_bucket
- loki\_write\_sent\_bytes\_total
- otelcol\_exporter\_send\_failed\_log\_records\_total
- otelcol\_exporter\_send\_failed\_metric\_points\_total
- otelcol\_exporter\_send\_failed\_spans\_total
- otelcol\_exporter\_sent\_log\_records\_total
- otelcol\_exporter\_sent\_metric\_points\_total
- otelcol\_exporter\_sent\_spans\_total
- otelcol\_processor\_batch\_batch\_send\_size\_bucket
- otelcol\_processor\_batch\_metadata\_cardinality
- otelcol\_processor\_batch\_timeout\_trigger\_send\_total
- otelcol\_receiver\_accepted\_log\_records\_total
- otelcol\_receiver\_accepted\_metric\_points\_total
- otelcol\_receiver\_accepted\_spans\_total
- otelcol\_receiver\_refused\_log\_records\_total
- otelcol\_receiver\_refused\_metric\_points\_total
- otelcol\_receiver\_refused\_spans\_total
- prometheus\_remote\_storage\_bytes\_total
- prometheus\_remote\_storage\_highest\_timestamp\_in\_seconds
- prometheus\_remote\_storage\_metadata\_bytes\_total
- prometheus\_remote\_storage\_queue\_highest\_sent\_timestamp\_seconds
- prometheus\_remote\_storage\_samples\_failed\_total
- prometheus\_remote\_storage\_samples\_retried\_total
- prometheus\_remote\_storage\_samples\_total
- prometheus\_remote\_storage\_sent\_batch\_duration\_seconds\_bucket
- prometheus\_remote\_storage\_sent\_batch\_duration\_seconds\_count
- prometheus\_remote\_storage\_sent\_batch\_duration\_seconds\_sum
- prometheus\_remote\_storage\_shards
- prometheus\_remote\_storage\_shards\_max
- prometheus\_remote\_storage\_shards\_min
- prometheus\_remote\_write\_wal\_samples\_appended\_total
- prometheus\_remote\_write\_wal\_storage\_active\_series
- rpc\_client\_duration\_milliseconds\_bucket
- rpc\_server\_duration\_milliseconds\_bucket
- scrape\_duration\_seconds
- up

## Changelog

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

```md
# 1.1.1 - January 2026

*  Add loki_* metrics to prometheus relabel rule to populate loki component dashboards

# 1.1.0 - October 2025

* Update mixin to the latest version
    * Update OTEL support for logs and metrics
    * Remove explicit requirement for otel proto service types

# 1.0.2 - November 2024

* Update mixin to the latest version 
    * Include `cluster_name` label into cluster related alerts to avoid false positives.
    * Otel metric renames

# 1.0.1 - November 2024

* Update status panel check queries

# 1.0.0 - July 2024

* Initial release
```

## Cost

By connecting your Alloy Health instance to Grafana Cloud, you might incur charges. To view information on the number of active series that your Grafana Cloud account uses for metrics included in each Cloud tier, see [Active series and dpm usage](/docs/grafana-cloud/fundamentals/active-series-and-dpm/) and [Cloud tier pricing](/products/cloud/pricing/).