Tutorials on Grafana Labs

Flow by example

Tue, 14 Apr 2026 08:40:50 +0000

Flow by example

This section provides a set of step-by-step tutorials that show how to use Grafana Agent Flow.

Collect Prometheus metrics

Tue, 14 Apr 2026 08:40:50 +0000

Collect Prometheus metrics

Grafana Agent is a telemetry collector with the primary goal of moving telemetry data from one location to another. In this tutorial, you’ll set up Grafana Agent Flow.

Prerequisites

Docker

Run the example

Run the following command in a terminal window:

curl https://raw.githubusercontent.com/grafana/agent/main/docs/sources/flow/tutorials/assets/runt.sh -O && bash ./runt.sh agent.river

The runt.sh script does:

Downloads the configurations necessary for Mimir, Grafana, and Grafana Agent.
Downloads the docker image for Grafana Agent explicitly.
Runs the docker-compose up command to bring all the services up.

Allow Grafana Agent to run for two minutes, then navigate to Grafana.

This example scrapes the Grafana Agent Flow http://localhost:12345/metrics endpoint and pushes those metrics to the Mimir instance.

Navigate to http://localhost:12345/graph to view the Grafana Agent Flow UI.

Grafana Agent displays the component pipeline in a dependency graph. See Scraping component and Remote Write component for details about the components used in this configuration. Click the nodes to navigate to the associated component page. There, you can view the state, health information, and, if applicable, the debug information.

Scraping component

The prometheus.scrape component is responsible for scraping the metrics of a particular endpoint and passing them on to another component.

// prometheus.scrape is the name of the component and "default" is its label.
prometheus.scrape "default" {
    // Tell the scraper to scrape at http://localhost:12345/metrics.
    // The http:// and metrics are implied but able to be overwritten.
    targets = [{"__address__" = "localhost:12345"}]
    // Forward the scrape results to the receiver. In general,
    // Flow uses forward_to to tell which receiver to send results to.
    // The forward_to is an argument of prometheus.scrape.default and
    // the receiver is an exported field of prometheus.remote_write.prom.
    forward_to = [prometheus.remote_write.prom.receiver]
}

The prometheus.scrape "default" annotation indicates the name of the component, prometheus.scrape, and its label, default. All components must have a unique combination of name and if applicable label.

The targets attribute is an argument. targets is a list of labels that specify the target via the special key __address__. The scraper is targeting the Grafana Agent Flow /metrics endpoint. Both http and /metrics are implied but can be overridden.

The forward_to attribute is an argument that references the export of the prometheus.remote_write.prom component. This is where the scraper will send the metrics for further processing.

Remote Write component

The prometheus.remote_write component is responsible for writing the metrics to a Prometheus-compatible endpoint (Mimir).

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

Running without Docker

To try out Grafana Agent without using Docker:

Download Grafana Agent.
Set the environment variable AGENT_MODE=flow.
Run the Grafana Agent with grafana-agent run <path_to_flow_config>.

Filter Prometheus metrics

Tue, 14 Apr 2026 08:40:50 +0000

Filter Prometheus metrics

In this tutorial, you’ll add a new component prometheus.relabel using relabel.river to filter metrics. This tutorial uses the same base as Collecting Prometheus metrics.

Prerequisites

Docker

Run the example

The prometheus.relabel component is used to drop, add, or filter metrics.

Run the following:

curl https://raw.githubusercontent.com/grafana/agent/main/docs/sources/flow/tutorials/assets/runt.sh -O && bash ./runt.sh relabel.river

The runt.sh script does:

Downloads the configurations necessary for Mimir, Grafana and Grafana Agent.
Downloads the docker image for Grafana Agent explicitly.
Runs the docker-compose up command to bring all the services up.

Allow Grafana Agent to run for two minutes, then navigate to Grafana page and the service label will be there with the api_server value.

What’s happening?

The Prometheus scraper is sending the metrics to the filter.
The filter is adding a new label named service with the value api_server.
The filter is then sending metrics to the remote_write endpoint.

Update the service value

Open the relabel.river file that was downloaded and change the name of the service to api_server_v2, then run bash ./runt.sh relabel.river. Allow Grafana Agent to run for two minutes, then navigate to the Grafana page, and the new label will be updated. The old value api_server may still show up in the graph but hovering over the lines will show that that value stopped being scraped and was replaced with api_server_v2.

Chain Prometheus components

Tue, 14 Apr 2026 08:40:50 +0000

Chain Prometheus components

This tutorial shows how to use multiple-inputs.river to send data to several different locations. This tutorial uses the same base as Filtering metrics.

A new concept introduced in Flow is chaining components together in a composable pipeline. This promotes the reusability of components while offering flexibility.

Prerequisites

Docker

Run the example

Run the following

curl https://raw.githubusercontent.com/grafana/agent/main/docs/sources/flow/tutorials/assets/runt.sh -O && bash ./runt.sh multiple-inputs.river

The runt.sh script does:

Downloads the configurations necessary for Mimir, Grafana, and Grafana Agent.
Downloads the docker image for Grafana Agent explicitly.
Runs the docker-compose up command to bring all the services up.

Allow Grafana Agent to run for two minutes, then navigate to Grafana to see Grafana Agent scrape metrics. The node_exporter metrics also show up now.

There are two scrapes each sending metrics to one filter. Note the job label lists the full name of the scrape component.

Multiple outputs

prometheus.scrape "agent" {
    targets    = [{"__address__" = "localhost:12345"}]
    forward_to = [prometheus.relabel.service.receiver]
}

prometheus.exporter.unix "default" {
    set_collectors = ["cpu", "diskstats"]
}

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

prometheus.relabel "service" {
    rule {
        source_labels = ["__name__"]
        regex         = "(.+)"
        replacement   = "api_server"
        target_label  = "service"
    }
    forward_to = [prometheus.remote_write.prom.receiver]
}

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

In the Flow block, prometheus.relabel.service is being forwarded metrics from two sources prometheus.scrape.agent and prometheus.exporter.unix.default. This allows for a single relabel component to be used with any number of inputs.

Adding another relabel

In multiple-input.river add a new prometheus.relabel component that adds a version label with the value of v2 to all metrics after the prometheus.relabel.service.