[release/v1.2] Clarify the need for capture groups in stage.replace (#…

…1507)

Co-authored-by: Clayton Cornell <[email protected]>
Co-authored-by: Paulin Todev <[email protected]>

docs/sources/reference/components/loki/loki.process.md

@@ -1028,21 +1028,23 @@ The following arguments are supported:
 
 | Name         | Type     | Description                                                     | Default | Required |
 | ------------ | -------- | --------------------------------------------------------------- | ------- | -------- |
-| `expression` | `string` | Name from extracted data to use for the log entry.              |         | yes      |
+| `expression` | `string` | A RE2 regular expression containing capture groups.            |         | yes      |
 | `source`     | `string` | Source of the data to parse. If empty, it uses the log message. |         | no       |
 | `replace`    | `string` | Value replaced by the capture group.                            |         | no       |
 
+Each capture group and named capture group in `expression` is replaced with the value given in `replace`.
+
+`expression` must contain valid RE2 regular expression capture groups.
+You can also name some groups using syntax such as `(?P<name>re)`.
+If any of the capture groups are named, their values will be set into the shared extracted map under the name of the regular expression group.
 
 The `source` field defines the source of data to parse using `expression`.
 When `source` is missing or empty, the stage parses the log line itself, but it can also be used to parse a previously extracted value.
 The replaced value is assigned back to the `source` key.
 
-The `expression` must be a valid RE2 regex.
-Every named capture group `(?P<name>re)` is set into the extracted map with its name.
-
 Because of how {{< param "PRODUCT_NAME" >}} syntax treats backslashes in double-quoted strings, note that all backslashes in a regex expression must be escaped like `"\\w*"`.
 
-Let's see how this works with the following log line and stage. Since `source` is omitted, the replacement occurs  on the log line itself.
+Let's see how this works with the following log line and stage. Since `source` is omitted, the replacement occurs on the log line itself.
 
 ```
 2023-01-01T01:00:00.000000001Z stderr P i'm a log message who has sensitive information with password xyz!