Skip to content

Commit 105b451

Browse files
ptodevptodev
committed
Add a "When to use Flow" section to the docs
1 parent ea7b005 commit 105b451

File tree

3 files changed

+158
-0
lines changed

3 files changed

+158
-0
lines changed

‎docs/sources/flow/when-to-use-flow/_index.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
description: Learn how to Flow compares to other offerings
3+
menuTitle: When to use Flow
4+
title: When to use Flow
5+
weight: 25
6+
---
7+
8+
# When to use Flow
9+
10+
Grafana Agent Flow allows you to process telemetry in a variety of formats, natively:
11+
* [OTLP][] (`otelcol` components)
12+
* Prometheus (`prometheus` components)
13+
* Loki (`loki` components)
14+
* Pyroscope (`pyroscope` components)
15+
16+
Native processing of telemetry could lead to higher efficiency and ease of use.
17+
18+
It is also possible from switch to one format to another. For example:
19+
* `otelcol.exporter.prometheus` converts OTLP metrics to Prometheus logs.
20+
* `otelcol.receiver.prometheus` converts Prometheus metrics to OTLP metrics.
21+
* `otelcol.exporter.loki` converts OTLP logs to Loki logs.
22+
* `otelcol.receiver.loki` converts Loki logs to OTLP logs.
23+
* `otelcol.connector.spanlogs` converts OTLP spans to OTLP logs.
24+
* `otelcol.connector.spanmetrics` converts OTLP spans to OTLP metrics.
25+
26+
There are even Flow components which do not deal with telemetry. For example, `mimir.rules.kubernetes`
27+
can be used to configure a Mimir instance.
28+
29+
The articles in this section describe in more detail how Flow compares to similar products:
30+
31+
{{< section >}}
32+
33+
[OTLP]: https://grafana.com/docs/grafana-cloud/send-data/otlp/

‎docs/sources/flow/when-to-use-flow/opentelemetry-collector.md

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
description: Learn how to Flow compares to the OpenTelemetry Collector
3+
menuTitle: OpenTelemetry Collector
4+
title: OpenTelemetry Collector
5+
weight: 100
6+
---
7+
8+
# Comparing Flow with the OpenTelemetry Collector
9+
10+
## Which one of the two should you use?
11+
12+
Flow may be a better choice if:
13+
* You prefer River syntax over YAML.
14+
* You would like to collect "profile" telemetry - Flow can do this via Pyroscope components.
15+
* You would like to process Prometheus or Loki telemetry without converting it to OTLP.
16+
17+
The Collector may be a better choice if:
18+
* You are already using the Collector, and do not need any of the features of Flow.
19+
* You prefer YAML syntax over River.
20+
21+
Below you can find more details on similarities and differences between the Collector and Flow.
22+
23+
## Similarities
24+
25+
### Many Collector components are available in Flow
26+
27+
Flow contains many of the components available inside the Collector:
28+
* For example, the OTLP exporter is available as `otelcol.exporter.otlp`.
29+
* The Grafana Agent development team is actively working on adding more of the Collector's components to Flow.
30+
* If a Flow user needs a Collector feature to be made available in the Agent, the Agent development team could work on implementing it.
31+
32+
### Similar performance when processing OpenTelemetry signals natively
33+
34+
Most of Flow's `otelcol` components are just thin wrappers over a Collector component.
35+
Hence, the CPU and memory performance of Flow is similar.
36+
37+
## Differences
38+
39+
### Configuration language
40+
41+
Collector is configured using yaml, whereas Flow is configured using River.
42+
43+
#### Example - coalesce
44+
45+
One of River's main advantages is its standard library. It contains handy functions such as coalesce,
46+
which could be used to retrieve the first argument which is not null or empty:
47+
48+
```river
49+
```
50+
51+
### Modularity
52+
53+
The Agent configuration is more flexible, modular, and allows for more opportunities to chain components together in a pipeline.
54+
55+
#### Example - retrieving data from a file
56+
57+
Let's say you would like to use OAuth2 authentication in the Collector. If you need to retrieve `client_id`
58+
or `client_secret` from a file, then you would have to use the `client_id_file` or `client_secret_file` config parameters.
59+
60+
```yaml
61+
```
62+
63+
In the Agent, you'd use `otelcol.auth.oauth2` with the normal `client_id` and `client_secret` parameters,
64+
and you would setup another component which retrieves those from a `local.file` component.
65+
66+
```river
67+
```
68+
69+
Moreover, the string could also come from a `remote.s3`, `remote.vault`, or `remote.http`.
70+
This gives Flow users lots of flexibility because strings coming out of those components
71+
could be used for any parameter, in any component which requires a string - not just for
72+
a `client_id` for OAuth2.
73+
74+
```river
75+
```
76+
77+
### Flow can process Prometheus signals natively
78+
79+
Collector needs to convert Prometheus signals to the OTLP format in order to process them.
80+
Flow, on the other hand, can process those signals natively using components such as `prometheus.relabel`, `prometheus.relabel`, and `prometheus.remote_write`.
81+
This could lead to better performance and ease of use.
82+
83+
### Flow documentation is consistent and structured
84+
85+
Flow components tend to be documented in a more consistent way than Collector components.
86+
87+
### Some Collector features are not available in the Agent and vice-versa
88+
89+
Agent doesn't have all the components which the Collector has. However, the Grafana Agent development team is working on
90+
adding new components all the time and we would be happy to add new components which Flow users need.
91+
92+
### Flow supports "profile" telemetry signals
93+
94+
OpenTelemetry currently does not support "profile" signals. Flow supports them through components such as `pyroscope.scrape` and `pyroscope.ebpf`.
95+
96+
### Flow is usually a few versions of OpenTelemetry behind
97+
98+
Flow imports OpenTelemetry libraries as a dependency. Generally, a given version of Flow might use OpenTelemetry libraries
99+
which are older by 1, 2, or even 4 months. This is usually not a problem and the Agent development team could schedule an
100+
upgrade of the Agent's OpenTelemetry dependencies outside of the usual upgrade cycle if it is important to a user.

‎docs/sources/flow/when-to-use-flow/prometheus-agent.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
description: Learn how to Flow compares to the Prometheus Agent Mode
3+
menuTitle: Prometheus Agent Mode
4+
title: Prometheus Agent Mode
5+
weight: 200
6+
---
7+
8+
## Should you use Flow or the Prometheus Agent Mode?
9+
10+
Grafana Agent Flow supports all of the [features][prom-agent-mode-blog] of the [Prometheus Agent Mode][prom-agent-mode-flag] via components such as:
11+
* `discovery.http`
12+
* `discovery.relabel`
13+
* `prometheus.scrape`
14+
* `prometheus.relabel`
15+
* `prometheus.remote_write`
16+
17+
Agent Flow's performance is comparable to Prometheus, because `prometheus` Flow components are abe
18+
to processes Prometheus metrics natively without converting them to other formats such as OTLP.
19+
20+
Agent Flow also comes pre-built with exporters out of the box. For example, `prometheus.exporter.unix`
21+
provides the functionality of Prometheus' [Node Exporter][node-exporter].
22+
23+
[prom-agent-mode-flag]: https://prometheus.io/docs/prometheus/latest/feature_flags/#prometheus-agent
24+
[prom-agent-mode-blog]: https://prometheus.io/blog/2021/11/16/agent/
25+
[node-exporter]: https://github.com/prometheus/node_exporter

0 commit comments

Comments
 (0)