Skip to content

Commit

Permalink
Replace relrefs with docrefs in Agent tutorials (#5578)
Browse files Browse the repository at this point in the history 
* Update relrefs collect prom components

* Update relrefs in filtering metrics

* Update relrefs in chaining topic

* Update links to assets
  • Loading branch information
@clayton-cornell
clayton-cornell authored Oct 24, 2023
1 parent 10cf125 commit 97f1013
Show file tree
Hide file tree
Showing 3 changed files with 58 additions and 20 deletions.
17 changes: 13 additions & 4 deletions docs/sources/flow/tutorials/chaining.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ weight: 400

# Chain Prometheus components

This tutorial shows how to use [multiple-inputs.river](/docs/agent/latest/flow/tutorials/assets/flow_configs/multiple-inputs.river) to send data to several different locations. This tutorial uses the same base as [Filtering metrics]({{< relref "./filtering-metrics" >}}).
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.

Expand All @@ -31,11 +31,11 @@ curl https://raw.githubusercontent.com/grafana/agent/main/docs/sources/flow/tuto

The `runt.sh` script does:

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

Allow the Grafana Agent to run for two minutes, then navigate to [Grafana](http://localhost:3000/explore?orgId=1&left=%5B%22now-1h%22,%22now%22,%22Mimir%22,%7B%22refId%22:%22A%22,%22instant%22:true,%22range%22:true,%22exemplar%22:true,%22expr%22:%22agent_build_info%7B%7D%22%7D%5D) to see the Agent scrape metrics. The [node_exporter](http://localhost:3000/explore?orgId=1&left=%5B%22now-1h%22,%22now%22,%22Mimir%22,%7B%22refId%22:%22A%22,%22instant%22:true,%22range%22:true,%22exemplar%22:true,%22expr%22:%22node_cpu_seconds_total%22%7D%5D) metrics also show up now.
Allow Grafana Agent to run for two minutes, then navigate to [Grafana][] to see the 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.

Expand Down Expand Up @@ -73,10 +73,19 @@ prometheus.remote_write "prom" {
}
```

In the above 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.
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`.

![Add a new label with the value v2](/media/docs/agent/screenshot-grafana-agent-chaining-scrape-v2.png)

[multiple-inputs.river]: https://grafana.com/docs/agent/<AGENT_VERSION>/flow/tutorials/assets/flow_configs/multiple-inputs.river
[Grafana]: http://localhost:3000/explore?orgId=1&left=%5B%22now-1h%22,%22now%22,%22Mimir%22,%7B%22refId%22:%22A%22,%22instant%22:true,%22range%22:true,%22exemplar%22:true,%22expr%22:%22agent_build_info%7B%7D%22%7D%5D
[node_exporter]: http://localhost:3000/explore?orgId=1&left=%5B%22now-1h%22,%22now%22,%22Mimir%22,%7B%22refId%22:%22A%22,%22instant%22:true,%22range%22:true,%22exemplar%22:true,%22expr%22:%22node_cpu_seconds_total%22%7D%5D

{{% docs/reference %}}
[Filtering metrics]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/tutorials/filtering-metrics.md"
[Filtering metrics]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/tutorials/filtering-metrics.md"
{{% /docs/reference %}}
33 changes: 25 additions & 8 deletions docs/sources/flow/tutorials/collecting-prometheus-metrics.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Grafana Agent is a telemetry collector with the primary goal of moving telemetry

## Prerequisites

* [Docker](https://www.docker.com/products/docker-desktop)
* [Docker][]

## Run the example

Expand All @@ -29,11 +29,11 @@ curl https://raw.githubusercontent.com/grafana/agent/main/docs/sources/flow/tuto

The `runt.sh` script does:

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

Allow the Grafana Agent to run for two minutes, then navigate to [Grafana](http://localhost:3000/explore?orgId=1&left=%5B%22now-1h%22,%22now%22,%22Mimir%22,%7B%22refId%22:%22A%22,%22instant%22:true,%22range%22:true,%22exemplar%22:true,%22expr%22:%22agent_build_info%7B%7D%22%7D%5D).
Allow Grafana Agent to run for two minutes, then navigate to [Grafana][].

![Dashboard showing agent_build_info metrics](/media/docs/agent/screenshot-grafana-agent-collect-metrics-build-info.png)

Expand All @@ -43,14 +43,14 @@ Navigate to `http://localhost:12345/graph` to view the Grafana Agent Flow UI.

![The Grafana Agent UI](/media/docs/agent/screenshot-grafana-agent-collect-metrics-graph.png)

The Agent displays the component pipeline in a dependency graph. See [Scraping component](#scraping-component) and [Remote Write component](#remote-write-component) for details about the components used in this configuration.
The Agent displays the component pipeline in a dependency graph. See [Scraping component](#scraping-component) and [Remote Write component](#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.

![Component information](/media/docs/agent/screenshot-grafana-agent-collect-metrics-comp-info.png)

## Scraping component

The [`prometheus.scrape`]({{< relref "../reference/components/prometheus.scrape.md" >}}) component is responsible for scraping the metrics of a particular endpoint and passing them on to another component.
The [`prometheus.scrape`][prometheus.scrape] component is responsible for scraping the metrics of a particular endpoint and passing them on to another component.

```river
// prometheus.scrape is the name of the component and "default" is its label.
Expand All @@ -68,13 +68,13 @@ prometheus.scrape "default" {

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]({{< relref "../concepts/configuration_language#attributes" >}}) is an [argument]({{< relref "../concepts/components" >}}). `targets` is a list of labels that specify the target via the special key `__address__`. The scraper is targeting the Agent's `/metrics` endpoint. Both `http` and `/metrics` are implied but can be overridden.
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 Agent's `/metrics` endpoint. Both `http` and `/metrics` are implied but can be overridden.

The `forward_to` attribute is an argument that references the [export]({{< relref "../concepts/components" >}}) of the `prometheus.remote_write.prom` component. This is where the scraper will send the metrics for further processing.
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`]({{< relref "../reference/components/prometheus.remote_write.md" >}}) component is responsible for writing the metrics to a Prometheus-compatible endpoint (Mimir).
The [`prometheus.remote_write`][prometheus.remote_write] component is responsible for writing the metrics to a Prometheus-compatible endpoint (Mimir).

```river
prometheus.remote_write "prom" {
Expand All @@ -90,3 +90,20 @@ To try out the Grafana Agent without using Docker:
1. Download the Grafana Agent.
1. Set the environment variable `AGENT_MODE=flow`.
1. Run the agent with `grafana-agent run <path_to_flow_config>`.


[Docker]: https://www.docker.com/products/docker-desktop
[Grafana]: http://localhost:3000/explore?orgId=1&left=%5B%22now-1h%22,%22now%22,%22Mimir%22,%7B%22refId%22:%22A%22,%22instant%22:true,%22range%22:true,%22exemplar%22:true,%22expr%22:%22agent_build_info%7B%7D%22%7D%5D

{{% docs/reference %}}
[prometheus.scrape]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/prometheus.scrape.md"
[prometheus.scrape]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/components/prometheus.scrape.md"
[attribute]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/concepts/configuration_language.md#attributes"
[attribute]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/concepts/configuration_language.md#attributes"
[argument]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/concepts/components"
[argument]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/concepts/components"
[export]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/concepts/components"
[export]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/concepts/components"
[prometheus.remote_write]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/prometheus.remote_write.md"
[prometheus.remote_write]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/components/prometheus.remote_write.md"
{{% /docs/reference %}}
28 changes: 20 additions & 8 deletions docs/sources/flow/tutorials/filtering-metrics.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,11 @@ weight: 300

# Filter Prometheus metrics

In this tutorial, you'll add a new component [prometheus.relabel]({{< relref "../reference/components/prometheus.relabel.md" >}}) using [relabel.river](/docs/agent/latest/flow/tutorials/assets/flow_configs/relabel.river) to filter metrics. This tutorial uses the same base as [Collecting Prometheus metrics]({{< relref "./collecting-prometheus-metrics.md" >}}).
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](https://www.docker.com/products/docker-desktop)
* [Docker][]

## Run the example

Expand All @@ -31,23 +31,35 @@ curl https://raw.githubusercontent.com/grafana/agent/main/docs/sources/flow/tuto

The `runt.sh` script does:

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


Allow Grafana Agent to run for two minutes, then navigate to [Grafana](http://localhost:3000/explore?orgId=1&left=%5B%22now-1h%22,%22now%22,%22Mimir%22,%7B%22refId%22:%22A%22,%22instant%22:true,%22range%22:true,%22exemplar%22:true,%22expr%22:%22agent_build_info%7B%7D%22%7D%5D) page and the `service` label will be there with the `api_server` value.
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.

![Dashboard showing api_server](/media/docs/agent/screenshot-grafana-agent-filtering-metrics-filter.png)

## What's happening?

1. The Prometheus scraper is sending the metrics to the filter.
1. The filter is adding a new label named `service` with the value `api_server`.
1. The filter is then sending metrics to the remote_write endpoint.
1. 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 the Grafana Agent to run for two minutes, then navigate to [Grafana](http://localhost:3000/explore?orgId=1&left=%5B%22now-1h%22,%22now%22,%22Mimir%22,%7B%22refId%22:%22A%22,%22instant%22:true,%22range%22:true,%22exemplar%22:true,%22expr%22:%22agent_build_info%7B%7D%22%7D%5D) 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`.
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`.

![Updated dashboard showing api_server_v2](/media/docs/agent/screenshot-grafana-agent-filtering-metrics-transition.png)


[Docker]: https://www.docker.com/products/docker-desktop
[Grafana]: http://localhost:3000/explore?orgId=1&left=%5B%22now-1h%22,%22now%22,%22Mimir%22,%7B%22refId%22:%22A%22,%22instant%22:true,%22range%22:true,%22exemplar%22:true,%22expr%22:%22agent_build_info%7B%7D%22%7D%5D
[relabel.river]: https://grafana.com/docs/agent/<AGENT_VERSION>/flow/tutorials/assets/flow_configs/relabel.river

{{% docs/reference %}}
[prometheus.relabel]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/prometheus.relabel.md"
[prometheus.relabel]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/components/prometheus.relabel.md"
[Collecting Prometheus metrics]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/tutorials/collecting-prometheus-metrics.md"
[Collecting Prometheus metrics]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/tutorials/collecting-prometheus-metrics.md"
{{% /docs/reference %}}

0 comments on commit 97f1013

Please sign in to comment.