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/configuration_language.md b/docs/sources/flow/concepts/configuration_language.md index 91bd5af6dc4d..46754973cf2c 100644 --- a/docs/sources/flow/concepts/configuration_language.md +++ b/docs/sources/flow/concepts/configuration_language.md @@ -13,9 +13,7 @@ weight: 400 # Configuration language concepts -The {{< param "PRODUCT_NAME" >}} _configuration language_ refers to the language used in configuration files that 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" { @@ -32,7 +30,7 @@ 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 quickly evaluate changes. * _Simple_: The configuration language must be easy to read and write to minimize the learning curve. @@ -40,37 +38,37 @@ River was designed with the following requirements in mind: ## 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 you 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. +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 more complex expressions, such as: +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 (for example, `local.file`), +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. ## Blocks -_Blocks_ are used to configure components and groups of attributes. +You use _Blocks_ to configure components and groups of attributes. Each block can contain any number of attributes or nested blocks. ```river @@ -81,7 +79,7 @@ prometheus.remote_write "default" { } ``` -This file has two blocks: +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"`. @@ -90,7 +88,7 @@ This file has two blocks: ## 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 5e1b72eeee13..3bd3fcbb4ff3 100644 --- a/docs/sources/flow/concepts/modules.md +++ b/docs/sources/flow/concepts/modules.md @@ -13,46 +13,48 @@ weight: 300 # Modules -_Modules_ are a way to create {{< param "PRODUCT_NAME" >}} configurations which can be loaded as a component. +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 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. +* _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](#module-loaders) 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 that 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 the following: +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][]. +{{% 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. -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: +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" { @@ -72,7 +74,7 @@ module.string "my_module" { ## Example module -This example module manages a pipeline that filters out debug- and info-level log lines that 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 that specifies where filtered @@ -105,7 +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" { diff --git a/docs/sources/flow/config-language/_index.md b/docs/sources/flow/config-language/_index.md index 7b1c76e6bd69..929518f47c5e 100644 --- a/docs/sources/flow/config-language/_index.md +++ b/docs/sources/flow/config-language/_index.md @@ -42,10 +42,8 @@ BLOCK_NAME { } ``` -> River 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. - -> For historical context on River was introduced, you can read the original [RFC][]. +[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. * 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. diff --git a/docs/sources/flow/config-language/components.md b/docs/sources/flow/config-language/components.md index 84fd7860b0e2..6691b0cf091e 100644 --- a/docs/sources/flow/config-language/components.md +++ b/docs/sources/flow/config-language/components.md @@ -17,12 +17,11 @@ 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. -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. +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]({{< relref "../reference/components/_index.md" >}}) are created by defining a top-level River block. +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 @@ -33,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 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 they 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`, -which 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 or not. ```river local.file "targets" { @@ -80,11 +79,15 @@ prometheus.scrape "default" { } ``` -Every time the file contents change, the `local.file` updates its exports. The new value is provided to the `prometheus.scrape` targets field. +Every time the file contents change, the `local.file` updates its exports. The new value is given to the `prometheus.scrape` targets field. -Each argument and exported field has an underlying [type]({{< relref "./expressions/types_and_values.md" >}}). +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]({{< relref "../reference/components/_index.md" >}}) provides more information about the ways that you can wire components together. +The documentation of each [component][components] provides more information about the ways that you can wire components together. -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 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. + +[components]: {{< relref "../reference/components/_index.md" >}} +[controller]: {{< relref "../concepts/component_controller.md" >}} +[type]: {{< relref "./expressions/types_and_values.md" >}} diff --git a/docs/sources/flow/config-language/expressions/_index.md b/docs/sources/flow/config-language/expressions/_index.md index cadec3aad85a..b2b65c859a13 100644 --- a/docs/sources/flow/config-language/expressions/_index.md +++ b/docs/sources/flow/config-language/expressions/_index.md @@ -13,13 +13,14 @@ weight: 400 # Expressions -Expressions represent or compute values that can be assigned to attributes within a configuration. +Expressions represent or compute values that 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 can be used when configuring any component. -As all component arguments have an underlying [type][], River type-checks expressions before assigning the result to an attribute. +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. [refer to values]: {{< relref "./referencing_exports.md" >}} [call functions]: {{< relref "./function_calls.md" >}} diff --git a/docs/sources/flow/config-language/expressions/operators.md b/docs/sources/flow/config-language/expressions/operators.md index 180e6fec5861..768b95e2cedb 100644 --- a/docs/sources/flow/config-language/expressions/operators.md +++ b/docs/sources/flow/config-language/expressions/operators.md @@ -13,7 +13,7 @@ weight: 300 # Operators -River uses a set of operators that most should be familiar with. +River uses a common set of operators. All operations follow the standard [PEMDAS][] rule for operator precedence. ## Arithmetic operators @@ -44,10 +44,10 @@ Operator | Description `>` | `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 results 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're either both true or both false. * Numerical (integer and floating-point) values are orderable in the usual way. @@ -72,11 +72,11 @@ River uses `=` as its assignment operator. An assignment statement may only assign a single value. 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 aren't 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 @@ -86,7 +86,7 @@ Brackets | Description `( )` | Groups and prioritizes expressions. `[ ]` | Defines arrays. -In the following example, you 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" } diff --git a/docs/sources/flow/config-language/expressions/referencing_exports.md b/docs/sources/flow/config-language/expressions/referencing_exports.md index 28f51b4bc7de..d833b7b99126 100644 --- a/docs/sources/flow/config-language/expressions/referencing_exports.md +++ b/docs/sources/flow/config-language/expressions/referencing_exports.md @@ -18,16 +18,16 @@ While components can work in isolation, they're more useful when one component's 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. -That means that components can't reference themselves. +Components can't reference themselves. ## Using references -These references are built by combining the component's name, label, and named export with dots. +You build references 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`. +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 this. +The following example shows some references. ```river local.file "target" { @@ -46,11 +46,9 @@ prometheus.remote_write "onprem" { } ``` -In the previous example, you wired 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. -

-Flow of example pipeline -

+![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. While you can only configure attributes using the basic River types, 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 96af6a5ab9b8..bc4268dce9d8 100644 --- a/docs/sources/flow/config-language/expressions/types_and_values.md +++ b/docs/sources/flow/config-language/expressions/types_and_values.md @@ -35,8 +35,16 @@ In addition to the preceding types, the [component reference][] documentation us * `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"`. + 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"`. [component reference]: {{< relref "../../reference/components" >}} @@ -89,7 +97,7 @@ Raw strings don't support any escape sequences: ``` 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 `+`. +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. @@ -117,8 +125,8 @@ Array values are constructed by a sequence of comma-separated values surrounded [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 than 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 [ @@ -130,7 +138,7 @@ A comma after the final value must be present if the closing bracket `]` is on a ## Objects -Object values are constructed by a sequence of comma-separated key-value pairs surrounded by curly braces `{}`: +You construct object values with a sequence of comma-separated key-value pairs surrounded by curly braces `{}`. ```river { @@ -139,13 +147,13 @@ Object values are constructed by a sequence of comma-separated key-value pairs s } ``` -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 must wrap it in double quotes like a string. ```river { @@ -155,24 +163,26 @@ If the key is not a valid identifier, it must be wrapped in double quotes like a } ``` -> **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][Attributes]. You **must** use commas between key-value pairs on separate lines. + +A [Block][Blocks] is a named structural element composed of multiple attributes. You **must not** use commans between attributes. [Attributes]: {{< relref "../syntax.md#Attributes" >}} [Blocks]: {{< relref "../syntax.md#Blocks" >}} +{{% /admonition %}} ## Functions -Function values can't be constructed by users but can be called from the standard library or when it's exported by a component. +You can't construct function values. You can call functions from the standard library or you can export them from a component. ## Null The null value is represented by the symbol `null`. -## Special Types +## Special types #### Secrets @@ -182,15 +192,15 @@ It's impossible to convert a secret to a string or assign a secret to an attribu #### Capsules -River has a special type called a `capsule`, which 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("SOME_INTERNAL_NAME")`. -Capsule values can't be constructed by the user, but can be used in expressions as any other type. +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. -That means, if an attribute expects a `capsule("prometheus.Receiver")`, it can only be assigned a `capsule("prometheus.Receiver")` type. +That means, if an attribute expects a `capsule("prometheus.Receiver")`, it 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. -This can then be used in the `forward_to` attribute of `prometheus.scrape`, which expects an array of `capsule("prometheus.Receiver")`s: +You can use this capsule in the `forward_to` attribute of `prometheus.scrape`, which expects an array of `capsule("prometheus.Receiver")`s: ```river prometheus.remote_write "default" { diff --git a/docs/sources/flow/config-language/files.md b/docs/sources/flow/config-language/files.md index b1e6acf4f0e5..b07af903205e 100644 --- a/docs/sources/flow/config-language/files.md +++ b/docs/sources/flow/config-language/files.md @@ -13,7 +13,7 @@ weight: 100 # Files -River files are plaintext files with the `.river` file extension. +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. diff --git a/docs/sources/flow/config-language/syntax.md b/docs/sources/flow/config-language/syntax.md index 874667c35f16..95a0a911d4c2 100644 --- a/docs/sources/flow/config-language/syntax.md +++ b/docs/sources/flow/config-language/syntax.md @@ -84,8 +84,8 @@ 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. +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](#identifiers) wrapped in double quotes. In these cases, the label is used 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".