Referencing component exports

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

Referencing component exports

Referencing exports enables River to configure and connect components dynamically using expressions. While components can work in isolation, they’re more useful when one component’s behavior and data flow are bound to the exports of another, building a dependency relationship between the two.

Such references can only appear as part of another component’s arguments or a configuration block’s fields. Components can’t reference themselves.

Using references

You build references by combining the component’s name, label, and named export with dots.

For example, you can reference the contents of a file exported by the local.file component labeled target as local.file.target.content. Similarly, a prometheus.remote_write component instance labeled onprem exposes its receiver for metrics on prometheus.remote_write.onprem.receiver.

The following example shows some references.

river
local.file "target" {
  filename = "/etc/agent/target"
}

prometheus.scrape "default" {
  targets    = [{ "__address__" = local.file.target.content }]
  forward_to = [prometheus.remote_write.onprem.receiver]
}

prometheus.remote_write "onprem" {
  endpoint {
    url = "http://prometheus:9009/api/prom/push"
  }
}

In the preceding example, you wired together a very simple pipeline by writing a few River expressions.

Flow of example pipeline

After the value is resolved, it must match the type of the attribute it is assigned to. While you can only configure attributes using the basic River types, the exports of components can take on special internal River types, such as Secrets or Capsules, which expose different functionality.