Menu

This is documentation for the next version of Alloy. For the latest stable release, go to the latest version.

Documentationbreadcrumb arrow Grafana Alloybreadcrumb arrow Referencebreadcrumb arrow Configuration blocksbreadcrumb arrow foreach
Experimental

foreach

EXPERIMENTAL: This is an experimental feature. Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement. The stability.level flag must be set to experimental to use the feature.

The foreach block runs a separate pipeline for each item inside a list.

Usage

alloy 
foreach "<LABEL>" {
  collection = [...]
  var        = "<VAR_NAME>"
  template {
    ...
  }
}

Arguments

You can use the following arguments with foreach:

NameTypeDescriptionDefaultRequired
collectionlist(any)A list of items to loop over.yes
varstringName of the variable referring to the current item in the collection.yes
enable_metricsboolWhether to expose debug metrics in the Alloy /metrics endpoint.falseno

The items in the collection list can be of any type type, such as a bool, a string, a list, or a map.

Warning

Setting enable_metrics to true when collection has lots of elements may cause a large number of metrics to appear on the Alloy /metric endpoint.

Blocks

You can use the following blocks with foreach:

BlockDescriptionRequired
templateA component pipeline to run.yes

template

The template block contains the definition of Alloy components which will be ran for every item in the collection. The contents of the block look like a normal Alloy configuration file, except that you can use the keyword defined in var to refer to the current item in the collection.

Components inside the template block can use exports of components defined outside of the foreach block. However, components outside of the foreach cannot use exports from components defined inside the template block of a foreach.

Example

The following example shows you how to run Prometheus exporters dynamically on service discovery targets.

prometheus.exporter.* components often require the address of one particular instance being monitored. For example, prometheus.exporter.redis has a redis_addr attribute for the Redis instance under observation. On the other hand, discovery.* components such as discovery.kubernetes output a list of targets such as this:

You can use a foreach to loop over each target and start a separate component pipeline for it. The following example configuration shows how a prometheus.exporter.redis instance is started for each Redis instance discovered by discovery.kubernetes. Additional Kubernetes labels from discovery.kubernetes are also added to the metrics created by prometheus.exporter.redis.

alloy 
discovery.kubernetes "default" {
    role = "pod"
}

discovery.relabel "redis" {
    targets = discovery.kubernetes.default.targets

    // Remove all targets except the Redis ones.
    rule {
        source_labels = ["__meta_kubernetes_pod_container_name"]
        regex         = "redis-cont"
        action        = "keep"
    }
}

// Collect metrics for each Redis instance.
foreach "redis" {
    collection = discovery.relabel.redis.output
    var        = "each"

    template {
        prometheus.exporter.redis "default" {
            // This is the "__address__" label from discovery.kubernetes.
            redis_addr = each["__address__"]
        }

        prometheus.scrape "default" {
            targets    = prometheus.exporter.redis.default.targets
            forward_to = [prometheus.relabel.default.receiver]
        }

        // Add labels from discovery.kubernetes.
        prometheus.relabel "default" {
            rule {
                replacement  = each["__meta_kubernetes_namespace"]
                target_label = "k8s_namespace"
                action       = "replace"
            }

            rule {
                replacement  = each["__meta_kubernetes_pod_container_name"]
                target_label = "k8s_pod_container_name"
                action       = "replace"
            }

            forward_to = [prometheus.remote_write.mimir.receiver]
        }
    }
}

prometheus.remote_write "mimir" {
    endpoint {
        url = "https://prometheus-xxx.grafana.net/api/prom/push"

        basic_auth {
            username = sys.env("<PROMETHEUS_USERNAME>")
            password = sys.env("<GRAFANA_CLOUD_API_KEY>")
        }
    }
}

Replace the following:

  • <PROMETHEUS_USERNAME>: Your Prometheus username.
  • <GRAFANA_CLOUD_API_KEY>: Your Grafana Cloud API key.