diff --git a/docs/sources/flow/when-to-use-flow/_index.md b/docs/sources/flow/when-to-use-flow/_index.md index 5dd54b2dd4bb..5a12c44fe169 100644 --- a/docs/sources/flow/when-to-use-flow/_index.md +++ b/docs/sources/flow/when-to-use-flow/_index.md @@ -15,7 +15,7 @@ Grafana Agent Flow allows you to process telemetry in a variety of formats, nati Native processing of telemetry could lead to higher efficiency and ease of use. -It is also possible from switch to one format to another. For example: +It is also possible to switch from one format to another. For example: * `otelcol.exporter.prometheus` converts OTLP metrics to Prometheus logs. * `otelcol.receiver.prometheus` converts Prometheus metrics to OTLP metrics. * `otelcol.exporter.loki` converts OTLP logs to Loki logs. @@ -23,10 +23,10 @@ It is also possible from switch to one format to another. For example: * `otelcol.connector.spanlogs` converts OTLP spans to OTLP logs. * `otelcol.connector.spanmetrics` converts OTLP spans to OTLP metrics. -There are even Flow components which do not deal with telemetry. For example, `mimir.rules.kubernetes` +There are even Flow components that do not deal with telemetry. For example, `mimir.rules.kubernetes` can be used to configure a Mimir instance. -The articles in this section describe in more detail how Flow compares to similar products: +The following topics describe in more detail how Flow compares to similar products: {{< section >}} diff --git a/docs/sources/flow/when-to-use-flow/opentelemetry-collector.md b/docs/sources/flow/when-to-use-flow/opentelemetry-collector.md index 9faf68385049..4c3e0fbb699d 100644 --- a/docs/sources/flow/when-to-use-flow/opentelemetry-collector.md +++ b/docs/sources/flow/when-to-use-flow/opentelemetry-collector.md @@ -18,57 +18,61 @@ The Collector may be a better choice if: * You are already using the Collector, and do not need any of the features of Flow. * You prefer YAML syntax over River. -Below you can find more details on similarities and differences between the Collector and Flow. - ## Similarities ### Many Collector components are available in Flow -Flow contains many of the components available inside the Collector: -* For example, the OTLP exporter is available as `otelcol.exporter.otlp`. -* The Grafana Agent development team is actively working on adding more of the Collector's components to Flow. -* If a Flow user needs a Collector feature to be made available in the Agent, the Agent development team could work on implementing it. +Flow contains many of the components available inside the Collector. +For example, Collector's OTLP exporter is available in Flow as `otelcol.exporter.otlp`. + +The Grafana Agent development team is actively working on adding more of the Collector's components to Flow. +If a Flow user needs a Collector feature to be made available in the Agent, the Agent development team could work on implementing it. ### Similar performance when processing OpenTelemetry signals natively Most of Flow's `otelcol` components are just thin wrappers over a Collector component. -Hence, the CPU and memory performance of Flow is similar. +As a result, the CPU and memory performance of Flow is similar. ## Differences ### Configuration language -Collector is configured using yaml, whereas Flow is configured using River. +Collector uses YAML for its configuration, and Flow uses River for its configuration. #### Example - coalesce -One of River's main advantages is its standard library. It contains handy functions such as coalesce, -which could be used to retrieve the first argument which is not null or empty: +One of River's main advantages is its standard library. It contains handy functions such as coalesce. +You can use this function to retrieve the first argument which is not null or empty: ```river ``` ### Modularity -The Agent configuration is more flexible, modular, and allows for more opportunities to chain components together in a pipeline. +The Agent configuration is flexible and modular: +* Telemetry and non-telemetry components can be combined easily. + For example, a configuration argument for `otelcol.exporter.otlp` could be supplied from the response of an HTTP request via `remote.http`. +* Some or all of the components which an Agent runs could be defined outside of its main config file. + For example, whole snippets of Flow configuration could be loaded from a file (`module.file`), + a Git repository (`module.git`), or a HTTP endpoint (`module.http`). #### Example - retrieving data from a file -Let's say you would like to use OAuth2 authentication in the Collector. If you need to retrieve `client_id` -or `client_secret` from a file, then you would have to use the `client_id_file` or `client_secret_file` config parameters. +Let's say you want to use OAuth2 authentication in the Collector. If you need to retrieve `client_id` +or `client_secret` from a file, then you must use the `client_id_file` or `client_secret_file` config parameters. ```yaml ``` In the Agent, you'd use `otelcol.auth.oauth2` with the normal `client_id` and `client_secret` parameters, -and you would setup another component which retrieves those from a `local.file` component. +and you would set up another component that retrieves those from a `local.file` component. ```river ``` -Moreover, the string could also come from a `remote.s3`, `remote.vault`, or `remote.http`. +The string could also come from a `remote.s3`, `remote.vault`, or `remote.http`. This gives Flow users lots of flexibility because strings coming out of those components -could be used for any parameter, in any component which requires a string - not just for +could be used for any parameter in any component which requires a string - not just for a `client_id` for OAuth2. ```river @@ -76,22 +80,27 @@ a `client_id` for OAuth2. ### Flow can process Prometheus signals natively -Collector needs to convert Prometheus signals to the OTLP format in order to process them. +Collector needs to convert Prometheus signals to the OTLP format to process them. Flow, on the other hand, can process those signals natively using components such as `prometheus.relabel`, `prometheus.relabel`, and `prometheus.remote_write`. This could lead to better performance and ease of use. ### Flow documentation is consistent and structured -Flow components tend to be documented in a more consistent way than Collector components. +Flow components are documented in a consistent and structured way. ### Some Collector features are not available in the Agent and vice-versa -Agent doesn't have all the components which the Collector has. However, the Grafana Agent development team is working on -adding new components all the time and we would be happy to add new components which Flow users need. +Agent doesn't have all the components which the Collector has. However, the Grafana Agent development team is constantly working on +adding new components, and would be happy to add new components that Flow users need. ### Flow supports "profile" telemetry signals -OpenTelemetry currently does not support "profile" signals. Flow supports them through components such as `pyroscope.scrape` and `pyroscope.ebpf`. +OpenTelemetry currently does not support "profile" signals. Flow supports "profile" signals through components such as `pyroscope.scrape` and `pyroscope.ebpf`. + +### Flow can load balance scraping dynamically + +Using clustering, `prometheus.scrape` and `pyroscope.scrape` use a gossip communication to load balance +scraping among each other. Agents can be added and removed from the cluster without having to restart the whole set of Agents. ### Flow is usually a few versions of OpenTelemetry behind diff --git a/docs/sources/flow/when-to-use-flow/prometheus-agent.md b/docs/sources/flow/when-to-use-flow/prometheus-agent.md index e2d926973393..dc2b438f732f 100644 --- a/docs/sources/flow/when-to-use-flow/prometheus-agent.md +++ b/docs/sources/flow/when-to-use-flow/prometheus-agent.md @@ -14,7 +14,7 @@ Grafana Agent Flow supports all of the [features][prom-agent-mode-blog] of the [ * `prometheus.relabel` * `prometheus.remote_write` -Agent Flow's performance is comparable to Prometheus, because `prometheus` Flow components are abe +Agent Flow's performance is comparable to Prometheus, because `prometheus` Flow components are able to processes Prometheus metrics natively without converting them to other formats such as OTLP. Agent Flow also comes pre-built with exporters out of the box. For example, `prometheus.exporter.unix`