From b42073f7ab1af8af7ba656b48b31e2da55100df5 Mon Sep 17 00:00:00 2001
From: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com>
Date: Thu, 14 Dec 2023 09:45:37 -0800
Subject: [PATCH] Update the Agent Concepts topics (#5956)
* Update grammar spelling and syntax
* Updates for semantic line breaks
* More cleanup of grammar spelling and word use
* Another pass at cleanup and consistency
* Additional edits nad updates for grammar style
* Fix image link
* Update images grammar spelling xrefs
* More language cleanup with focus on passive
* Convert links to doc references
* Tidy up punctuation and fix broken links
* Update docs/sources/flow/config-language/syntax.md
---
.../assets/concepts_example_pipeline.svg | 304 ------------------
.../flow_referencing_exports_diagram.svg | 216 -------------
docs/sources/flow/concepts/_index.md | 2 +-
docs/sources/flow/concepts/clustering.md | 45 +--
.../flow/concepts/component_controller.md | 104 +++---
docs/sources/flow/concepts/components.md | 81 ++---
.../flow/concepts/configuration_language.md | 61 ++--
docs/sources/flow/concepts/modules.md | 66 ++--
docs/sources/flow/config-language/_index.md | 64 ++--
.../flow/config-language/components.md | 83 +++--
.../config-language/expressions/_index.md | 24 +-
.../expressions/function_calls.md | 26 +-
.../config-language/expressions/operators.md | 71 ++--
.../expressions/referencing_exports.md | 46 ++-
.../expressions/types_and_values.md | 174 +++++-----
docs/sources/flow/config-language/files.md | 11 +-
docs/sources/flow/config-language/syntax.md | 79 ++---
.../migrating-from-prometheus.md | 2 +-
.../getting-started/migrating-from-static.md | 10 +-
19 files changed, 423 insertions(+), 1046 deletions(-)
delete mode 100644 docs/sources/assets/concepts_example_pipeline.svg
delete mode 100644 docs/sources/assets/flow_referencing_exports_diagram.svg
diff --git a/docs/sources/assets/concepts_example_pipeline.svg b/docs/sources/assets/concepts_example_pipeline.svg
deleted file mode 100644
index ebbfa535c37e..000000000000
--- a/docs/sources/assets/concepts_example_pipeline.svg
+++ /dev/null
@@ -1,304 +0,0 @@
-
-
-
diff --git a/docs/sources/assets/flow_referencing_exports_diagram.svg b/docs/sources/assets/flow_referencing_exports_diagram.svg
deleted file mode 100644
index f6bb77ef06bf..000000000000
--- a/docs/sources/assets/flow_referencing_exports_diagram.svg
+++ /dev/null
@@ -1,216 +0,0 @@
-
-
-
diff --git a/docs/sources/flow/concepts/_index.md b/docs/sources/flow/concepts/_index.md
index da8e2ddf57da..786af8e5467b 100644
--- a/docs/sources/flow/concepts/_index.md
+++ b/docs/sources/flow/concepts/_index.md
@@ -13,6 +13,6 @@ weight: 100
# Concepts
-This section explains primary concepts of {{< param "PRODUCT_NAME" >}}.
+This section explains the primary concepts of {{< param "PRODUCT_NAME" >}}.
{{< section >}}
diff --git a/docs/sources/flow/concepts/clustering.md b/docs/sources/flow/concepts/clustering.md
index 0dd2139462d1..3f6f5b093639 100644
--- a/docs/sources/flow/concepts/clustering.md
+++ b/docs/sources/flow/concepts/clustering.md
@@ -15,32 +15,25 @@ weight: 500
# Clustering (beta)
-Clustering enables a fleet of {{< param "PRODUCT_ROOT_NAME" >}}s to work together for workload distribution
-and high availability. It helps create horizontally scalable deployments with
-minimal resource and operational overhead.
+Clustering enables a fleet of {{< param "PRODUCT_ROOT_NAME" >}}s to work together for workload distribution and high availability.
+It helps create horizontally scalable deployments with minimal resource and operational overhead.
-To achieve this, {{< param "PRODUCT_NAME" >}} makes use of an eventually consistent model that
-assumes all participating {{< param "PRODUCT_ROOT_NAME" >}}s are interchangeable and converge on using the
-same configuration file.
+To achieve this, {{< param "PRODUCT_NAME" >}} makes use of an eventually consistent model that assumes all participating
+{{< param "PRODUCT_ROOT_NAME" >}}s are interchangeable and converge on using the same configuration file.
-The behavior of a standalone, non-clustered {{< param "PRODUCT_ROOT_NAME" >}} is the same as if it was a
-single-node cluster.
+The behavior of a standalone, non-clustered {{< param "PRODUCT_ROOT_NAME" >}} is the same as if it were a single-node cluster.
-You configure clustering by passing `cluster` command-line flags to the [run][]
-command.
+You configure clustering by passing `cluster` command-line flags to the [run][] command.
## Use cases
### Target auto-distribution
-Target auto-distribution is the most basic use case of clustering; it allows
-scraping components running on all peers to distribute scrape load between
-themselves. For target auto-distribution to work correctly, all {{< param "PRODUCT_ROOT_NAME" >}} in the
-same cluster must be able to reach the same service discovery APIs and must be
-able to scrape the same targets.
+Target auto-distribution is the most basic use case of clustering.
+It allows scraping components running on all peers to distribute the scrape load between themselves.
+Target auto-distribution requires that all {{< param "PRODUCT_ROOT_NAME" >}} in the same cluster can reach the same service discovery APIs and scrape the same targets.
-You must explicitly enable target auto-distribution on components by defining a
-`clustering` block, such as:
+You must explicitly enable target auto-distribution on components by defining a `clustering` block.
```river
prometheus.scrape "default" {
@@ -52,18 +45,15 @@ prometheus.scrape "default" {
}
```
-A cluster state change is detected when a new node joins or an existing node goes away. All participating components locally
-recalculate target ownership and re-balance the number of targets they’re
-scraping without explicitly communicating ownership over the network.
+A cluster state change is detected when a new node joins or an existing node leaves.
+All participating components locally recalculate target ownership and re-balance the number of targets they’re scraping without explicitly communicating ownership over the network.
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 goes away.
+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:
+Refer to component reference documentation to discover whether it supports clustering, such as:
- [prometheus.scrape][]
- [pyroscope.scrape][]
@@ -72,9 +62,8 @@ clustering, such as:
## Cluster monitoring and troubleshooting
-To monitor your cluster status, you can check the {{< param "PRODUCT_NAME" >}} UI [clustering page][].
-The [debugging][] topic contains some clues to help pin down probable
-clustering issues.
+You can use the {{< param "PRODUCT_NAME" >}} UI [clustering page][] to monitor your cluster status.
+Refer to [Debugging clustering issues][debugging] for additional troubleshooting information.
{{% docs/reference %}}
[run]: "/docs/agent/ -> /docs/agent//flow/reference/cli/run.md#clustering-beta"
diff --git a/docs/sources/flow/concepts/component_controller.md b/docs/sources/flow/concepts/component_controller.md
index e3896050c6c6..1a19e13b4979 100644
--- a/docs/sources/flow/concepts/component_controller.md
+++ b/docs/sources/flow/concepts/component_controller.md
@@ -13,8 +13,7 @@ weight: 200
# Component controller
-The _component controller_ is the core part of {{< param "PRODUCT_NAME" >}} which manages
-components at runtime.
+The _component controller_ is the core part of {{< param "PRODUCT_NAME" >}} which manages components at runtime.
The component controller is responsible for:
@@ -25,16 +24,12 @@ The component controller is responsible for:
## Component graph
-As discussed in [Components][], a relationship between components is created
-when an expression is used to set the argument of one component to an exported
-field of another component.
+A relationship between [components][Components] is created when an expression is used to set the argument of one component to an exported field of another component.
-The set of all components and the relationships between them define a [Directed
-Acyclic Graph][DAG] (DAG), which informs the component controller which
-references are valid and in what order components must be evaluated.
+The set of all components and the relationships between them define a [Directed Acyclic Graph][DAG] (DAG),
+which informs the component controller which references are valid and in what order components must be evaluated.
-For a configuration file to be valid, components must not reference themselves or
-contain a cyclic reference:
+For a configuration file to be valid, components must not reference themselves or contain a cyclic reference.
```river
// INVALID: local.file.some_file can not reference itself:
@@ -55,87 +50,68 @@ 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 component controller is finished loading once all components are
-evaluated, configured, and running.
+A component is _evaluated_ when its expressions are computed into concrete values.
+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. Components that do not depend on other
-components can be evaluated at any time during the evaluation process.
+The component controller only evaluates a given component after evaluating all of that component's dependencies.
+Components that don't depend on other components can be evaluated anytime during the evaluation process.
## Component reevaluation
-As mentioned in [Components][], a component is dynamic: a component can update
-its exports any number of times throughout its lifetime.
+A [component][Components] is dynamic. A component can update its exports any number of times throughout its lifetime.
-When a component updates its exports, a _controller reevaluation_ is triggered:
-the component controller reevaluates any component which references the changed
-component, any components which reference those components, and so on, until
-all affected components are reevaluated.
+A _controller reevaluation_ is triggered when a component updates its exports.
+The component controller reevaluates any component that references the changed component, any components that reference those components,
+and so on, until all affected components are reevaluated.
## Component health
At any given time, a component can have one of the following health states:
-1. Unknown: default state, the component isn't running yet.
-2. Healthy: the component is working as expected.
-3. Unhealthy: the component is not working as expected.
-4. Exited: the component has stopped and is no longer running.
+1. Unknown: The default state. The component isn't running yet.
+1. Healthy: The component is working as expected.
+1. Unhealthy: The component isn't working as expected.
+1. Exited: The component has stopped and is no longer running.
-By default, the component controller determines the health of a component. The
-component controller marks a component as healthy as long as that component is
-running and its most recent evaluation succeeded.
+By default, the component controller determines the health of a component.
+The component controller marks a component as healthy as long as that component is running and its most recent evaluation succeeded.
-Some components can report their own component-specific health information. For
-example, the `local.file` component reports itself as unhealthy if the file it
-was watching gets deleted.
+Some components can report their own component-specific health information.
+For example, the `local.file` component reports itself as unhealthy if the file it was watching gets deleted.
-The overall health of a component is determined by combining the
-controller-reported health of the component with the component-specific health
-information.
+The overall health of a component is determined by combining the controller-reported health of the component with the component-specific health information.
-An individual component's health is independent of the health of any other
-components it references: a component can be marked as healthy even if it
-references an exported field of an unhealthy component.
+An individual component's health is independent of the health of any other components it references.
+A component can be marked as healthy even if it references an exported field of an unhealthy component.
## Handling evaluation failures
-When a component fails to evaluate, it is marked as unhealthy with the reason
-for why the evaluation failed.
+When a component fails to evaluate, it's marked as unhealthy with the reason for why the evaluation failed.
-When an evaluation fails, the component continue operating as normal: it
-continues using its previous set of evaluated arguments, and it can continue
-exporting new values.
+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: if your `local.file` component which watches
-API keys suddenly stops working, other components continues using the last
-valid API key until the component returns to a healthy state.
+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 which expose HTTP endpoints, such as [prometheus.exporter.unix][],
-can expose an internal address which will completely bypass 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 that expose HTTP endpoints, such as [prometheus.exporter.unix][], can expose an internal address that completely bypasses the network and communicate in-memory.
+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.
+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.
-Components must opt-in to using in-memory traffic. See the individual
-documentation for components to learn if in-memory traffic is supported.
+Components must opt-in to using in-memory traffic.
+Refer to the individual documentation for components to learn if in-memory traffic is supported.
## Updating the configuration file
-Both the `/-/reload` HTTP endpoint and the `SIGHUP` signal can be used to
-inform the component controller to reload the configuration file. When this happens,
-the component controller will synchronize the set of running components with
-the ones in the configuration file, removing components which are no longer defined in
-the configuration file and creating new components which were added to the configuration
-file. All components managed by the controller will be reevaluated after
-reloading.
+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.
[DAG]: https://en.wikipedia.org/wiki/Directed_acyclic_graph
diff --git a/docs/sources/flow/concepts/components.md b/docs/sources/flow/concepts/components.md
index 223d76b4f4f8..1f93d768113e 100644
--- a/docs/sources/flow/concepts/components.md
+++ b/docs/sources/flow/concepts/components.md
@@ -13,22 +13,19 @@ weight: 100
# Components
-_Components_ are the building blocks of {{< param "PRODUCT_NAME" >}}. Each component is
-responsible for handling a single task, such as retrieving secrets or
-collecting Prometheus metrics.
+_Components_ are the building blocks of {{< param "PRODUCT_NAME" >}}.
+Each component handles a single task, such as retrieving secrets or collecting Prometheus metrics.
-Components are composed of two parts:
+Components are composed of the following:
-* Arguments: settings which configure a component.
-* Exports: named values which a component exposes to other components.
+* Arguments: Settings that configure a component.
+* Exports: Named values that a component exposes to other components.
-Each component has a name which describes what that component is responsible
-for. For example, the `local.file` component is responsible for retrieving the
-contents of files on disk.
+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 config 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" {
@@ -40,54 +37,40 @@ 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
-Most arguments for a component in a configuration file are constant values, such
-setting a `log_level` attribute to the quoted string `"debug"`:
+Most arguments for a component in a configuration file are constant values, such as setting a `log_level` attribute to the quoted string `"debug"`.
```river
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`).
-When a component's argument references an exported field of another component,
-a dependant relationship is created: a component's input (arguments) now
-depends on another component's output (exports). The input of the component
-will now be re-evaluated any time 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_.
+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.
-2. 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.
-3. A `discovery.kubernetes` component discovers and exports Kubernetes Pods
- where metrics can be collected.
-4. A `prometheus.scrape` component references the exports of the previous
- component, and sends collected metrics to the `prometheus.remote_write`
- component.
+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.
-
-
-
+
-The following configuration file represents the pipeline:
+The following configuration file represents the pipeline.
```river
// Get our API key from disk.
@@ -105,10 +88,10 @@ local.file "api_key" {
is_secret = true
}
-// Create a prometheus.remote_write component which other components can send
+// Create a prometheus.remote_write component, which other components can send
// metrics to.
//
-// This component exports a "receiver" value which can be used by other
+// This component exports a "receiver" value, which can be used by other
// components to send metrics.
prometheus.remote_write "prod" {
endpoint {
@@ -117,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
}
}
@@ -125,7 +108,7 @@ prometheus.remote_write "prod" {
// Find Kubernetes pods where we can collect metrics.
//
-// This component exports a "targets" value which contains the list of
+// This component exports a "targets" value, which contains the list of
// discovered pods.
discovery.kubernetes "pods" {
role = "pod"
diff --git a/docs/sources/flow/concepts/configuration_language.md b/docs/sources/flow/concepts/configuration_language.md
index bdd2d829b854..69b1a7357e71 100644
--- a/docs/sources/flow/concepts/configuration_language.md
+++ b/docs/sources/flow/concepts/configuration_language.md
@@ -13,10 +13,7 @@ weight: 400
# Configuration language concepts
-The {{< param "PRODUCT_NAME" >}} _configuration language_ refers to the language used in
-configuration files which define and configure components to run.
-
-The configuration language is called River, a Terraform/HCL-inspired language:
+The {{< param "PRODUCT_NAME" >}} _configuration language_, River, refers to the language used in configuration files that define and configure components to run.
```river
prometheus.scrape "default" {
@@ -33,51 +30,46 @@ prometheus.remote_write "default" {
}
```
-River was designed with the following requirements in mind:
+River is designed with the following requirements in mind:
-* _Fast_: The configuration language must be fast so the component controller
- can evaluate changes as quickly as possible.
-* _Simple_: The configuration language must be easy to read and write to
- minimize the learning curve.
-* _Debuggable_: The configuration language must give detailed information when
- there's a mistake in the configuration file.
+* _Fast_: The configuration language must be fast so the component controller can quickly evaluate changes.
+* _Simple_: The configuration language must be easy to read and write to minimize the learning curve.
+* _Debuggable_: The configuration language must give detailed information when there's a mistake in the configuration file.
## Attributes
-_Attributes_ are used to configure individual settings. They always take the
-form of `ATTRIBUTE_NAME = ATTRIBUTE_VALUE`.
+You use _Attributes_ to configure individual settings.
+Attributes always take the form of `ATTRIBUTE_NAME = ATTRIBUTE_VALUE`.
+
+The following example shows how to set the `log_level` attribute to `"debug"`.
```river
log_level = "debug"
```
-This sets the `log_level` attribute to `"debug"`.
-
## Expressions
-Expressions are used to compute the value of an attribute. The simplest
-expressions are constant values like `"debug"`, `32`, or `[1, 2, 3, 4]`. River
-supports more complex expressions, such as:
+You use expressions to compute the value of an attribute.
+The simplest expressions are constant values like `"debug"`, `32`, or `[1, 2, 3, 4]`.
+River supports complex expressions, for example:
* Referencing the exports of components: `local.file.password_file.content`
* Mathematical operations: `1 + 2`, `3 * 4`, `(5 * 6) + (7 + 8)`
* Equality checks: `local.file.file_a.content == local.file.file_b.content`
-* Calling functions from River's standard library: `env("HOME")` (retrieve the
- value of the `HOME` environment variable)
+* Calling functions from River's standard library: `env("HOME")` retrieves the value of the `HOME` environment variable.
-Expressions may be used for any attribute inside a component definition.
+You can use expressions for any attribute inside a component definition.
### Referencing component exports
-The most common expression is to reference the exports of a component like
-`local.file.password_file.content`. A reference to a component's exports is
-formed by merging the component's name (e.g., `local.file`), label (e.g.,
-`password_file`), and export name (e.g., `content`), delimited by period.
+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 a period.
## Blocks
-_Blocks_ are used to configure components and groups of attributes. Each block
-can contain any number of attributes or nested blocks.
+You use _Blocks_ to configure components and groups of attributes.
+Each block can contain any number of attributes or nested blocks.
```river
prometheus.remote_write "default" {
@@ -87,19 +79,16 @@ prometheus.remote_write "default" {
}
```
-This file has two blocks:
-
-* `prometheus.remote_write "default"`: A labeled block which instantiates a
- `prometheus.remote_write` component. The label is the string `"default"`.
+The preceding example has two blocks:
-* `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.
+* `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 that configures an endpoint to send metrics to.
+ This block sets the `url` attribute to specify the endpoint.
## More information
-River is documented in detail in [Configuration language][config-docs] section
-of the {{< param "PRODUCT_NAME" >}} docs.
+Refer to [Configuration language][config-docs] for more information about River.
{{% docs/reference %}}
[config-docs]: "/docs/agent/ -> /docs/agent//flow/config-language"
diff --git a/docs/sources/flow/concepts/modules.md b/docs/sources/flow/concepts/modules.md
index 2e5383fb6430..940357f30127 100644
--- a/docs/sources/flow/concepts/modules.md
+++ b/docs/sources/flow/concepts/modules.md
@@ -13,54 +13,48 @@ weight: 300
# Modules
-_Modules_ are a way to create {{< param "PRODUCT_NAME" >}} configurations which can be
-loaded as a component. Modules are a great way to parameterize a configuration
-to create reusable pipelines.
+You use _Modules_ to create {{< param "PRODUCT_NAME" >}} configurations that you can load as a component.
+Modules are a great way to parameterize a configuration to create reusable pipelines.
Modules are {{< param "PRODUCT_NAME" >}} configurations which have:
-* Arguments: settings which configure a module.
-* Exports: named values which a module exposes to the consumer of the module.
-* Components: {{< param "PRODUCT_NAME" >}} Components to run when the module is running.
+* _Arguments_: Settings that configure a module.
+* _Exports_: Named values that a module exposes to the consumer of the module.
+* _Components_: {{< param "PRODUCT_NAME" >}} components to run when the module is running.
-Modules are loaded into {{< param "PRODUCT_NAME" >}} by using a [Module
-loader](#module-loaders).
+You use a [Module loader][] to load Modules into {{< param "PRODUCT_NAME" >}}.
-Refer to the documentation for the [argument block][] and [export block][] to
-learn how to define arguments and exports for a module.
+Refer to [argument block][] and [export block][] to learn how to define arguments and exports for a module.
## Module loaders
-A _Module loader_ is a {{< param "PRODUCT_NAME" >}} component which retrieves a module
-and runs the components defined inside of it.
+A _Module loader_ is a {{< param "PRODUCT_NAME" >}} component that retrieves a module and runs the defined components.
-Module loader components are responsible for:
+Module loader components are responsible for the following functions:
-* Retrieving the module source to run.
-* Creating a [Component controller][] for the module to run in.
+* Retrieving the module source.
+* Creating a [Component controller][] for the module.
* Passing arguments to the loaded module.
* Exposing exports from the loaded module.
-Module loaders typically are called `module.LOADER_NAME`. The list of module
-loader components can be found in the list of {{< param "PRODUCT_NAME" >}}
-[Components][].
+Module loaders are typically called `module.LOADER_NAME`.
+{{% admonition type="note" %}}
Some module loaders may not support running modules with arguments or exports.
-Refer to the documentation for the module loader you are using for more
-information.
+{{% /admonition %}}
+
+Refer to [Components][] for more information about the module loader components.
## Module sources
-Modules are designed to be flexible, and can have their configuration retrieved
-from anywhere, such as:
+Modules are flexible, and you can retrieve their configuration anywhere, such as:
-* The local filesystem
-* An S3 bucket
-* An HTTP endpoint
+* The local filesystem.
+* An S3 bucket.
+* An HTTP endpoint.
-Each module loader component will support different ways of retrieving module
-sources. The most generic module loader component, `module.string`, can load
-modules from the export of another Flow component:
+Each module loader component supports different ways of retrieving `module.sources`.
+The most generic module loader component, `module.string`, can load modules from the export of another {{< param "PRODUCT_NAME" >}} component.
```river
local.file "my_module" {
@@ -80,14 +74,13 @@ module.string "my_module" {
## Example module
-This example module manages a pipeline which filters out debug- and info-level
-log lines which are given to it:
+This example module manages a pipeline that filters out debug-level and info-level log lines.
```river
-// argument.write_to is a required argument which specifies where filtered
-// log lines should be sent.
+// argument.write_to is a required argument that specifies where filtered
+// 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
@@ -106,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.
@@ -114,8 +107,7 @@ export "filter_input" {
}
```
-The module above can be saved to a file and then used as a processing step
-before writing logs to Loki:
+You can save the module to a file and then use it as a processing step before writing logs to Loki.
```river
loki.source.file "self" {
@@ -141,6 +133,8 @@ loki.write "default" {
}
```
+[Module loader]: #module-loaders
+
{{% docs/reference %}}
[argument block]: "/docs/agent/ -> /docs/agent//flow/reference/config-blocks/argument.md"
[argument block]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/reference/config-blocks/argument.md"
diff --git a/docs/sources/flow/config-language/_index.md b/docs/sources/flow/config-language/_index.md
index 1392678a5f21..2ed7afb8b284 100644
--- a/docs/sources/flow/config-language/_index.md
+++ b/docs/sources/flow/config-language/_index.md
@@ -13,18 +13,14 @@ weight: 400
# Configuration language
-{{< param "PRODUCT_NAME" >}} contains 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 are done in blocks which can be
-easily copied-and-pasted from documentation to help users get started as
-quickly as possible.
+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.
+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 River syntax uses blocks, attributes, and expressions.
```river
// Create a local.file component labeled my_file.
@@ -46,42 +42,38 @@ BLOCK_NAME {
}
```
-> You may have noticed that River looks similar to HCL, the language used by
-> Terraform and other Hashicorp projects. River was inspired by HCL, but is a
-> distinct language with different syntax and features, such as first-class
-> functions. If you are already familiar with HCL or Terraform, writing River
-> should seem mostly natural to you.
-
-> For historical context on why we decided to introduce River, you can read the
-> original [RFC][].
-
-* Blocks are a group of related settings, and usually represent creating a
- component. Blocks have a name which consist of zero or more identifiers
- separated by `.` (like `my_block` or `local.file` above), an optional user
- label, and a body which contains attributes and nested blocks.
+[River][RFC] is similar to HCL, the language Terraform and other Hashicorp projects use.
+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 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.
+ You use expressions to compute a value for an attribute.
-* Expressions represent a value, either literally or by referencing and
- combining other values. Expressions are used to compute a value for an
- attribute.
-
-River is declarative, so the ordering of components, blocks, and attributes
-within a block is not significant. The order of operations is determined by the
-relationship between components.
-
-[RFC]: https://github.com/grafana/agent/blob/97a55d0d908b26dbb1126cc08b6dcc18f6e30087/docs/rfcs/0005-river.md
+River is declarative, so ordering components, blocks, and attributes within a block isn't significant.
+The relationship between components determines the order of operations.
## Tooling
-To help you write configuration files in River, the following tools are available:
+You can use one or all of the following tools to help you write configuration files in River.
* Experimental editor support for
* [vim](https://github.com/rfratto/vim-river)
* [VSCode](https://github.com/rfratto/vscode-river)
* [river-mode](https://github.com/jdbaldry/river-mode) for Emacs
-* Code formatting using the [`agent fmt` command]({{< relref "../reference/cli/fmt" >}})
+* Code formatting using the [`agent fmt` command][fmt]
+
+You can also start developing your own tooling using the {{< param "PRODUCT_ROOT_NAME" >}} repository as a go package or use the
+[tree-sitter grammar][] with other programming languages.
-You can also start developing your own tooling using the {{< param "PRODUCT_ROOT_NAME" >}} repository as a
-go package or use the [tree-sitter
-grammar](https://github.com/grafana/tree-sitter-river) with other programming languages.
+[RFC]: https://github.com/grafana/agent/blob/97a55d0d908b26dbb1126cc08b6dcc18f6e30087/docs/rfcs/0005-river.md
+[vim]: https://github.com/rfratto/vim-river
+[VSCode]: https://github.com/rfratto/vscode-river
+[river-mode]: https://github.com/jdbaldry/river-mode
+[tree-sitter grammar]: https://github.com/grafana/tree-sitter-river
+
+{{% docs/reference %}}
+[fmt]: "/docs/agent/ -> /docs/agent//flow/reference/cli/fmt"
+[fmt]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/reference/cli/fmt"
+{{% /docs/reference %}}
\ No newline at end of file
diff --git a/docs/sources/flow/config-language/components.md b/docs/sources/flow/config-language/components.md
index 986567fe2610..3939363ba7a5 100644
--- a/docs/sources/flow/config-language/components.md
+++ b/docs/sources/flow/config-language/components.md
@@ -12,46 +12,34 @@ weight: 300
---
# Components configuration language
-Components are the defining feature of {{< param "PRODUCT_NAME" >}}. They are small,
-reusable pieces of business logic that perform a single task (like retrieving
-secrets or collecting Prometheus metrics) and can be wired together to form
-programmable pipelines of telemetry data.
-Under the hood, components are orchestrated via the [_component
-controller_]({{< relref "../concepts/component_controller.md" >}}), which is
-responsible for scheduling them, reporting their health and debug status,
-re-evaluating their arguments and providing their exports.
+Components are the defining feature of {{< param "PRODUCT_NAME" >}}.
+Components are small, reusable pieces of business logic that perform a single task like retrieving secrets or collecting Prometheus metrics,
+and you can wire them together to form programmable pipelines of telemetry data.
+
+The [_component controller_][controller] is responsible for scheduling components, reporting their health and debug status, re-evaluating their arguments, and providing their exports.
## Configuring components
-Components are created by defining a top-level River block. All components
-are identified by their name, describing what the component is responsible for,
-and a user-specified _label_.
-The [components docs]({{< relref "../reference/components/_index.md" >}}) contain a list
-of all available components. Each one has a complete reference page, so getting
-a component to work for you should be as easy as reading its documentation and
-copy/pasting from an example.
+You create [components][] by defining a top-level River block.
+All components are identified by their name, describing what the component is responsible for, and a user-specified _label_.
## Arguments and exports
-Most user interactions with components will center around two basic concepts;
-_arguments_ and _exports_.
-* _Arguments_ are settings which modify the behavior of a component. They can
- be any number of attributes or nested unlabeled blocks, some of them being
-required and some being optional. Any optional arguments that are not set will
-take on their default values.
+Most user interactions with components center around two basic concepts, _arguments_ and _exports_.
+
+* _Arguments_ are settings that modify the behavior of a component.
+ 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 can be referred to by other
- components, and 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.
-Here's a quick example; the following block defines a `local.file` component
-labeled "targets". The `local.file.targets` component will then expose the
-file `content` as a string in its exports.
+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; the user can also define a
-number of _optional_ ones, in this case `detector`, `poll_frequency` and
-`is_secret`, which configure how and how often the file should be polled
-as well as whether its contents are sensitive or not.
+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.
```river
local.file "targets" {
@@ -70,13 +58,12 @@ local.file "targets" {
```
## Referencing components
-To wire components together, one can use the exports of one as the arguments
-to another by using references. References can only appear in components.
-For example, here's a component that scrapes Prometheus metrics. The `targets`
-field is populated with two scrape targets; a constant one `localhost:9001` and
-an expression that ties the target to the value of
-`local.file.targets.content`.
+To wire components together, one can use the exports of one as the arguments to another by using references.
+References can only appear in components.
+
+For example, here's a component that scrapes Prometheus metrics.
+The `targets` field is populated with two scrape targets, a constant target `localhost:9001` and an expression that ties the target to the value of `local.file.targets.content`.
```river
prometheus.scrape "default" {
@@ -92,14 +79,20 @@ prometheus.scrape "default" {
}
```
-Every time the file contents change, the `local.file` will update its exports,
-so the new value will be provided 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 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.
-Each argument and exported field has an underlying [type]({{< relref "./expressions/types_and_values.md" >}}).
-River will type-check expressions before assigning a value to an attribute; the
-documentation of each component will have more information about the ways that
-you can 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 you can configure it.
-In the previous example, the contents of the `local.file.targets.content`
-expression must first be evaluated in a concrete value then type-checked and
-substituted into `prometheus.scrape.default` for it to be configured in turn.
+{{% docs/reference %}}
+[components]: "/docs/agent/ -> /docs/agent//flow/reference/components"
+[components]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/reference/components"
+[controller]: "/docs/agent/ -> /docs/agent//flow/concepts/component_controller"
+[controller]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/concepts/component_controller"
+[type]: "/docs/agent/ -> /docs/agent//flow/config-language/expressions/types_and_values"
+[type]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/config-language/expressions/types_and_values"
+{{% /docs/reference %}}
\ No newline at end of file
diff --git a/docs/sources/flow/config-language/expressions/_index.md b/docs/sources/flow/config-language/expressions/_index.md
index 7fc1363432a7..991e7c163a20 100644
--- a/docs/sources/flow/config-language/expressions/_index.md
+++ b/docs/sources/flow/config-language/expressions/_index.md
@@ -13,18 +13,20 @@ weight: 400
# Expressions
-Expressions represent or compute values that can be assigned 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][].
+Expressions may also do things like [refer to values][] exported by components, perform arithmetic, or [call functions][].
-Expressions can be used when configuring any component. As all component
-arguments have an underlying [type][], River will type-check expressions before
-assigning the result to an attribute.
-
-[refer to values]: {{< relref "./referencing_exports.md" >}}
-[call functions]: {{< relref "./function_calls.md" >}}
-[type]: {{< relref "./types_and_values.md" >}}
+You use expressions when you configure any component.
+All component arguments have an underlying [type][].
+River checks the expression type before assigning the result to an attribute.
+{{% docs/reference %}}
+[refer to values]: "/docs/agent/ -> /docs/agent//flow/config-language/expressions/referencing_exports"
+[refer to values]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/config-language/expressions/referencing_exports"
+[call functions]: "/docs/agent/ -> /docs/agent//flow/config-language/expressions/function_calls"
+[call functions]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/config-language/expressions/function_calls"
+[type]: "/docs/agent/ -> /docs/agent//flow/config-language/expressions/types_and_values"
+[type]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/config-language/expressions/types_and_values"
+{{% /docs/reference %}}
diff --git a/docs/sources/flow/config-language/expressions/function_calls.md b/docs/sources/flow/config-language/expressions/function_calls.md
index d8a6ade75048..2b773138cf71 100644
--- a/docs/sources/flow/config-language/expressions/function_calls.md
+++ b/docs/sources/flow/config-language/expressions/function_calls.md
@@ -12,24 +12,26 @@ weight: 400
---
# Function calls
-Function calls is one more River feature that lets users build richer
-expressions.
-Functions take zero or more arguments as their input and always return a single
-value as their output. Functions cannot be constructed by users, but can be
-either called from River's standard library, or when exported by a component.
+You can use River function calls to build richer expressions.
-In case a function fails, the expression will not be evaluated and an error
-will be reported.
+Functions take zero or more arguments as their input and always return a single value as their output.
+You can't construct functions. You can call functions from River's standard library or export them from a component.
+
+If a function fails, the expression isn't evaluated, and an error is reported.
## Standard library functions
-River contains a [standard library][] of useful functions. Some enable
-interaction with the host system (e.g. reading from an environment variable), or
-allow for more complex expressions (e.g. concatenating arrays or decoding JSON
-strings into objects).
+
+River contains a [standard library][] of functions.
+Some functions enable interaction with the host system, for example, reading from an environment variable.
+Some functions allow for more complex expressions, for example, concatenating arrays or decoding JSON strings into objects.
+
```river
env("HOME")
json_decode(local.file.cfg.content)["namespace"]
```
-[standard library]: {{< relref "../../reference/stdlib" >}}
+{{% docs/reference %}}
+[standard library]: "/docs/agent/ -> /docs/agent//flow/reference/stdlib"
+[standard library]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/reference/stdlib"
+{{% /docs/reference %}}
\ No newline at end of file
diff --git a/docs/sources/flow/config-language/expressions/operators.md b/docs/sources/flow/config-language/expressions/operators.md
index 73ef1868688a..309afb78ddc5 100644
--- a/docs/sources/flow/config-language/expressions/operators.md
+++ b/docs/sources/flow/config-language/expressions/operators.md
@@ -12,14 +12,14 @@ weight: 300
---
# Operators
-River uses a set of operators that most should be familiar with. All operations
-follow the standard [PEMDAS](https://en.wikipedia.org/wiki/Order_of_operations)
-rule for operator precedence.
+
+River uses a common set of operators.
+All operations follow the standard [PEMDAS][] order of mathematical operations.
## Arithmetic operators
Operator | Description
--------- | -----------
+---------|---------------------------------------------------
`+` | Adds two numbers.
`-` | Subtracts two numbers.
`*` | Multiplies two numbers.
@@ -30,29 +30,27 @@ Operator | Description
## String operators
Operator | Description
--------- | -----------
+---------|-------------------------
`+` | Concatenate two strings.
## Comparison operators
Operator | Description
--------- | -----------
+---------|---------------------------------------------------------------------
`==` | `true` when two values are equal.
-`!=` | `true` when two values are not equal.
+`!=` | `true` when two values aren't equal.
`<` | `true` when the left value is less than the right value.
`<=` | `true` when the left value is less than or equal to the right value.
`>` | `true` when the left value is greater than the right value.
`>=` | `true` when the left value is greater or equal to the right value.
-The equality operators `==` and `!=` can be applied to any operands.
+You can apply the equality operators `==` and `!=` to any operands.
-On the other hand, for the ordering operators `<` `<=` `>` and `>=` the two
-operands must both be _orderable_ and of the same type. The result of the
-comparisons are defined as follows:
+The two operands in ordering operators `<` `<=` `>` and `>=` must both be _orderable_ and of the same type.
+The results of the comparisons are:
-* Boolean values are equal if they are either both true or both false.
-* Numerical (integer and floating-point) values are orderable, in the usual
- way.
+* Boolean values are equal if they're either both true or both false.
+* Numerical (integer and floating-point) values are orderable in the usual way.
* String values are orderable lexically byte-wise.
* Objects are equal if all their fields are equal.
* Array values are equal if their corresponding elements are equal.
@@ -60,38 +58,36 @@ comparisons are defined as follows:
## Logical operators
Operator | Description
--------- | -----------
+---------|---------------------------------------------------------
`&&` | `true` when the both left _and_ right value are `true`.
-`\|\|` | `true` when the either left _or_ right value are `true`.
+`\|\|` | `true` when the either left _or_ right value are `true`.
`!` | Negates a boolean value.
Logical operators apply to boolean values and yield a boolean result.
## Assignment operator
+
River uses `=` as its assignment operator.
An assignment statement may only assign a single value.
-In assignments, each value must be _assignable_ to the attribute or object key
-to which it is being assigned.
+Each value must be _assignable_ to the attribute or object key.
-* The `null` value can be assigned to any attribute.
-* Numerical, string, boolean, array, function, capsule and object types are
- assignable to attributes of the corresponding type.
-* Numbers can be assigned to string attributes with an implicit conversion.
-* Strings can be assigned to numerical attributes, provided that they represent
- a number.
-* Blocks are not assignable.
+* You can assign `null` to any attribute.
+* You can assign numerical, string, boolean, array, function, capsule, and object types to attributes of the corresponding type.
+* You can assign numbers to string attributes with an implicit conversion.
+* You can assign strings to numerical attributes if they represent a number.
+* You can't assign blocks.
## Brackets
Brackets | Description
--------- | -----------
+---------|------------------------------------
`{ }` | Defines blocks and objects.
`( )` | Groups and prioritizes expressions.
`[ ]` | Defines arrays.
-In the following example we can see the use of curly braces and square brackets
-to define an object and an array.
+The following example uses curly braces and square brackets to define an object and an array.
+
```river
obj = { app = "agent", namespace = "dev" }
arr = [1, true, 7 * (1+1), 3]
@@ -100,15 +96,14 @@ arr = [1, true, 7 * (1+1), 3]
## Access operators
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.
-Square brackets can be used to access zero-indexed array indices as well as
-object fields by enclosing the field name in double quotes.
-The dot operator can be used to access both object fields (without double
-quotes) and component exports.
+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 object fields without double quotes and component exports.
+
```river
obj["app"]
arr[1]
@@ -117,8 +112,8 @@ obj.app
local.file.token.content
```
-If the `[ ]` operator is used to access a member of an object where the member
-doesn't exist, the resulting value is `null`.
+If you use the `[ ]` operator to access a member of an object where the member doesn't exist, the resulting value is `null`.
+
+If you use the `.` operator to access a named member of an object where the named member doesn't exist, an error is generated.
-If the `.` operator is used to access a named member of an object where the
-named member doesn't exist, an error is generated.
+[PEMDAS]: https://en.wikipedia.org/wiki/Order_of_operations
diff --git a/docs/sources/flow/config-language/expressions/referencing_exports.md b/docs/sources/flow/config-language/expressions/referencing_exports.md
index ed35c3ec7f88..5923d6bd89c0 100644
--- a/docs/sources/flow/config-language/expressions/referencing_exports.md
+++ b/docs/sources/flow/config-language/expressions/referencing_exports.md
@@ -12,24 +12,23 @@ weight: 200
---
# Referencing component exports
-Referencing exports is what enables River to dynamically configure and connect
-components 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, building a dependency relationship between the two.
-Such references can only appear as part of another component's arguments or a
-config block's fields. That means that components cannot reference themselves.
+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 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.
+Components can't reference themselves.
## Using references
-These references are built by combining the component's name, label and named
-export with dots.
-For example, the contents of a file exported by the `local.file` component
-labeled `target` might be referenced as `local.file.target.content`.
-Similarly, a `prometheus.remote_write` component instance labeled `onprem` will
-expose its receiver for metrics on `prometheus.remote_write.onprem.receiver`.
+You build references by combining the component's name, label, and named export with dots.
+
+For example, you can reference the contents of a file exported by the `local.file` component labeled `target` as `local.file.target.content`.
+Similarly, a `prometheus.remote_write` component instance labeled `onprem` exposes its receiver for metrics on `prometheus.remote_write.onprem.receiver`.
+
+The following example shows some references.
-Let's see that in action:
```river
local.file "target" {
filename = "/etc/agent/target"
@@ -47,18 +46,15 @@ prometheus.remote_write "onprem" {
}
```
-In the previous example, we managed to wire together a very simple pipeline by
-writing a few River expressions.
-
-
-
-
+In the preceding example, you wired together a very simple pipeline by writing a few River expressions.
-As with all expressions, once the value is resolved, it must match the [type][]
-of the attribute being assigned to. While users can only configure attributes
-using the basic River types, the exports of components can also take on special
-internal River types such as Secrets or Capsules, which expose different
-functionality.
+
+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.
-[type]: {{< relref "./types_and_values.md" >}}
+{{% docs/reference %}}
+[type]: "/docs/agent/ -> /docs/agent//flow/config-language/expressions/types_and_values"
+[type]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/config-language/expressions/types_and_values"
+{{% /docs/reference %}}
\ No newline at end of file
diff --git a/docs/sources/flow/config-language/expressions/types_and_values.md b/docs/sources/flow/config-language/expressions/types_and_values.md
index eedda9445a7b..9a641c34d286 100644
--- a/docs/sources/flow/config-language/expressions/types_and_values.md
+++ b/docs/sources/flow/config-language/expressions/types_and_values.md
@@ -13,45 +13,42 @@ weight: 100
# Types and values
-## Types
-
River uses the following types for its values:
* `number`: Any numeric value, like `3` or `3.14`.
* `string`: A sequence of Unicode characters representing text, like `"Hello, world!"`.
* `bool`: A boolean value, either `true` or `false`.
-* `array`: A sequence of values, like `[1, 2, 3]`. Elements within the
- list are indexed by whole numbers, starting with zero.
-* `object`: A group of values which are identified by named labels, like
- `{ name = "John" }`.
-* `function`: A value representing a routine which can be executed with
- arguments to compute another value, like `env("HOME")`. Functions take zero
- or more arguments as input and always return a single value as output.
+* `array`: A sequence of values, like `[1, 2, 3]`. Elements within the list are indexed by whole numbers, starting with zero.
+* `object`: A group of values identified by named labels, like `{ name = "John" }`.
+* `function`: A value representing a routine that runs with arguments to compute another value, like `env("HOME")`.
+ Functions take zero or more arguments as input and always return a single value as output.
* `null`: A type that has no value.
-### Naming convention
+## Naming convention
-In addition to the types above, [component reference][] documentation will use
-the following conventions for referring to types:
+In addition to the preceding types, the [component reference][] documentation uses the following conventions for referring to types:
* `any`: A value of any type.
-* `map(T)`: an `object` where the value type is `T`. For example, `map(string)`
- is an object where all the values are strings. The key type of an object is
- always a string, or an identifier which is converted into a string.
-* `list(T)`: an `array` where the value type is `T`. For example, `list(string)`
- is an array where all the values are strings.
-* `duration`: a `string` denoting a duration of time, such as `"1d"`, `"1h30m"`,
- `"10s"`. Valid units are `d` (for days), `h` (for hours), `m` (for minutes),
- `s` (for seconds), `ms` (for milliseconds), `ns` (for nanoseconds). Values of
- descending units can be combined to add their values together; `"1h30m"` is
- the same as `"90m"`.
-
-[component reference]: {{< relref "../../reference/components" >}}
+* `map(T)`: an `object` with the value type `T`.
+ For example, `map(string)` is an object where all the values are strings.
+ The key type of an object is always a string or an identifier converted into a string.
+* `list(T)`: an `array` with the value type`T`.
+ For example, `list(string)` is an array where all the values are strings.
+* `duration`: a `string` denoting a duration of time, such as `"1d"`, `"1h30m"`, `"10s"`.
+ Valid units are:
+
+ * `d` for days.
+ * `h` for hours.
+ * `m` for minutes.
+ * `s` for seconds.
+ * `ms` for milliseconds.
+ * `ns` for nanoseconds.
+
+ You can combine values of descending units to add their values together. For example, `"1h30m"` is the same as `"90m"`.
## Numbers
-River handles integers, unsigned integers and floating-point values as a single
-'number' type which simplifies writing and reading River configuration files.
+River handles integers, unsigned integers, and floating-point values as a single 'number' type, simplifying writing and reading River configuration files.
```river
3 == 3.00 // true
@@ -62,54 +59,52 @@ River handles integers, unsigned integers and floating-point values as a single
## Strings
-Strings are represented by sequences of Unicode characters surrounded by double
-quotes `""`:
+Strings are represented by sequences of Unicode characters surrounded by double quotes `""`.
```river
"Hello, world!"
```
A `\` in a string starts an escape sequence to represent a special character.
-The supported escape sequences are as follows:
-
-| Sequence | Replacement |
-| -------- | ----------- |
-| `\\` | The `\` character `U+005C` |
-| `\a` | The alert or bell character `U+0007` |
-| `\b` | The backspace character `U+0008` |
-| `\f` | The formfeed character `U+000C` |
-| `\n` | The newline character `U+000A` |
-| `\r` | The carriage return character `U+000D` |
-| `\t` | The horizontal tab character `U+0009` |
-| `\v` | The vertical tab character `U+000B` |
-| `\'` | The `'` character `U+0027` |
-| `\"` | The `"` character `U+0022`, which prevents terminating the string |
-| `\NNN` | A literal byte (NNN is three octal digits) |
-| `\xNN` | A literal byte (NN is two hexadecimal digits) |
-| `\uNNNN` | A Unicode character from the basic multilingual plane (NNNN is four hexadecimal digits) |
-| `\UNNNNNNNN` | A Unicode character from supplementary planes (NNNNNNNN is eight hexadecimal digits) |
+The following table shows the supported escape sequences.
+
+| Sequence | Replacement |
+|--------------|-----------------------------------------------------------------------------------------|
+| `\\` | The `\` character `U+005C` |
+| `\a` | The alert or bell character `U+0007` |
+| `\b` | The backspace character `U+0008` |
+| `\f` | The formfeed character `U+000C` |
+| `\n` | The newline character `U+000A` |
+| `\r` | The carriage return character `U+000D` |
+| `\t` | The horizontal tab character `U+0009` |
+| `\v` | The vertical tab character `U+000B` |
+| `\'` | The `'` character `U+0027` |
+| `\"` | The `"` character `U+0022`, which prevents terminating the string |
+| `\NNN` | A literal byte (NNN is three octal digits) |
+| `\xNN` | A literal byte (NN is two hexadecimal digits) |
+| `\uNNNN` | A Unicode character from the basic multilingual plane (NNNN is four hexadecimal digits) |
+| `\UNNNNNNNN` | A Unicode character from supplementary planes (NNNNNNNN is eight hexadecimal digits) |
## Raw strings
Raw strings are represented by sequences of Unicode characters surrounded by backticks ``` `` ```.
-Raw strings do not support any escape sequences:
+Raw strings don't support any escape sequences.
```river
`Hello, "world"!`
```
-Within the backticks, any character may appear except a backtick. A backtick
-can be included by concatenating a double quoted string that contains a
-backtick using `+`.
+Within the backticks, any character may appear except a backtick.
+You can include a backtick by concatenating a double-quoted string that contains a backtick using `+`.
-A multiline raw string is interpreted exactly as written:
+A multiline raw string is interpreted exactly as written.
```river
`Hello,
"world"!`
```
-is interpretted as a string with the value:
+The preceding multiline raw string is interpreted as a string with the following value.
```string
Hello,
@@ -122,16 +117,14 @@ Bools are represented by the symbols `true` and `false`.
## Arrays
-Array values are constructed by a sequence of comma separated values surrounded
-by square brackets `[]`:
+You construct arrays with a sequence of comma-separated values surrounded by square brackets `[]`.
```river
[0, 1, 2, 3]
```
-Values in array elements may be placed on separate lines for readability. A
-comma after the final value must be present if the closing bracket `]`
-is on a different line as the final value:
+You can place values in array elements on separate lines for readability.
+A comma after the final value must be present if the closing bracket `]` is on a different line than the final value.
```river
[
@@ -143,8 +136,7 @@ is on a different line as the final value:
## Objects
-Object values are constructed by a sequence of comma separated key-value pairs
-surrounded by curly braces `{}`:
+You construct objects with a sequence of comma-separated key-value pairs surrounded by curly braces `{}`.
```river
{
@@ -153,15 +145,13 @@ surrounded by curly braces `{}`:
}
```
-A comma after the final key-value pair may be omitted if the closing curly
-brace `}` is on the same line as the final pair:
+You can omit the comma after the final key-value pair if the closing curly brace `}` is on the same line as the final pair.
```river
{ name = "John" }
```
-If the key is not a valid identifier, it must be wrapped in double quotes like
-a string:
+If the key isn't a valid identifier, you must wrap it in double quotes like a string.
```river
{
@@ -171,52 +161,43 @@ a string:
}
```
-> **NOTE**: Be careful not to confuse objects with blocks.
->
-> An _object_ is a value assigned to an [Attribute][Attributes], where
-> commas **must** be provided between key-value pairs on separate lines.
->
-> A [Block][Blocks] is a named structural element composed of multiple attributes,
-> where commas **must not** be provided between attributes.
+{{% admonition type="Note" %}}
+Don't confuse objects with blocks.
+
+* An _object_ is a value assigned to an [Attribute][]. You **must** use commas between key-value pairs on separate lines.
+* A [Block][] is a named structural element composed of multiple attributes. You **must not** use commas between attributes.
-[Attributes]: {{< relref "../syntax.md#Attributes" >}}
-[Blocks]: {{< relref "../syntax.md#Blocks" >}}
+[Attribute]: {{< relref "../syntax.md#Attributes" >}}
+[Block]: {{< relref "../syntax.md#Blocks" >}}
+{{% /admonition %}}
## Functions
-Function values cannot be constructed by users, but can be called from the
-standard library or when exported by a component.
+You can't construct function values. You can call functions from the standard library or export them from a component.
## Null
The null value is represented by the symbol `null`.
-## Special Types
+## Special types
#### Secrets
-A `secret` is a special type of string which is never displayed to the user.
-`string` values may be assigned to an attribute expecting a `secret`, but never
-the inverse; it is not possible to convert a secret to a string or assign a
-secret to an attribute expecting a string.
+A `secret` is a special type of string that's never displayed to the user.
+You can assign `string` values to an attribute expecting a `secret`, but never the inverse.
+It's impossible to convert a secret to a string or assign a secret to an attribute expecting a string.
#### Capsules
-River has a special type called a `capsule`, which represents a category of
-_internal_ types used by Flow. Each capsule type has a unique name and will be
-represented to the user as `capsule("SOME_INTERNAL_NAME")`.
-Capsule values cannot be constructed by the user, but can be used in
-expressions as any other type. Capsules are not inter-compatible and an
-attribute expecting a capsule can only be given a capsule of the same internal
-type. That means, if an attribute expects a `capsule("prometheus.Receiver")`,
-it can only be assigned a `capsule("prometheus.Receiver")` type. The specific
-type of capsule expected is explicitly documented for any component which uses
-or exports them.
-
-In the following example, the `prometheus.remote_write` component exports a
-`receiver`, which is a `capsule("prometheus.Receiver")` type. This can then be
-used in the `forward_to` attribute of `prometheus.scrape`, which
-expects an array of `capsule("prometheus.Receiver")`s:
+A `capsule` is a special type that represents a category of _internal_ types used by {{< param "PRODUCT_NAME" >}}.
+Each capsule type has a unique name and is represented to the user as `capsule("")`.
+You can't construct capsule values. You can use capsules in expressions as any other type.
+Capsules aren't inter-compatible, and an attribute expecting a capsule can only be given a capsule of the same internal type.
+If an attribute expects a `capsule("prometheus.Receiver")`, you can only assign a `capsule("prometheus.Receiver")` type.
+The specific type of capsule expected is explicitly documented for any component that uses or exports them.
+
+In the following example, the `prometheus.remote_write` component exports a `receiver`, which is a `capsule("prometheus.Receiver")` type.
+You can use this capsule in the `forward_to` attribute of `prometheus.scrape`, which expects an array of `capsule("prometheus.Receiver")`.
```river
prometheus.remote_write "default" {
@@ -230,3 +211,8 @@ prometheus.scrape "default" {
forward_to = [prometheus.remote_write.default.receiver]
}
```
+
+{{% docs/reference %}}
+[type]: "/docs/agent/ -> /docs/agent//flow/reference/components"
+[type]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/reference/components"
+{{% /docs/reference %}}
\ No newline at end of file
diff --git a/docs/sources/flow/config-language/files.md b/docs/sources/flow/config-language/files.md
index 39d6f5a144b3..2b5e12f7b6e1 100644
--- a/docs/sources/flow/config-language/files.md
+++ b/docs/sources/flow/config-language/files.md
@@ -12,10 +12,9 @@ weight: 100
---
# Files
-River files are plaintext files with the `.river` file extension. Each River
-file may be referred to as a "configuration file," or a "River configuration."
-River files are required to be UTF-8 encoded, and are permitted to contain
-Unicode characters. River files can use both Unix-style line endings (LF) and
-Windows-style line endings (CRLF), but formatters may replace all line endings
-with Unix-style ones.
+River files are plain text files with the `.river` file extension.
+You can refer to each River file as a "configuration file" or a "River configuration."
+
+River files must be UTF-8 encoded and can contain Unicode characters.
+River files can use Unix-style line endings (LF) and Windows-style line endings (CRLF), but formatters may replace all line endings with Unix-style ones.
diff --git a/docs/sources/flow/config-language/syntax.md b/docs/sources/flow/config-language/syntax.md
index 284c2e63079b..e085ca967007 100644
--- a/docs/sources/flow/config-language/syntax.md
+++ b/docs/sources/flow/config-language/syntax.md
@@ -13,32 +13,28 @@ weight: 200
# Syntax
-The River syntax is designed to be easy to read and write. Essentially, there
-are just two high-level elements to it: _Attributes_ and _Blocks_.
+The River syntax is easy to read and write. It has only two high-level elements, _Attributes_ and _Blocks_.
River is a _declarative_ language used to build programmable pipelines.
-As such, the ordering of blocks and attributes within the River configuration
-file is not important; the language will consider all direct and indirect
-dependencies between elements to determine their relationships.
+The order of blocks and attributes within the River configuration file isn't important.
+The language considers all direct and indirect dependencies between elements to determine their relationships.
## Comments
-River configuration files support single-line `//` as well as block `/* */`
-comments.
+River configuration files support single-line `//` and block `/* */` comments.
## Identifiers
-River considers an identifier as valid if it consists of one or more UTF-8
-letters (A through Z, both upper- and lower-case), digits or underscores, but
-doesn't start with a digit.
+River considers an identifier as valid if it consists of one or more UTF-8 letters (A through Z, both upper- and lower-case),
+digits or underscores, but doesn't start with a digit.
## Attributes and Blocks
### Attributes
-_Attributes_ are used to configure individual settings. They always take the
-form of `ATTRIBUTE_NAME = ATTRIBUTE_VALUE`. They can appear either as
-top-level elements or nested within blocks.
+You use _Attributes_ to configure individual settings.
+They always take the form of `ATTRIBUTE_NAME = ATTRIBUTE_VALUE`.
+They can appear either as top-level elements or nested within blocks.
The following example sets the `log_level` attribute to `"debug"`.
@@ -46,23 +42,22 @@ The following example sets the `log_level` attribute to `"debug"`.
log_level = "debug"
```
-The `ATTRIBUTE_NAME` must be a valid River [identifier](#identifiers).
+The `ATTRIBUTE_NAME` must be a valid River [identifier][].
-The `ATTRIBUTE_VALUE` can be either a constant value of a valid River
-[type]({{< relref "./expressions/types_and_values.md" >}}) (eg. string,
-boolean, number) or an [_expression_]({{< relref "./expressions/_index.md" >}})
-to represent or compute more complex attribute values.
+The `ATTRIBUTE_VALUE` can be either a constant value of a valid River [type][] (for example, a string, boolean, number),
+or an [_expression_][expression] to represent or compute more complex attribute values.
### Blocks
-_Blocks_ are used to configure the {{< param "PRODUCT_ROOT_NAME" >}}'s behavior as well as {{< param "PRODUCT_NAME" >}} components by
-grouping any number of attributes or nested blocks using curly braces.
-Blocks have a _name_, an optional _label_ and a body that contains any number
-of arguments and nested unlabeled blocks.
+You use _Blocks_ to configure the {{< param "PRODUCT_ROOT_NAME" >}}'s behavior as well as {{< param "PRODUCT_NAME" >}}
+components by grouping any number of attributes or nested blocks using curly braces.
+Blocks have a _name_, an optional _label_ and a body that contains any number of arguments and nested unlabeled blocks.
-Some blocks support being defined more than once.
+Some blocks can be defined more than once.
-#### Pattern for creating an unlabeled block
+#### Examples
+
+You can use the following pattern to create an unlabeled block.
```river
BLOCK_NAME {
@@ -75,7 +70,7 @@ BLOCK_NAME {
}
```
-#### Pattern for creating a labeled block
+You can use the following pattern to create a labeled block
```river
// Pattern for creating a labeled block:
@@ -91,16 +86,14 @@ BLOCK_NAME "BLOCK_LABEL" {
#### Block naming rules
-The `BLOCK_NAME` has to be recognized by Flow as either a valid component
-name or a special block for configuring global settings. If the `BLOCK_LABEL`
-has to be set, it must be a valid River [identifier](#identifiers) wrapped in
-double quotes. In these cases the label will be used to disambiguate between
-multiple top-level blocks of the same name.
+The `BLOCK_NAME` has to be recognized by {{< param "PRODUCT_NAME" >}} as either a valid component name or a special block for configuring global settings.
+If the `BLOCK_LABEL` must be set, it must be a valid River [identifier][] wrapped in double quotes.
+In these cases, you use the label to disambiguate between multiple top-level blocks of the same name.
+
+The following snippet defines a block named `local.file` with its label set to "token".
+The block's body sets `filename` to the content of the `TOKEN_FILE_PATH` environment variable by using an expression,
+and the `is_secret` attribute is set to the boolean `true`, marking the file content as sensitive.
-The following snippet defines a block named `local.file` with its label set to
-"token". The block's body sets `filename` to the content of the `TOKEN_FILE_PATH`
-environment variable by using an expression and the `is_secret` attribute is
-set to the boolean `true`, marking the file content as sensitive.
```river
local.file "token" {
filename = env("TOKEN_FILE_PATH") // Use an expression to read from an env var.
@@ -110,9 +103,17 @@ local.file "token" {
## Terminators
-All block and attribute definitions are followed by a newline, which River
-calls a _terminator_, as it terminates the current statement.
+All block and attribute definitions are followed by a newline, which River calls a _terminator_, as it terminates the current statement.
+
+A newline is treated as a terminator when it follows any expression, `]`, `)`, or `}`.
+River ignores other newlines and you can can enter as many newlines as you want.
+
+[identifier]: #identifiers
+[identifier]: #identifiers
-A newline is treated as terminator when it follows any expression, `]`,
-`)` or `}`. Other newlines are ignored by River and and a user can enter as many
-newlines as they want.
+{{% docs/reference %}}
+[expression]: "/docs/agent/ -> /docs/agent//flow/config-language/expressions"
+[expression]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/config-language/expressions"
+[type]: "/docs/agent/ -> /docs/agent//flow/config-language/expressions/types_and_values"
+[type]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/config-language/expressions/types_and_values"
+{{% /docs/reference %}}
\ No newline at end of file
diff --git a/docs/sources/flow/getting-started/migrating-from-prometheus.md b/docs/sources/flow/getting-started/migrating-from-prometheus.md
index 75ca9b20935f..dbb88055b64e 100644
--- a/docs/sources/flow/getting-started/migrating-from-prometheus.md
+++ b/docs/sources/flow/getting-started/migrating-from-prometheus.md
@@ -229,7 +229,7 @@ Review the following checklist:
* The following configurations aren't available for conversion to {{< param "PRODUCT_NAME" >}}: `rule_files`, `alerting`, `remote_read`, `storage`, and `tracing`.
Any additional unsupported features are returned as errors during conversion.
-* Check if you are using any extra command line arguments with Prometheus that are not present in your configuration file. For example, `--web.listen-address`.
+* Check if you are using any extra command line arguments with Prometheus that aren't present in your configuration file. For example, `--web.listen-address`.
* Metamonitoring metrics exposed by {{< param "PRODUCT_NAME" >}} usually match Prometheus metamonitoring metrics but will use a different name.
Make sure that you use the new metric names, for example, in your alerts and dashboards queries.
* The logs produced by {{< param "PRODUCT_NAME" >}} differ from those produced by Prometheus.
diff --git a/docs/sources/flow/getting-started/migrating-from-static.md b/docs/sources/flow/getting-started/migrating-from-static.md
index 9ff6b56cc8e1..6393d5a181ae 100644
--- a/docs/sources/flow/getting-started/migrating-from-static.md
+++ b/docs/sources/flow/getting-started/migrating-from-static.md
@@ -305,14 +305,14 @@ After the configuration is converted, review the {{< param "PRODUCT_NAME" >}} co
Review the following checklist:
-* The following configuration options are not available for conversion to {{< param "PRODUCT_NAME" >}}: [Integrations next][], [Traces][], and [Agent Management][].
+* The following configuration options aren't available for conversion to {{< param "PRODUCT_NAME" >}}: [Integrations next][], [Traces][], and [Agent Management][].
Any additional unsupported features are returned as errors during conversion.
* There is no gRPC server to configure for {{< param "PRODUCT_NAME" >}}, as any non-default configuration will show as unsupported during the conversion.
* Check if you are using any extra command line arguments with Static that aren't present in your configuration file. For example, `-server.http.address`.
-* Check if you are using any environment variables in your [Static] configuration.
- These will be evaluated during conversion and you may want to replace them with the {{< param "PRODUCT_NAME" >}} Standard library [env] function after conversion.
-* Review additional [Prometheus Limitations] for limitations specific to your [Metrics] config.
-* Review additional [Promtail Limitations] for limitations specific to your [Logs] config.
+* Check if you are using any environment variables in your [Static][] configuration.
+ These will be evaluated during conversion and you may want to replace them with the {{< param "PRODUCT_NAME" >}} Standard library [env][] function after conversion.
+* Review additional [Prometheus Limitations][] for limitations specific to your [Metrics][] configuration.
+* Review additional [Promtail Limitations][] for limitations specific to your [Logs][] configuration.
* The logs produced by {{< param "PRODUCT_NAME" >}} mode will differ from those produced by Static.
* {{< param "PRODUCT_ROOT_NAME" >}} exposes the {{< param "PRODUCT_NAME" >}} [UI][].
-
-