Caution

Grafana Agent has reached End-of-Life (EOL) on November 1, 2025. Agent is no longer receiving vendor support and will no longer receive security or bug fixes. Current users of Agent Static mode, Agent Flow mode, and Agent Operator should proceed with migrating to Grafana Alloy. If you have already migrated to Alloy, no further action is required. 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.

Documentationbreadcrumb arrow Grafana Agentbreadcrumb arrow Flow modebreadcrumb arrow Get startedbreadcrumb arrow Distribute Prometheus metrics scrape load
Open source

Distribute Prometheus metrics scrape load

A good predictor for the size of an agent deployment is the number of Prometheus targets each agent scrapes. Clustering with target auto-distribution allows a fleet of agents to work together to dynamically distribute their scrape load, providing high-availability.

Note

Clustering is a beta feature. Beta features are subject to breaking changes and may be replaced with equivalent functionality that covers the same use case.

Before you begin

Steps

To distribute Prometheus metrics scrape load with clustering:

  1. Add the following block to all prometheus.scrape components which should use auto-distribution:

    Alloy 
    clustering {
  enabled = true
}

  2. Restart or reload agents for them to use the new configuration.

  3. Validate that auto-distribution is functioning:

    1. Using the UI on each agent, navigate to the details page for one of the prometheus.scrape components you modified.

    2. Compare the Debug Info sections between two different agents to ensure that they are not scraping the same sets of targets.