More language cleanup with focus on passive

docs/sources/flow/concepts/clustering.md

@@ -51,7 +51,7 @@ All participating components locally recalculate target ownership and re-balance
 Target auto-distribution allows you to dynamically scale the number of {{< param "PRODUCT_ROOT_NAME" >}}s to distribute workload during peaks.
 It also provides resiliency because targets are automatically picked up by one of the node peers if a node leaves.
 
-{{< param "PRODUCT_NAME" >}} uses a fully local consistent hashing algorithm to distribute targets, meaning that, on average, only ~1/N of the targets are redistributed.
+{{< param "PRODUCT_NAME" >}} uses a local consistent hashing algorithm to distribute targets, meaning that, on average, only ~1/N of the targets are redistributed.
 
 Refer to component reference documentation to discover whether it supports clustering, such as:
 

docs/sources/flow/concepts/component_controller.md

@@ -51,7 +51,7 @@ local.file "b" {
 ## Component evaluation
 
 A component is _evaluated_ when its expressions are computed into concrete values.
-The computed values are then used to configure the component's runtime behavior.
+The computed values configure the component's runtime behavior.
 The component controller is finished loading once all components are evaluated, configured, and running.
 
 The component controller only evaluates a given component after evaluating all of that component's dependencies.
@@ -92,13 +92,13 @@ When a component fails to evaluate, it's marked as unhealthy with the reason for
 When an evaluation fails, the component continues operating as normal.
 The component continues using its previous set of evaluated arguments and can continue exporting new values.
 
-This prevents failure propagation.
+This behavior prevents failure propagation.
 If your `local.file` component, which watches API keys, suddenly stops working, other components continue using the last valid API key until the component returns to a healthy state.
 
 ## In-memory traffic
 
 Components that expose HTTP endpoints, such as [prometheus.exporter.unix][], can expose an internal address that completely bypasses the network and communicate in-memory.
-This allows components within the same process to communicate with one another without needing to be aware of any network-level protections such as authentication or mutual TLS.
+Components within the same process can communicate with one another without needing to be aware of any network-level protections such as authentication or mutual TLS.
 
 The internal address defaults to `agent.internal:12345`.
 If this address collides with a real target on your network, change it to something unique using the `--server.http.memory-addr` flag in the [run][] command.
@@ -108,7 +108,7 @@ Refer to the individual documentation for components to learn if in-memory traff
 
 ## Updating the configuration file
 
-Both the `/-/reload` HTTP endpoint and the `SIGHUP` signal can inform the component controller to reload the configuration file.
+The `/-/reload` HTTP endpoint and the `SIGHUP` signal can inform the component controller to reload the configuration file.
 When this happens, the component controller synchronizes the set of running components with the ones in the configuration file,
 removing components no longer defined in the configuration file and creating new components added to the configuration file.
 All components managed by the controller are reevaluated after reloading.

docs/sources/flow/concepts/components.md

@@ -24,8 +24,8 @@ Components are composed of the following:
 Each component has a name that describes what that component is responsible for.
 For example, the `local.file` component is responsible for retrieving the contents of files on disk.
 
-Components are specified in the configuration file by first providing the component's name with a user-specified label,
-and then by providing arguments to configure the component.
+You specify components in the configuration file by first providing the component's name with a user-specified label,
+and then by giving arguments to configure the component.
 
 ```river
 discovery.kubernetes "pods" {
@@ -37,11 +37,11 @@ discovery.kubernetes "nodes" {
 }
 ```
 
-> Components are referenced by combining the component name with its label.
-> For example, a `local.file` component labeled `foo` would be referenced as `local.file.foo`.
->
-> The combination of a component's name and its label must be unique within the configuration file.
-> This means multiple instances of a component may be defined as long as each instance has a different label value.
+You reference components by combining the component name with its label.
+For example, you can reference a `local.file` component labeled `foo` as `local.file.foo`.
+
+The combination of a component's name and its label must be unique within the configuration file.
+Combining component names with a label means you can define multiple instances of a component as long as each instance has a different label value.
 
 ## Pipelines
 
@@ -51,19 +51,19 @@ Most arguments for a component in a configuration file are constant values, such
 log_level = "debug"
 ```
 
-_Expressions_ can be used to dynamically compute the value of an argument at runtime.
-Among other things, expressions can be used to retrieve the value of an environment variable
-(`log_level = env("LOG_LEVEL")`) or to reference an exported field of another component (`log_level = local.file.log_level.content`).
+You use _expressions_ to dynamically compute the value of an argument at runtime.
+You can use expressions to retrieve the value of an environment variable (`log_level = env("LOG_LEVEL")`)
+or to reference an exported field of another component (`log_level = local.file.log_level.content`).
 
-A dependent relationship is created when a component's argument references an exported field of another component.
-A component's input (arguments) now depends on another component's output (exports).
-The input of the component is re-evaluated whenever the exports of the components it references get updated.
+You create a dependent relationship when a component's argument references an exported field of another component.
+A component's arguments now depend on another component's exports.
+The input of the component is re-evaluated whenever the exports of the components it references are updated.
 
 The flow of data through the set of references between components forms a _pipeline_.
 
 An example pipeline may look like this:
 
-1. A `local.file` component watches a file on disk containing an API key.
+1. A `local.file` component watches a file that contains an API key.
 1. A `prometheus.remote_write` component is configured to receive metrics and forward them to an external database using the API key from the `local.file` for authentication.
 1. A `discovery.kubernetes` component discovers and exports Kubernetes Pods where metrics can be collected.
 1. A `prometheus.scrape` component references the exports of the previous component, and sends collected metrics to the `prometheus.remote_write` component.
@@ -100,7 +100,7 @@ prometheus.remote_write "prod" {
     basic_auth {
       username = "admin"
 
-      // Use our password file for authenticating with the production database.
+      // Use the password file to authenticate with the production database.
       password = local.file.api_key.content
     }
   }

docs/sources/flow/concepts/configuration_language.md

@@ -41,7 +41,7 @@ River is designed with the following requirements in mind:
 You use _Attributes_ to configure individual settings.
 Attributes always take the form of `ATTRIBUTE_NAME = ATTRIBUTE_VALUE`.
 
-The following example shows you how to set the `log_level` attribute to `"debug"`.
+The following example shows how to set the `log_level` attribute to `"debug"`.
 
 ```river
 log_level = "debug"
@@ -64,7 +64,7 @@ You can use expressions for any attribute inside a component definition.
 
 The most common expression is to reference the exports of a component, for example, `local.file.password_file.content`.
 You form a reference to a component's exports by merging the component's name (for example, `local.file`),
-label (for example, `password_file`), and export name (for example, `content`), delimited by period.
+label (for example, `password_file`), and export name (for example, `content`), delimited by a period.
 
 ## Blocks
 
@@ -83,8 +83,8 @@ The preceding example has two blocks:
 
 * `prometheus.remote_write "default"`: A labeled block which instantiates a `prometheus.remote_write` component.
   The label is the string `"default"`.
-* `endpoint`: An unlabeled block inside the component which configures an endpoint to send metrics to.
-  This block sets the `url` attribute to specify what the endpoint is.
+* `endpoint`: An unlabeled block inside the component that configures an endpoint to send metrics to.
+  This block sets the `url` attribute to specify the endpoint.
 
 ## More information
 

docs/sources/flow/concepts/modules.md

@@ -47,7 +47,7 @@ Refer to [Components][] for more information about the module loader components.
 
 ## Module sources
 
-Modules are flexible and you can retrieve their configuration anywhere, such as:
+Modules are flexible, and you can retrieve their configuration anywhere, such as:
 
 * The local filesystem.
 * An S3 bucket.
@@ -78,9 +78,9 @@ This example module manages a pipeline that filters out debug-level and info-lev
 
 ```river
 // argument.write_to is a required argument that specifies where filtered
-// log lines should be sent.
+// log lines are sent.
 //
-// The value of the argument can be retrieved in this file with
+// The value of the argument is retrieved in this file with
 // argument.write_to.value.
 argument "write_to" {
   optional = false
@@ -99,7 +99,7 @@ loki.process "filter" {
   forward_to = argument.write_to.value
 }
 
-// export.filter_input exports a value to the consumer of the module.
+// export.filter_input exports a value to the module consumer.
 export "filter_input" {
   // Expose the receiver of loki.process so the module consumer can send
   // logs to our loki.process component.

docs/sources/flow/config-language/_index.md

@@ -13,14 +13,14 @@ weight: 400
 
 # Configuration language
 
-{{< param "PRODUCT_NAME" >}} uses a custom configuration language called River to dynamically configure and connect components.
+{{< param "PRODUCT_NAME" >}} dynamically configures and connects components with a custom configuration language called River.
 
 River aims to reduce errors in configuration files by making configurations easier to read and write.
 River configurations use blocks that can be easily copied and pasted from the documentation to help you get started as quickly as possible.
 
 A River configuration file tells {{< param "PRODUCT_NAME" >}} which components to launch and how to bind them together into a pipeline.
 
-The syntax of River is centered around blocks, attributes, and expressions.
+The syntax of River uses blocks, attributes, and expressions.
 
 ```river
 // Create a local.file component labeled my_file.
@@ -43,16 +43,16 @@ BLOCK_NAME {
 ```
 
 [River][RFC] is similar to HCL, the language Terraform and other Hashicorp projects use.
-River was inspired by HCL, but is a distinct language with different syntax and features, such as first-class functions.
+It's a distinct language with custom syntax and features, such as first-class functions.
 
 * Blocks are a group of related settings and usually represent creating a component.
-  Blocks have a name that consist of zero or more identifiers separated by `.`, an optional user label, and a body that contains attributes and nested blocks.
+  Blocks have a name that consists of zero or more identifiers separated by `.`, an optional user label, and a body containing attributes and nested blocks.
 * Attributes appear within blocks and assign a value to a name.
 * Expressions represent a value, either literally or by referencing and combining other values.
-  Expressions are used to compute a value for an attribute.
+  You use expressions to compute a value for an attribute.
 
-River is declarative, so the ordering of components, blocks, and attributes within a block isn't significant.
-The order of operations is determined by the relationship between components.
+River is declarative, so ordering components, blocks, and attributes within a block isn't significant.
+The relationship between components determines the order of operations.
 
 [RFC]: https://github.com/grafana/agent/blob/97a55d0d908b26dbb1126cc08b6dcc18f6e30087/docs/rfcs/0005-river.md
 

docs/sources/flow/config-language/components.md

@@ -32,14 +32,14 @@ Most user interactions with components center around two basic concepts, _argume
   They can be any number of attributes or nested unlabeled blocks, some required and some optional.
   Any optional arguments that aren't set take on their default values.
 
-* _Exports_ are zero or more output values that other components can refer to, and they can be of any River type.
+* _Exports_ are zero or more output values that other components can refer to and can be of any River type.
 
 The following block defines a `local.file` component labeled "targets".
 The `local.file.targets` component exposes the file `content` as a string in its exports.
 
 The `filename` attribute is a _required_ argument.
 You can also define a number of _optional_ arguments, in this case, `detector`, `poll_frequency`, and `is_secret`,
-that configure how and how often the file should be polled and whether its contents are sensitive or not.
+that configure how and how often the file should be polled and whether its contents are sensitive.
 
 ```river
 local.file "targets" {
@@ -79,14 +79,14 @@ prometheus.scrape "default" {
 }
 ```
 
-Every time the file contents change, the `local.file` updates its exports. The new value is given to the `prometheus.scrape` targets field.
+Each time the file contents change, the `local.file` updates its exports. The new value is sent to the `prometheus.scrape` targets field.
 
 Each argument and exported field has an underlying [type][].
-River type-checks expressions before assigning a value to an attribute.
-The documentation of each [component][components] provides more information about the ways that you can wire components together.
+River checks the expression type before assigning a value to an attribute.
+The documentation of each [component][components] provides more information about how to wire components together.
 
 In the previous example, the contents of the `local.file.targets.content` expression is evaluated to a concrete value.
-The value is type-checked and substituted into `prometheus.scrape.default` where it can be configured.
+The value is type-checked and substituted into `prometheus.scrape.default`, where you can configure it.
 
 [components]: {{< relref "../reference/components/_index.md" >}}
 [controller]: {{< relref "../concepts/component_controller.md" >}}

docs/sources/flow/config-language/expressions/_index.md

@@ -13,14 +13,14 @@ weight: 400
 
 # Expressions
 
-Expressions represent or compute values that you can assign to attributes within a configuration.
+Expressions represent or compute values you can assign to attributes within a configuration.
 
 Basic expressions are literal values, like `"Hello, world!"` or `true`.
 Expressions may also do things like [refer to values][] exported by components, perform arithmetic, or [call functions][].
 
 You use expressions when you configure any component.
 All component arguments have an underlying [type][].
-River type-checks expressions before assigning the result to an attribute.
+River checks the expression type before assigning the result to an attribute.
 
 [refer to values]: {{< relref "./referencing_exports.md" >}}
 [call functions]: {{< relref "./function_calls.md" >}}

docs/sources/flow/config-language/expressions/operators.md

@@ -14,7 +14,7 @@ weight: 300
 # Operators
 
 River uses a common set of operators.
-All operations follow the standard [PEMDAS][] rule for operator precedence.
+All operations follow the standard [PEMDAS][] order of mathematical operations.
 
 ## Arithmetic operators
 
@@ -100,9 +100,9 @@ Operator | Description
 `[ ]`    | Access a member of an array or object.
 `.`      | Access a named member of an object or an exported field of a component.
 
-River's access operators support accessing of arbitrarily nested values.
+You can access arbitrarily nested values with River's access operators.
 You can use square brackets to access zero-indexed array indices and object fields by enclosing the field name in double quotes.
-You can use the dot operator to access both object fields without double quotes, and component exports.
+You can use the dot operator to access object fields without double quotes and component exports.
 
 ```river
 obj["app"]

docs/sources/flow/config-language/expressions/referencing_exports.md

@@ -14,7 +14,7 @@ weight: 200
 # Referencing component exports
 
 Referencing exports enables River to configure and connect components dynamically using expressions.
-While components can work in isolation, they're more useful when one component's behavior and data flow is bound to the exports of another,
+While components can work in isolation, they're more useful when one component's behavior and data flow are bound to the exports of another,
 building a dependency relationship between the two.
 
 Such references can only appear as part of another component's arguments or a configuration block's fields.
@@ -50,8 +50,8 @@ In the preceding example, you wired together a very simple pipeline by writing a
 
 ![Flow of example pipeline](/media/docs/agent/flow_referencing_exports_diagram.svg)
 
-As with all expressions, once the value is resolved, it must match the [type][] of the attribute it is assigned to.
+After the value is resolved, it must match the [type][] of the attribute it is assigned to.
 While you can only configure attributes using the basic River types,
-the exports of components can take on special internal River types such as Secrets or Capsules, which expose different functionality.
+the exports of components can take on special internal River types, such as Secrets or Capsules, which expose different functionality.
 
 [type]: {{< relref "./types_and_values.md" >}}