Apply suggestions from code review

Co-authored-by: Clayton Cornell <[email protected]>
Co-authored-by: William Dumont <[email protected]>

Author: 3 people

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

@@ -15,18 +15,18 @@ 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.
 * `otelcol.receiver.loki` converts Loki logs to OTLP logs.
 * `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 >}}
 

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

@@ -18,80 +18,89 @@ 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 an 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
 ```
 
 ### 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
 

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`