From 59f0dfef727af20dffd180e915ebaa606cb3b67a Mon Sep 17 00:00:00 2001
From: Clayton Cornell <clayton.cornell@grafana.com>
Date: Fri, 31 Jan 2025 13:35:39 -0800
Subject: [PATCH] First linting pass through some loki components

---
 .../reference/components/local/local.file.md  |    2 +-
 .../reference/components/loki/loki.echo.md    |   14 +-
 .../reference/components/loki/loki.process.md | 1277 ++++++++---------
 .../reference/components/loki/loki.relabel.md |   42 +-
 .../components/loki/loki.rules.kubernetes.md  |  101 +-
 5 files changed, 708 insertions(+), 728 deletions(-)

diff --git a/docs/sources/reference/components/local/local.file.md b/docs/sources/reference/components/local/local.file.md
index cdd8d866ea..453f6706ef 100644
--- a/docs/sources/reference/components/local/local.file.md
+++ b/docs/sources/reference/components/local/local.file.md
@@ -25,7 +25,7 @@ local.file "<LABEL>" {
 
 ## Arguments
 
-The following arguments are supported:
+You can use the following arguments with `local.file`:
 
 Name             | Type       | Description                                         | Default      | Required
 -----------------|------------|-----------------------------------------------------|--------------|---------
diff --git a/docs/sources/reference/components/loki/loki.echo.md b/docs/sources/reference/components/loki/loki.echo.md
index 8e46cc47bb..8b83176685 100644
--- a/docs/sources/reference/components/loki/loki.echo.md
+++ b/docs/sources/reference/components/loki/loki.echo.md
@@ -6,21 +6,25 @@ description: Learn about loki.echo
 title: loki.echo
 ---
 
-# loki.echo
+# `loki.echo`
 
 `loki.echo` receives log entries from other `loki` components and prints them to the process' standard output (stdout).
 
-Multiple `loki.echo` components can be specified by giving them different labels.
+You can specify multiple `loki.echo` components by giving them different labels.
 
 ## Usage
 
 ```alloy
-loki.echo "LABEL" {}
+loki.echo "<LABEL>" {}
 ```
 
 ## Arguments
 
-`loki.echo` accepts no arguments.
+The `loki.echo` component doesn't support any arguments.
+
+## Blocks
+
+The `loki.echo` component doesn't support any blocks.
 
 ## Exported fields
 
@@ -36,7 +40,7 @@ Name       | Type           | Description
 
 ## Debug information
 
-`loki.echo` does not expose any component-specific debug information.
+`loki.echo` doesn't expose any component-specific debug information.
 
 ## Example
 
diff --git a/docs/sources/reference/components/loki/loki.process.md b/docs/sources/reference/components/loki/loki.process.md
index 31043c12b9..6ecf3b8953 100644
--- a/docs/sources/reference/components/loki/loki.process.md
+++ b/docs/sources/reference/components/loki/loki.process.md
@@ -6,7 +6,7 @@ description: Learn about loki.process
 title: loki.process
 ---
 
-# loki.process
+# `loki.process`
 
 `loki.process` receives log entries from other loki components, applies one or more processing _stages_, and forwards the results to the list of receivers in the component's arguments.
 
@@ -14,15 +14,15 @@ A stage is a multi-purpose tool that can parse, transform, and filter log entrie
 These stages are applied to each log entry in order of their appearance in the configuration file.
 All stages within a `loki.process` block have access to the log entry's label set, the log line, the log timestamp, as well as a shared map of 'extracted' values so that the results of one stage can be used in a subsequent one.
 
-Multiple `loki.process` components can be specified by giving them different labels.
+You can specify multiple `loki.process` components by giving them different labels.
 
 ## Usage
 
 ```alloy
-loki.process "LABEL" {
-  forward_to = RECEIVER_LIST
+loki.process "<LABEL>" {
+  forward_to = <RECEIVER_LIST>
 
-  stage.STAGENAME {
+  stage.<STAGENAME> {
     ...
   }
   ...
@@ -31,86 +31,85 @@ loki.process "LABEL" {
 
 ## Arguments
 
-`loki.process` supports the following arguments:
+You can use the following arguments with `loki.process`:
 
-| Name         | Type                 | Description                                    | Default | Required |
-| ------------ | -------------------- | ---------------------------------------------- | ------- | -------- |
-| `forward_to` | `list(LogsReceiver)` | Where to forward log entries after processing. |         | yes      |
+Name         | Type                 | Description                                    | Default | Required
+-------------|----------------------|------------------------------------------------|---------|---------
+`forward_to` | `list(LogsReceiver)` | Where to forward log entries after processing. |         | yes
 
 ## Blocks
 
-The following blocks are supported inside the definition of `loki.process`:
-
-| Hierarchy                 | Block                         | Description                                                    | Required |
-|---------------------------|-------------------------------|----------------------------------------------------------------|----------|
-| stage.cri                 | [stage.cri][]                 | Configures a pre-defined CRI-format pipeline.                  | no       |
-| stage.decolorize          | [stage.decolorize][]          | Strips ANSI color codes from log lines.                        | no       |
-| stage.docker              | [stage.docker][]              | Configures a pre-defined Docker log format pipeline.           | no       |
-| stage.drop                | [stage.drop][]                | Configures a `drop` processing stage.                          | no       |
-| stage.eventlogmessage     | [stage.eventlogmessage][]     | Extracts data from the Message field in the Windows Event Log. | no       |
-| stage.geoip               | [stage.geoip][]               | Configures a `geoip` processing stage.                         | no       |
-| stage.json                | [stage.json][]                | Configures a JSON processing stage.                            | no       |
-| stage.label_drop          | [stage.label_drop][]          | Configures a `label_drop` processing stage.                    | no       |
-| stage.label_keep          | [stage.label_keep][]          | Configures a `label_keep` processing stage.                    | no       |
-| stage.labels              | [stage.labels][]              | Configures a `labels` processing stage.                        | no       |
-| stage.limit               | [stage.limit][]               | Configures a `limit` processing stage.                         | no       |
-| stage.logfmt              | [stage.logfmt][]              | Configures a `logfmt` processing stage.                        | no       |
-| stage.luhn                | [stage.luhn][]                | Configures a `luhn` processing stage.                          | no       |
-| stage.match               | [stage.match][]               | Configures a `match` processing stage.                         | no       |
-| stage.metrics             | [stage.metrics][]             | Configures a `metrics` stage.                                  | no       |
-| stage.multiline           | [stage.multiline][]           | Configures a `multiline` processing stage.                     | no       |
-| stage.output              | [stage.output][]              | Configures an `output` processing stage.                       | no       |
-| stage.pack                | [stage.pack][]                | Configures a `pack` processing stage.                          | no       |
-| stage.regex               | [stage.regex][]               | Configures a `regex` processing stage.                         | no       |
-| stage.replace             | [stage.replace][]             | Configures a `replace` processing stage.                       | no       |
-| stage.sampling            | [stage.sampling][]            | Samples logs at a given rate.                                  | no       |
-| stage.static_labels       | [stage.static_labels][]       | Configures a `static_labels` processing stage.                 | no       |
-| stage.structured_metadata | [stage.structured_metadata][] | Configures a structured metadata processing stage.             | no       |
-| stage.template            | [stage.template][]            | Configures a `template` processing stage.                      | no       |
-| stage.tenant              | [stage.tenant][]              | Configures a `tenant` processing stage.                        | no       |
-| stage.timestamp           | [stage.timestamp][]           | Configures a `timestamp` processing stage.                     | no       |
-
-A user can provide any number of these stage blocks nested inside `loki.process`; these will run in order of appearance in the configuration file.
-
-[stage.cri]: #stagecri-block
-[stage.decolorize]: #stagedecolorize-block
-[stage.docker]: #stagedocker-block
-[stage.drop]: #stagedrop-block
-[stage.eventlogmessage]: #stageeventlogmessage-block
-[stage.geoip]: #stagegeoip-block
-[stage.json]: #stagejson-block
-[stage.label_drop]: #stagelabel_drop-block
-[stage.label_keep]: #stagelabel_keep-block
-[stage.labels]: #stagelabels-block
-[stage.limit]: #stagelimit-block
-[stage.logfmt]: #stagelogfmt-block
-[stage.luhn]: #stageluhn-block
-[stage.match]: #stagematch-block
-[stage.metrics]: #stagemetrics-block
-[stage.multiline]: #stagemultiline-block
-[stage.output]: #stageoutput-block
-[stage.pack]: #stagepack-block
-[stage.regex]: #stageregex-block
-[stage.replace]: #stagereplace-block
-[stage.sampling]: #stagesampling-block
-[stage.static_labels]: #stagestatic_labels-block
-[stage.structured_metadata]: #stagestructuredmetadata-block
-[stage.template]: #stagetemplate-block
-[stage.tenant]: #stagetenant-block
-[stage.timestamp]: #stagetimestamp-block
-
-
-### stage.cri block
+You can use the following blocks with `loki.process`:
+
+Block                                                    | Description                                                    | Required
+---------------------------------------------------------|----------------------------------------------------------------|---------
+[`stage.cri`][stage.cri]                                 | Configures a pre-defined CRI-format pipeline.                  | no
+[`stage.decolorize`][stage.decolorize]                   | Strips ANSI color codes from log lines.                        | no
+[`stage.docker`][stage.docker]                           | Configures a pre-defined Docker log format pipeline.           | no
+[`stage.drop`][stage.drop]                               | Configures a `drop` processing stage.                          | no
+[`stage.eventlogmessage`][stage.eventlogmessage]         | Extracts data from the Message field in the Windows Event Log. | no
+[`stage.geoip`][stage.geoip]                             | Configures a `geoip` processing stage.                         | no
+[`stage.json`][stage.json]                               | Configures a JSON processing stage.                            | no
+[`stage.label_drop`][stage.label_drop]                   | Configures a `label_drop` processing stage.                    | no
+[`stage.label_keep`][stage.label_keep]                   | Configures a `label_keep` processing stage.                    | no
+[`stage.labels`][stage.labels]                           | Configures a `labels` processing stage.                        | no
+[`stage.limit`][stage.limit]                             | Configures a `limit` processing stage.                         | no
+[`stage.logfmt`][stage.logfmt]                           | Configures a `logfmt` processing stage.                        | no
+[`stage.luhn`][stage.luhn]                               | Configures a `luhn` processing stage.                          | no
+[`stage.match`][stage.match]                             | Configures a `match` processing stage.                         | no
+[`stage.metrics`][stage.metrics]                         | Configures a `metrics` stage.                                  | no
+[`stage.multiline`][stage.multiline]                     | Configures a `multiline` processing stage.                     | no
+[`stage.output`][stage.output]                           | Configures an `output` processing stage.                       | no
+[`stage.pack`][stage.pack]                               | Configures a `pack` processing stage.                          | no
+[`stage.regex`][stage.regex]                             | Configures a `regex` processing stage.                         | no
+[`stage.replace`][stage.replace]                         | Configures a `replace` processing stage.                       | no
+[`stage.sampling`][stage.sampling]                       | Samples logs at a given rate.                                  | no
+[`stage.static_labels`][stage.static_labels]             | Configures a `static_labels` processing stage.                 | no
+[`stage.structured_metadata`][stage.structured_metadata] | Configures a structured metadata processing stage.             | no
+[`stage.template`][stage.template]                       | Configures a `template` processing stage.                      | no
+[`stage.tenant`][stage.tenant]                           | Configures a `tenant` processing stage.                        | no
+[`stage.timestamp`][stage.timestamp]                     | Configures a `timestamp` processing stage.                     | no
+
+You can provide any number of these stage blocks nested inside `loki.process`. These blocks run in order of appearance in the configuration file.
+
+[stage.cri]: #stagecri
+[stage.decolorize]: #stagedecolorize
+[stage.docker]: #stagedocker
+[stage.drop]: #stagedrop
+[stage.eventlogmessage]: #stageeventlogmessage
+[stage.geoip]: #stagegeoip
+[stage.json]: #stagejson
+[stage.label_drop]: #stagelabel_drop
+[stage.label_keep]: #stagelabel_keep
+[stage.labels]: #stagelabels
+[stage.limit]: #stagelimit
+[stage.logfmt]: #stagelogfmt
+[stage.luhn]: #stageluhn
+[stage.match]: #stagematch
+[stage.metrics]: #stagemetrics
+[stage.multiline]: #stagemultiline
+[stage.output]: #stageoutput
+[stage.pack]: #stagepack
+[stage.regex]: #stageregex
+[stage.replace]: #stagereplace
+[stage.sampling]: #stagesampling
+[stage.static_labels]: #stagestatic_labels
+[stage.structured_metadata]: #stagestructured_metadata
+[stage.template]: #stagetemplate
+[stage.tenant]: #stagetenant
+[stage.timestamp]: #stagetimestamp
+
+### `stage.cri`
 
 The `stage.cri` inner block enables a predefined pipeline which reads log lines using the CRI logging format.
 
 The following arguments are supported:
 
-| Name                             | Type       | Description                                                          | Default        | Required |
-| -------------------------------- | ---------- | -------------------------------------------------------------------- | -------------- | -------- |
-| `max_partial_lines`              | `number`   | Maximum number of partial lines to hold in memory.                   | `100`          | no       |
-| `max_partial_line_size`          | `number`   | Maximum number of characters which a partial line can have.          | `0`            | no       |
-| `max_partial_line_size_truncate` | `bool`     | Truncate partial lines that are longer than `max_partial_line_size`. | `false`        | no       |
+Name                             | Type     | Description                                                          | Default | Required
+---------------------------------|----------|----------------------------------------------------------------------|---------|---------
+`max_partial_line_size_truncate` | `bool`   | Truncate partial lines that are longer than `max_partial_line_size`. | `false` | no
+`max_partial_line_size`          | `number` | Maximum number of characters which a partial line can have.          | `0`     | no
+`max_partial_lines`              | `number` | Maximum number of partial lines to hold in memory.                   | `100`   | no
 
 `max_partial_line_size` is only taken into account if `max_partial_line_size_truncate` is set to `true`.
 
@@ -120,14 +119,14 @@ stage.cri {}
 
 CRI specifies log lines as single space-delimited values with the following components:
 
-* `time`: The timestamp string of the log
-* `stream`: Either `stdout` or `stderr`
-* `flags`: CRI flags including `F` or `P`
-* `log`: The contents of the log line
+* `time`: The timestamp string of the log.
+* `stream`: Either `stdout` or `stderr`.
+* `flags`: CRI flags including `F` or `P`.
+* `log`: The contents of the log line.
 
 Given the following log line, the subsequent key-value pairs are created in the shared map of extracted data:
 
-```
+```text
 "2019-04-30T02:12:41.8443515Z stdout F message"
 
 content: message
@@ -135,11 +134,11 @@ stream: stdout
 timestamp: 2019-04-30T02:12:41.8443515
 ```
 
-### stage.decolorize block
+### `stage.decolorize`
 
-The `stage.decolorize` strips ANSI color codes from the log lines, thus making it easier to parse logs further.
+The `stage.decolorize` strips ANSI color codes from the log lines, making it easier to parse logs.
 
-The `stage.decolorize` block does not support any arguments or inner blocks, so it is always empty.
+The `stage.decolorize` block doesn't support any arguments or inner blocks, so it's always empty.
 
 ```alloy
 stage.decolorize {}
@@ -147,21 +146,21 @@ stage.decolorize {}
 
 `stage.decolorize` turns each line having a color code into a non-colored one, for example:
 
-```
+```text
 [2022-11-04 22:17:57.811] \033[0;32http\033[0m: GET /_health (0 ms) 204
 ```
 
 is turned into
 
-```
+```text
 [2022-11-04 22:17:57.811] http: GET /_health (0 ms) 204
 ```
 
-### stage.docker block
+### `stage.docker`
 
 The `stage.docker` inner block enables a predefined pipeline which reads log lines in the standard format of Docker log files.
 
-The `stage.docker` block does not support any arguments or inner blocks, so it is always empty.
+The `stage.docker` block doesn't support any arguments or inner blocks, so it's always empty.
 
 ```alloy
 stage.docker {}
@@ -169,13 +168,13 @@ stage.docker {}
 
 Docker log entries are formatted as JSON with the following keys:
 
-* `log`: The content of log line
-* `stream`: Either `stdout` or `stderr`
-* `time`: The timestamp string of the log line
+* `log`: The content of log line.
+* `stream`: Either `stdout` or `stderr`.
+* `time`: The timestamp string of the log line.
 
 Given the following log line, the subsequent key-value pairs are created in the shared map of extracted data:
 
-```
+```text
 {"log":"log message\n","stream":"stderr","time":"2019-04-30T02:12:41.8443515Z"}
 
 output: log message\n
@@ -183,7 +182,7 @@ stream: stderr
 timestamp: 2019-04-30T02:12:41.8443515
 ```
 
-### stage.drop block
+### `stage.drop`
 
 The `stage.drop` inner block configures a filtering stage that drops log entries based on several options.
 If multiple options are provided, they're treated as AND clauses and must _all_ be true for the log entry to be dropped.
@@ -191,26 +190,29 @@ To drop entries with an OR clause, specify multiple `drop` blocks in sequence.
 
 The following arguments are supported:
 
-| Name                  | Type       | Description                                                                                                            | Default        | Required |
-|-----------------------|------------|------------------------------------------------------------------------------------------------------------------------|----------------|----------|
-| `source`              | `string`   | Name or comma-separated list of names from extracted data to match. If empty or not defined, it uses the log message.  | `""`           | no       |
-| `separator`           | `string`   | When `source` is a comma-separated list of names, this separator is placed between concatenated extracted data values. | `";"`          | no       |
-| `expression`          | `string`   | A valid RE2 regular expression.                                                                                        | `""`           | no       |
-| `value`               | `string`   | If both `source` and `value` are specified, the stage drops lines where `value` exactly matches the source content.    | `""`           | no       |
-| `older_than`          | `duration` | If specified, the stage drops lines whose timestamp is older than the current time minus this duration.                | `""`           | no       |
-| `longer_than`         | `string`   | If specified, the stage drops lines whose size exceeds the configured value.                                           | `""`           | no       |
-| `drop_counter_reason` | `string`   | A custom reason to report for dropped lines.                                                                           | `"drop_stage"` | no       |
-
-The `expression` field must be a RE2 regex string.
-* If `source` is empty or not provided, the regex attempts to match the log line itself.
-* If `source` is a single name, the regex attempts to match the corresponding value from the extracted map.
-* If `source` is a comma-separated list of names, the corresponding values from the extracted map are concatenated using `separator` and the regex attempts to match the concatenated string.
+Name                  | Type       | Description                                                                                                            | Default        | Required
+----------------------|------------|------------------------------------------------------------------------------------------------------------------------|----------------|---------
+`drop_counter_reason` | `string`   | A custom reason to report for dropped lines.                                                                           | `"drop_stage"` | no
+`expression`          | `string`   | A valid RE2 regular expression.                                                                                        | `""`           | no
+`longer_than`         | `string`   | If specified, the stage drops lines whose size exceeds the configured value.                                           | `""`           | no
+`older_than`          | `duration` | If specified, the stage drops lines whose timestamp is older than the current time minus this duration.                | `""`           | no
+`separator`           | `string`   | When `source` is a comma-separated list of names, this separator is placed between concatenated extracted data values. | `";"`          | no
+`source`              | `string`   | Name or comma-separated list of names from extracted data to match. If empty or not defined, it uses the log message.  | `""`           | no
+`value`               | `string`   | If both `source` and `value` are specified, the stage drops lines where `value` exactly matches the source content.    | `""`           | no
+
+The `expression` field must be a RE2 regular expression string.
+
+* If `source` is empty or not provided, the regular expression attempts to match the log line itself.
+* If `source` is a single name, the regular expression attempts to match the corresponding value from the extracted map.
+* If `source` is a comma-separated list of names, the corresponding values from the extracted map are concatenated using `separator` and the regular expression attempts to match the concatenated string.
 
 The `value` field can only work with values from the extracted map, and must be specified together with `source`.
+
 * If `source` is a single name, the entries are dropped when there is an exact match between the corresponding value from the extracted map and the `value`.
 * If `source` is a comma-separated list of names, the entries are dropped when the `value` matches the `source` values from extracted data, concatenated using the `separator`.
 
-Whenever an entry is dropped, the metric `loki_process_dropped_lines_total` is incremented. By default, the reason label is `"drop_stage"`, but you can provide a custom label using the `drop_counter_reason` argument.
+Whenever an entry is dropped, the metric `loki_process_dropped_lines_total` is incremented.
+By default, the reason label is `"drop_stage"`, but you can provide a custom label using the `drop_counter_reason` argument.
 
 The following stage drops log entries that contain the word `debug` _and_ are longer than 1KB.
 
@@ -221,7 +223,7 @@ stage.drop {
 }
 ```
 
-On the following example, we define multiple `drop` blocks so `loki.process` drops entries that are either 24h or older, are longer than 8KB, _or_ the extracted value of 'app' is equal to foo.
+The following example defines multiple `drop` blocks so `loki.process` drops entries that are either 24h or older, are longer than 8KB, _or_ the extracted value of `app` is equal to `example`.
 
 ```alloy
 stage.drop {
@@ -236,27 +238,27 @@ stage.drop {
 
 stage.drop {
     source = "app"
-    value  = "foo"
+    value  = "example"
 }
 ```
 
-### stage.eventlogmessage block
+### `stage.eventlogmessage`
 
 The `eventlogmessage` stage extracts data from the Message string that appears in the Windows Event Log.
 
 The following arguments are supported:
 
-| Name                  | Type     | Description                                            | Default   | Required |
-|-----------------------|----------|--------------------------------------------------------|-----------|----------|
-| `source`              | `string` | Name of the field in the extracted data to parse.      | `message` | no       |
-| `overwrite_existing`  | `bool`   | Whether to overwrite existing extracted data fields.   | `false`   | no       |
-| `drop_invalid_labels` | `bool`   | Whether to drop fields that are not valid label names. | `false`   | no       |
+Name                  | Type     | Description                                           | Default   | Required
+----------------------|----------|-------------------------------------------------------|-----------|---------
+`drop_invalid_labels` | `bool`   | Whether to drop fields that aren't valid label names. | `false`   | no
+`overwrite_existing`  | `bool`   | Whether to overwrite existing extracted data fields.  | `false`   | no
+`source`              | `string` | Name of the field in the extracted data to parse.     | `message` | no
 
-When `overwrite_existing` is set to `true`, the stage overwrites existing extracted data fields with the same name.
-If set to `false`, the `_extracted` suffix will be appended to an already existing field name.
+When `drop_invalid_labels` is set to `true`, the stage drops fields that aren't valid label names.
+If set to `false`, the stage automatically converts them into valid labels replacing invalid characters with underscores.
 
-When `drop_invalid_labels` is set to `true`, the stage drops fields that are not valid label names.
-If set to `false`, the stage will automatically convert them into valid labels replacing invalid characters with underscores.
+When `overwrite_existing` is set to `true`, the stage overwrites existing extracted data fields with the same name.
+If set to `false`, the `_extracted` suffix is appended to an existing field name.
 
 The `eventlogmessage` stage only extracts lines with the key:value format.
 All non-alpha characters in the key are replaced with underscores.
@@ -279,22 +281,195 @@ stage.eventlogmessage {
 ```
 
 Given the following log line:
-```
+
+```text
 {"event_id": 1, "Overwritten": "old", "message": "Message type:\r\nOverwritten: new\r\nImage: C:\\Users\\User\\alloy.exe"}
 ```
 
 The first stage would create the following key-value pairs in the set of extracted data:
 
-- `message`: `Message type:\r\nOverwritten: new\r\nImage: C:\Users\User\alloy.exe`
-- `Overwritten`: `old`
+* `message`: `Message type:\r\nOverwritten: new\r\nImage: C:\Users\User\alloy.exe`
+* `Overwritten`: `old`
+
+The second stage parses the value of `message` from the extracted data and appends or overwrites the following key-value pairs to the set of extracted data:
 
-The second stage will parse the value of `message` from the extracted data and append/overwrite the following key-value pairs to the set of extracted data:
+* `Image`: `C:\\Users\\User\\alloy.exe`
+* `Message_type`: (empty string)
+* `Overwritten`: `new`
+
+### `stage.geoip`
+
+The `stage.geoip` inner block configures a processing stage that reads an IP address and populates the shared map with `geoip` fields. The Maxmind GeoIP2 database is used for the lookup.
+
+The following arguments are supported:
+
+Name             | Type          | Description                                                         | Default | Required
+-----------------|---------------|---------------------------------------------------------------------|---------|---------
+`db`             | `string`      | Path to the Maxmind DB file.                                        |         | yes
+`source`         | `string`      | IP from extracted data to parse.                                    |         | yes
+`custom_lookups` | `map(string)` | Key-value pairs of JMESPath expressions.                            |         | no
+`db_type`        | `string`      | Maxmind DB type. Allowed values are `"city"`, `"asn"`, `"country"`. |         | no
+
+#### GeoIP with City database example
+
+```alloy
+{"log":"log message","client_ip":"34.120.177.193"}
+
+loki.process "example" {
+    stage.json {
+        expressions = {ip = "client_ip"}
+    }
 
-- `Image`: `C:\\Users\\User\\alloy.exe`
-- `Message_type`: (empty string)
-- `Overwritten`: `new`
+    stage.geoip {
+        source  = "ip"
+        db      = "/path/to/db/GeoLite2-City.mmdb"
+        db_type = "city"
+    }
 
-### stage.json block
+    stage.labels {
+        values = {
+            geoip_city_name          = "",
+            geoip_country_name       = "",
+            geoip_country_code       = "",
+            geoip_continent_name     = "",
+            geoip_continent_code     = "",
+            geoip_location_latitude  = "",
+            geoip_location_longitude = "",
+            geoip_postal_code        = "",
+            geoip_timezone           = "",
+            geoip_subdivision_name   = "",
+            geoip_subdivision_code   = "",
+        }
+    }
+}
+```
+
+The `json` stage extracts the IP address from the `client_ip` key in the log line.
+Then the extracted `ip` value is given as source to `geoip` stage. The `geoip` stage performs a lookup on the IP and populates the following fields in the shared map which are added as labels using the `labels` stage.
+
+The extracted data from the IP used in this example:
+
+```text
+geoip_city_name: Kansas City
+geoip_country_name: United States
+geoip_country_code: US
+geoip_continent_name: North America
+geoip_continent_code: NA
+geoip_location_latitude: 39.1027
+geoip_location_longitude: -94.5778
+geoip_postal_code: 64184
+geoip_timezone: America/Chicago
+geoip_subdivision_name: Missouri
+geoip_subdivision_code: MO
+```
+
+#### GeoIP with ASN (Autonomous System Number) database example
+
+```alloy
+loki.process "example" {
+    stage.json {
+        expressions = {ip = "client_ip"}
+    }
+
+    stage.geoip {
+        source  = "ip"
+        db      = "/path/to/db/GeoIP2-ASN.mmdb"
+        db_type = "asn"
+    }
+
+    stage.labels {
+        values = {
+            geoip_autonomous_system_number       = "",
+            geoip_autonomous_system_organization = "",
+        }
+    }
+}
+```
+
+The `json` stage extracts the IP address from the `client_ip` key in the log line.
+Then the extracted `ip` value is given as source to `geoip` stage. The `geoip` stage performs a lookup on the IP and populates the shared map.
+
+The extracted data from the IP used in this example:
+
+```text
+geoip_autonomous_system_number: 396982
+geoip_autonomous_system_organization: GOOGLE-CLOUD-PLATFORM
+```
+
+#### GeoIP with Country database example
+
+```alloy
+{"log":"log message","client_ip":"34.120.177.193"}
+
+loki.process "example" {
+    stage.json {
+        expressions = {ip = "client_ip"}
+    }
+
+    stage.geoip {
+        source  = "ip"
+        db      = "/path/to/db/GeoLite2-Country.mmdb"
+        db_type = "country"
+    }
+
+    stage.labels {
+        values = {
+            geoip_country_name       = "",
+            geoip_country_code       = "",
+            geoip_continent_name     = "",
+            geoip_continent_code     = "",
+        }
+    }
+}
+```
+
+The `json` stage extracts the IP address from the `client_ip` key in the log line.
+Then the extracted `ip` value is given as source to `geoip` stage. The `geoip` stage performs a lookup on the IP and populates the following fields in the shared map which are added as labels using the `labels` stage.
+
+The extracted data from the IP used in this example:
+
+```text
+geoip_country_name: United States
+geoip_country_code: US
+geoip_continent_name: North America
+geoip_continent_code: NA
+```
+
+#### GeoIP with custom fields example
+
+If the MMDB file used is enriched with custom data, for example, private IP addresses as explained in [the Maxmind blog post](https://github.com/maxmind/mmdb-from-go-blogpost), then it can be extracted from the record using the `custom_lookups` attribute.
+
+```alloy
+loki.process "example" {
+    stage.json {
+        expressions = {ip = "client_ip"}
+    }
+
+    stage.geoip {
+        source         = "ip"
+        db             = "/path/to/db/GeoIP2-Enriched.mmdb"
+        db_type        = "city"
+        custom_lookups = {
+            "department"  = "MyCompany.DeptName",
+            "parent_vnet" = "MyCompany.ParentVNet",
+            "subnet"      = "MyCompany.Subnet",
+        }
+    }
+
+    stage.labels {
+        values = {
+            department  = "",
+            parent_vnet = "",
+            subnet      = "",
+        }
+    }
+}
+```
+
+The `json` stage extracts the IP address from the `client_ip` key in the log line.
+Then the extracted `ip` value is given as source to `geoip` stage. The `geoip` stage performs a lookup on the IP and populates the shared map with the data from the city database results in addition to the custom lookups. Lastly, the custom lookup fields from the shared map are added as labels.
+
+### `stage.json`
 
 The `stage.json` inner block configures a JSON processing stage that parses incoming log lines or previously extracted values as JSON and uses [JMESPath expressions][] to extract new values from them.
 
@@ -302,19 +477,19 @@ The `stage.json` inner block configures a JSON processing stage that parses inco
 
 The following arguments are supported:
 
-| Name             | Type          | Description                                            | Default | Required |
-| ---------------- | ------------- | ------------------------------------------------------ | ------- | -------- |
-| `expressions`    | `map(string)` | Key-value pairs of JMESPath expressions.               |         | yes      |
-| `source`         | `string`      | Source of the data to parse as JSON.                   | `""`    | no       |
-| `drop_malformed` | `bool`        | Drop lines whose input cannot be parsed as valid JSON. | `false` | no       |
-
-When configuring a JSON stage, the `source` field defines the source of data to parse as JSON.
-By default, this is the log line itself, but it can also be a previously extracted value.
+Name             | Type          | Description                                           | Default | Required
+-----------------|---------------|-------------------------------------------------------|---------|---------
+`expressions`    | `map(string)` | Key-value pairs of JMESPath expressions.              |         | yes
+`drop_malformed` | `bool`        | Drop lines whose input can't be parsed as valid JSON. | `false` | no
+`source`         | `string`      | Source of the data to parse as JSON.                  | `""`    | no
 
 The `expressions` field is the set of key-value pairs of JMESPath expressions to run.
 The map key defines the name with which the data is extracted, while the map value is the expression used to populate the value.
 
-Here's a given log line and two JSON stages to run.
+When configuring a JSON stage, the `source` field defines the source of data to parse as JSON.
+By default, this is the log line itself, but it can also be a previously extracted value.
+
+The following example shows a given log line and two JSON stages.
 
 ```alloy
 {"log":"log message\n","extra":"{\"user\":\"alloy\"}"}
@@ -332,19 +507,21 @@ loki.process "username" {
 ```
 
 In this example, the first stage uses the log line as the source and populates these values in the shared map.
-An empty expression means using the same value as the key (so `extra="extra"`).
-```
+An empty expression means using the same value as the key, for example `extra="extra"`.
+
+```text
 output: log message\n
 extra: {"user": "alloy"}
 ```
 
 The second stage uses the value in `extra` as the input and appends the following key-value pair to the set of extracted data.
-```
+
+```text
 username: alloy
 ```
 
 {{< admonition type="note" >}}
-Due to a limitation of the upstream jmespath library, you must wrap any string that contains a hyphen `-` in quotes so that it's not considered a numerical expression.
+Due to a limitation of the upstream `jmespath` library, you must wrap any string that contains a hyphen `-` in quotes so that it's not considered a numerical expression.
 
 If you don't use quotes to wrap a string that contains a hyphen, you will get errors like: `Unexpected token at the end of the expression: tNumber`
 
@@ -354,16 +531,15 @@ You can use one of two options to circumvent this issue:
 1. A backtick quote. For example: ``http_user_agent = `"request_User-Agent"` ``
 {{< /admonition >}}
 
-### stage.label_drop block
+### `stage.label_drop`
 
-The `stage.label_drop` inner block configures a processing stage that drops labels
-from incoming log entries.
+The `stage.label_drop` inner block configures a processing stage that drops labels from incoming log entries.
 
 The following arguments are supported:
 
-| Name     | Type           | Description                                 | Default | Required |
-| -------- | -------------- | ------------------------------------------- | ------- | -------- |
-| `values` | `list(string)` | Configures a `label_drop` processing stage. | `{}`    | no       |
+Name     | Type           | Description                                 | Default | Required
+---------|----------------|---------------------------------------------|---------|---------
+`values` | `list(string)` | Configures a `label_drop` processing stage. | `{}`    | no
 
 ```alloy
 stage.label_drop {
@@ -371,16 +547,15 @@ stage.label_drop {
 }
 ```
 
-### stage.label_keep block
+### `stage.label_keep`
 
 The `stage.label_keep` inner block configures a processing stage that filters the label set of an incoming log entry down to a subset.
 
 The following arguments are supported:
 
-| Name     | Type           | Description                                 | Default | Required |
-| -------- | -------------- | ------------------------------------------- | ------- | -------- |
-| `values` | `list(string)` | Configures a `label_keep` processing stage. | `{}`    | no       |
-
+Name     | Type           | Description                                 | Default | Required
+---------|----------------|---------------------------------------------|---------|---------
+`values` | `list(string)` | Configures a `label_keep` processing stage. | `{}`    | no
 
 ```alloy
 stage.label_keep {
@@ -388,18 +563,18 @@ stage.label_keep {
 }
 ```
 
-### stage.labels block
+### `stage.labels`
 
 The `stage.labels` inner block configures a labels processing stage that can read data from the extracted values map and set new labels on incoming log entries.
 
 The following arguments are supported:
 
-| Name     | Type          | Description                             | Default | Required |
-| -------- | ------------- | --------------------------------------- | ------- | -------- |
-| `values` | `map(string)` | Configures a `labels` processing stage. | `{}`    | no       |
+Name     | Type          | Description                             | Default | Required
+---------|---------------|-----------------------------------------|---------|---------
+`values` | `map(string)` | Configures a `labels` processing stage. | `{}`    | no
 
 In a labels stage, the map's keys define the label to set and the values are how to look them up.
-If the value is empty, it is inferred to be the same as the key.
+If the value is empty, it's inferred to be the same as the key.
 
 ```alloy
 stage.labels {
@@ -410,44 +585,24 @@ stage.labels {
 }
 ```
 
-### stage.structured_metadata block
-
-The `stage.structured_metadata` inner block configures a stage that can read data from the extracted values map and add them to log entries as structured metadata.
-
-The following arguments are supported:
-
-| Name     | Type          | Description                                                                 | Default | Required |
-| -------- | ------------- |-----------------------------------------------------------------------------| ------- | -------- |
-| `values` | `map(string)` | Specifies the list of labels to add from extracted values map to log entry. | `{}`    | no       |
-
-In a structured_metadata stage, the map's keys define the label to set and the values are how to look them up.
-If the value is empty, it is inferred to be the same as the key.
-
-```alloy
-stage.structured_metadata {
-    values = {
-      env  = "",         // Sets up an 'env' property to structured metadata, based on the 'env' extracted value.
-      user = "username", // Sets up a 'user' property to structured metadata, based on the 'username' extracted value.
-    }
-}
-```
-
-### stage.limit block
+### `stage.limit`
 
 The `stage.limit` inner block configures a rate-limiting stage that throttles logs based on several options.
 
 The following arguments are supported:
 
-| Name                  | Type     | Description                                                                      | Default | Required |
-| --------------------- | -------- | -------------------------------------------------------------------------------- | ------- | -------- |
-| `rate`                | `number` | The maximum rate of lines per second that the stage forwards.                    |         | yes      |
-| `burst`               | `number` | The maximum number of burst lines that the stage forwards.                       |         | yes      |
-| `by_label_name`       | `string` | The label to use when rate-limiting on a label name.                             | `""`    | no       |
-| `drop`                | `bool`   | Whether to discard or backpressure lines that exceed the rate limit.             | `false` | no       |
-| `max_distinct_labels` | `number` | The number of unique values to keep track of when rate-limiting `by_label_name`. | `10000` | no       |
+Name                  | Type     | Description                                                                      | Default | Required
+----------------------|----------|----------------------------------------------------------------------------------|---------|---------
+`burst`               | `number` | The maximum number of burst lines that the stage forwards.                       |         | yes
+`rate`                | `number` | The maximum rate of lines per second that the stage forwards.                    |         | yes
+`by_label_name`       | `string` | The label to use when rate-limiting on a label name.                             | `""`    | no
+`drop`                | `bool`   | Whether to discard or backpressure lines that exceed the rate limit.             | `false` | no
+`max_distinct_labels` | `number` | The number of unique values to keep track of when rate-limiting `by_label_name`. | `10000` | no
 
-The rate limiting is implemented as a "token bucket" of size `burst`, initially full and refilled at `rate` tokens per second.
-Each received log entry consumes one token from the bucket. When `drop` is set to true, incoming entries that exceed the rate-limit are dropped, otherwise they are queued until more tokens are available.
+The rate limiting is a "token bucket" of size `burst`.
+It's initially full and refilled at `rate` tokens per second.
+Each received log entry consumes one token from the bucket.
+When `drop` is set to true, incoming entries that exceed the rate-limit are dropped, otherwise they're queued until more tokens are available.
 
 ```alloy
 stage.limit {
@@ -460,7 +615,7 @@ If `by_label_name` is set, then `drop` must be set to `true`.
 This enables the stage to rate-limit not by the number of lines but by the number of labels.
 
 The following example rate-limits entries from each unique `namespace` value independently.
-Any entries without the `namespace` label are not rate-limited.
+Any entries without the `namespace` label aren't rate-limited.
 The stage keeps track of up to `max_distinct_labels` unique values, defaulting at 10000.
 
 ```alloy
@@ -473,29 +628,30 @@ stage.limit {
 }
 ```
 
-### stage.logfmt block
+### `stage.logfmt`
 
 The `stage.logfmt` inner block configures a processing stage that reads incoming log lines as logfmt and extracts values from them.
 
 The following arguments are supported:
 
-| Name      | Type          | Description                                  | Default | Required |
-| --------- | ------------- | -------------------------------------------- | ------- | -------- |
-| `mapping` | `map(string)` | Key-value pairs of logmft fields to extract. |         | yes      |
-| `source`  | `string`      | Source of the data to parse as logfmt.       | `""`    | no       |
-
+Name      | Type          | Description                                    | Default | Required
+----------|---------------|------------------------------------------------|---------|---------
+`mapping` | `map(string)` | Key-value pairs of `logmft` fields to extract. |         | yes
+`source`  | `string`      | Source of the data to parse as `logfmt`.       | `""`    | no
 
-The `source` field defines the source of data to parse as logfmt. 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 `source` field defines the source of data to parse as `logfmt`.
+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.
 
-This stage uses the [go-logfmt][] unmarshaler, so that numeric or boolean types are unmarshalled into their correct form. The stage does not perform any other type conversions.
-If the extracted value is a complex type, it is treated as a string.
+This stage uses the [go-logfmt][] unmarshaler, so that numeric or boolean types are unmarshalled into their correct form.
+The stage doesn't perform any other type conversions.
+If the extracted value is a complex type, it's treated as a string.
 
 [go-logfmt]: https://github.com/go-logfmt/logfmt
 
-Let's see how this works on the following log line and stages.
+The following log line and stages demonstrates how this works.
 
-```
-time=2012-11-01T22:08:41+00:00 app=loki level=WARN duration=125 message="this is a log line" extra="user=foo"
+```alloy
+time=2012-11-01T22:08:41+00:00 app=loki level=WARN duration=125 message="this is a log line" extra="user=example_name"
 
 stage.logfmt {
     mapping = { "extra" = "" }
@@ -507,39 +663,34 @@ stage.logfmt {
 }
 ```
 
-The first stage parses the log line itself and inserts the `extra` key in the set of extracted data, with the value of `user=foo`.
+The first stage parses the log line itself and inserts the `extra` key in the set of extracted data, with the value of `user=example_name`.
 
-The second stage parses the contents of `extra` and appends the `username: foo` key-value pair to the set of extracted data.
+The second stage parses the contents of `extra` and appends the `username: example_name` key-value pair to the set of extracted data.
 
-### stage.luhn block
+### `stage.luhn`
 
-The `stage.luhn` inner block configures a processing stage that reads incoming
-log lines and redacts strings that match a Luhn algorithm.
+The `stage.luhn` inner block configures a processing stage that reads incoming log lines and redacts strings that match a Luhn algorithm.
 
-The [Luhn algorithm][] is a simple checksum formula used to validate various
-identification numbers, such as credit card numbers, IMEI numbers, National
-Provider Identifier numbers in the US, and Canadian Social Insurance Numbers.
+The [Luhn algorithm][] is a simple checksum formula used to validate various identification numbers, such as credit card numbers, IMEI numbers, National Provider Identifier numbers in the USA, and Canadian Social Insurance Numbers.
 Many Payment Card Industry environments require these numbers to be redacted.
 
 [Luhn algorithm]: https://en.wikipedia.org/wiki/Luhn_algorithm
 
 The following arguments are supported:
 
-| Name          | Type          | Description                                    | Default          | Required |
-| ------------- | ------------- | ---------------------------------------------- | ---------------- | -------- |
-| `replacement` | `string`      | String to substitute the matched patterns with | `"**REDACTED**"` | no      |
-| `source`      | `string`      | Source of the data to parse.                   | `""`             | no       |
-| `min_length`   | `int`         | Minimum length of digits to consider           | `13`             | no       |
-
+Name          | Type     | Description                                    | Default          | Required
+--------------|----------|------------------------------------------------|------------------|---------
+`min_length`  | `int`    | Minimum length of digits to consider           | `13`             | no
+`replacement` | `string` | String to substitute the matched patterns with | `"**REDACTED**"` | no
+`source`      | `string` | Source of the data to parse.                   | `""`             | no
 
-The `source` field defines the source of data to search. 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 `source` field defines the source of data to search.
+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 following example log line contains an approved credit card number.
 
-```
-time=2012-11-01T22:08:41+00:00 app=loki level=WARN duration=125 message="credit card approved 4032032513548443" extra="user=foo"
+```alloy
+time=2012-11-01T22:08:41+00:00 app=loki level=WARN duration=125 message="credit card approved 4032032513548443" extra="user=example_name"
 
 stage.luhn {
     replacement = "**DELETED**"
@@ -548,40 +699,39 @@ stage.luhn {
 
 The stage parses the log line, redacts the credit card number, and produces the following updated log line:
 
-```
-time=2012-11-01T22:08:41+00:00 app=loki level=INFO duration=125 message="credit card approved **DELETED**" extra="user=foo"
+```text
+time=2012-11-01T22:08:41+00:00 app=loki level=INFO duration=125 message="credit card approved **DELETED**" extra="user=example_name"
 ```
 
-### stage.match block
+### `stage.match`
 
 The `stage.match` inner block configures a filtering stage that can conditionally either apply a nested set of processing stages or drop an entry when a log entry matches a configurable LogQL stream selector and filter expressions.
 
 The following arguments are supported:
 
-| Name                  | Type     | Description                                                                                           | Default         | Required |
-| --------------------- | -------- | ----------------------------------------------------------------------------------------------------- | --------------- | -------- |
-| `selector`            | `string` | The LogQL stream selector and line filter expressions to use.                                         |                 | yes      |
-| `pipeline_name`       | `string` | A custom name to use for the nested pipeline.                                                         | `""`            | no       |
-| `action`              | `string` | The action to take when the selector matches the log line. Supported values are `"keep"` and `"drop"` | `"keep"`        | no       |
-| `drop_counter_reason` | `string` | A custom reason to report for dropped lines.                                                          | `"match_stage"` | no       |
+Name                  | Type     | Description                                                                                           | Default         | Required
+----------------------|----------|-------------------------------------------------------------------------------------------------------|-----------------|---------
+`selector`            | `string` | The LogQL stream selector and line filter expressions to use.                                         |                 | yes
+`action`              | `string` | The action to take when the selector matches the log line. Supported values are `"keep"` and `"drop"` | `"keep"`        | no
+`drop_counter_reason` | `string` | A custom reason to report for dropped lines.                                                          | `"match_stage"` | no
+`pipeline_name`       | `string` | A custom name to use for the nested pipeline.                                                         | `""`            | no
 
 {{< admonition type="note" >}}
-The filters do not include label filter expressions such as `| label == "foobar"`.
+The filters don't include label filter expressions such as `| label == "examplelabel"`.
 {{< /admonition >}}
 
 The `stage.match` block supports a number of `stage.*` inner blocks, like the top-level block.
 These are used to construct the nested set of stages to run if the selector matches the labels and content of the log entries.
 It supports all the same `stage.NAME` blocks as the in the top level of the `loki.process` component.
 
-
 If the specified action is `"drop"`, the metric `loki_process_dropped_lines_total` is incremented with every line dropped.
 By default, the reason label is `"match_stage"`, but a custom reason can be provided by using the `drop_counter_reason` argument.
 
-Let's see this in action, with the following log lines and stages:
+The following example log lines and stages show how this works.
 
-```
-{ "time":"2023-01-18T17:08:41+00:00", "app":"foo", "component": ["parser","type"], "level" : "WARN", "message" : "app1 log line" }
-{ "time":"2023-01-18T17:08:42+00:00", "app":"bar", "component": ["parser","type"], "level" : "ERROR", "message" : "foo noisy error" }
+```alloy
+{ "time":"2023-01-18T17:08:41+00:00", "app":"example1", "component": ["parser","type"], "level" : "WARN", "message" : "app1 log line" }
+{ "time":"2023-01-18T17:08:42+00:00", "app":"example2", "component": ["parser","type"], "level" : "ERROR", "message" : "example noisy error" }
 
 stage.json {
     expressions = { "appname" = "app" }
@@ -592,7 +742,7 @@ stage.labels {
 }
 
 stage.match {
-    selector = "{applbl=\"foo\"}"
+    selector = "{applbl=\"examplelabel\"}"
 
     stage.json {
         expressions = { "msg" = "message" }
@@ -620,107 +770,105 @@ stage.output {
 
 The first two stages parse the log lines as JSON, decode the `app` value into the shared extracted map as `appname`, and use its value as the `applbl` label.
 
-The third stage uses the LogQL selector to only execute the nested stages on lines where the `applbl="foo"`.
+The third stage uses the LogQL selector to only execute the nested stages on lines where the `applbl="examplelabel"`.
 So, for the first line, the nested JSON stage adds `msg="app1 log line"` into the extracted map.
 
-The fourth stage uses the LogQL selector to only execute on lines where `applbl="qux"`; that means it won't match any of the input, and the nested JSON stage does not run.
+The fourth stage uses the LogQL selector to only execute on lines where `applbl="qux"`. This means it won't match any of the input, and the nested JSON stage doesn't run.
 
-The fifth stage drops entries from lines where `applbl` is set to 'bar' and the line contents matches the regex `.*noisy error.*`.
+The fifth stage drops entries from lines where `applbl` is set to 'example2' and the line contents matches the regex `.*noisy error.*`.
 It also increments the `loki_process_dropped_lines_total` metric with a label `drop_counter_reason="discard_noisy_errors"`.
 
 The final output stage changes the contents of the log line to be the value of `msg` from the extracted map. In this case, the first log entry's content is changed to `app1 log line`.
 
-### stage.metrics block
+### `stage.metrics`
 
-The `stage.metrics` inner block configures stage that allows to define and update metrics based on values from the shared extracted map.
-The created metrics are available at {{< param "PRODUCT_NAME" >}}'s root /metrics endpoint.
+The `stage.metrics` inner block configures stage that allows you to define and update metrics based on values from the shared extracted map.
+The created metrics are available at the {{< param "PRODUCT_NAME" >}} root `/metrics` endpoint.
 
-The `stage.metrics` block does not support any arguments and is only configured via a number of nested inner `metric.*` blocks, one for each metric that should be generated.
+The `stage.metrics` block doesn't support any arguments and is only configured via a number of nested inner `metric.*` blocks, one for each metric that should be generated.
 
 The following blocks are supported inside the definition of `stage.metrics`:
 
-| Hierarchy        | Block                | Description                   | Required |
-| ---------------- | -------------------- | ----------------------------- | -------- |
-| metric.counter   | [metric.counter][]   | Defines a `counter` metric.   | no       |
-| metric.gauge     | [metric.gauge][]     | Defines a `gauge` metric.     | no       |
-| metric.histogram | [metric.histogram][] | Defines a `histogram` metric. | no       |
+Block                                  | Description                   | Required
+---------------------------------------|-------------------------------|---------
+[`metric.counter`][metric.counter]     | Defines a `counter` metric.   | no
+[`metric.gauge`][metric.gauge]         | Defines a `gauge` metric.     | no
+[`metric.histogram`][metric.histogram] | Defines a `histogram` metric. | no
 
 {{< admonition type="note" >}}
 The metrics will be reset if you reload the {{< param "PRODUCT_NAME" >}} configuration file.
 {{< /admonition >}}
 
-[metric.counter]: #metriccounter-block
-[metric.gauge]: #metricgauge-block
-[metric.histogram]: #metrichistogram-block
-
+[metric.counter]: #metriccounter
+[metric.gauge]: #metricgauge
+[metric.histogram]: #metrichistogram
 
-#### metric.counter block
+#### `metric.counter`
 
 Defines a metric whose value only goes up.
 
 The following arguments are supported:
 
-| Name                | Type       | Description                                                                                               | Default                  | Required |
-|---------------------|------------|-----------------------------------------------------------------------------------------------------------|--------------------------|----------|
-| `name`              | `string`   | The metric name.                                                                                          |                          | yes      |
-| `action`            | `string`   | The action to take. Valid actions are `inc` and `add`.                                                    |                          | yes      |
-| `description`       | `string`   | The metric's description and help text.                                                                   | `""`                     | no       |
-| `source`            | `string`   | Key from the extracted data map to use for the metric. Defaults to the metric name.                       | `""`                     | no       |
-| `prefix`            | `string`   | The prefix to the metric name.                                                                            | `"loki_process_custom_"` | no       |
-| `max_idle_duration` | `duration` | Maximum amount of time to wait until the metric is marked as 'stale' and removed.                         | `"5m"`                   | no       |
-| `value`             | `string`   | If set, the metric only changes if `source` exactly matches the `value`.                                  | `""`                     | no       |
-| `match_all`         | `bool`     | If set to true, all log lines are counted, without attempting to match the `source` to the extracted map. | `false`                  | no       |
-| `count_entry_bytes` | `bool`     | If set to true, counts all log lines bytes.                                                               | `false`                  | no       |
-
-A counter cannot set both `match_all` to true _and_ a `value`.
-A counter cannot set `count_entry_bytes` without also setting `match_all=true` _or_ `action=add`.
-The valid `action` values are `inc` and `add`. The `inc` action increases the metric value by 1 for each log line that passed the filter.
+Name                | Type       | Description                                                                                               | Default                  | Required
+--------------------|------------|-----------------------------------------------------------------------------------------------------------|--------------------------|---------
+`action`            | `string`   | The action to take. Valid actions are `inc` and `add`.                                                    |                          | yes
+`name`              | `string`   | The metric name.                                                                                          |                          | yes
+`count_entry_bytes` | `bool`     | If set to true, counts all log lines bytes.                                                               | `false`                  | no
+`description`       | `string`   | The metric's description and help text.                                                                   | `""`                     | no
+`match_all`         | `bool`     | If set to true, all log lines are counted, without attempting to match the `source` to the extracted map. | `false`                  | no
+`max_idle_duration` | `duration` | Maximum amount of time to wait until the metric is marked as 'stale' and removed.                         | `"5m"`                   | no
+`prefix`            | `string`   | The prefix to the metric name.                                                                            | `"loki_process_custom_"` | no
+`source`            | `string`   | Key from the extracted data map to use for the metric. Defaults to the metric name.                       | `""`                     | no
+`value`             | `string`   | If set, the metric only changes if `source` exactly matches the `value`.                                  | `""`                     | no
+
+A counter can't set both `match_all` to true _and_ a `value`.
+A counter can't set `count_entry_bytes` without also setting `match_all=true` _or_ `action=add`.
+The valid `action` values are `inc` and `add`.
+The `inc` action increases the metric value by 1 for each log line that passed the filter.
 The `add` action converts the extracted value to a positive float and adds it to the metric.
 
+#### `metric.gauge`
 
-#### metric.gauge block
 Defines a gauge metric whose value can go up or down.
 
 The following arguments are supported:
 
-| Name                | Type       | Description                                                                         | Default                  | Required |
-|---------------------|------------|-------------------------------------------------------------------------------------|--------------------------|----------|
-| `name`              | `string`   | The metric name.                                                                    |                          | yes      |
-| `action`            | `string`   | The action to take. Valid actions are  `inc`, `dec`, `set`, `add`, or `sub`.        |                          | yes      |
-| `description`       | `string`   | The metric's description and help text.                                             | `""`                     | no       |
-| `source`            | `string`   | Key from the extracted data map to use for the metric. Defaults to the metric name. | `""`                     | no       |
-| `prefix`            | `string`   | The prefix to the metric name.                                                      | `"loki_process_custom_"` | no       |
-| `max_idle_duration` | `duration` | Maximum amount of time to wait until the metric is marked as 'stale' and removed.   | `"5m"`                   | no       |
-| `value`             | `string`   | If set, the metric only changes if `source` exactly matches the `value`.            | `""`                     | no       |
-
+Name                | Type       | Description                                                                         | Default                  | Required
+--------------------|------------|-------------------------------------------------------------------------------------|--------------------------|---------
+`action`            | `string`   | The action to take. Valid actions are  `inc`, `dec`, `set`, `add`, or `sub`.        |                          | yes
+`name`              | `string`   | The metric name.                                                                    |                          | yes
+`description`       | `string`   | The metric's description and help text.                                             | `""`                     | no
+`max_idle_duration` | `duration` | Maximum amount of time to wait until the metric is marked as 'stale' and removed.   | `"5m"`                   | no
+`prefix`            | `string`   | The prefix to the metric name.                                                      | `"loki_process_custom_"` | no
+`source`            | `string`   | Key from the extracted data map to use for the metric. Defaults to the metric name. | `""`                     | no
+`value`             | `string`   | If set, the metric only changes if `source` exactly matches the `value`.            | `""`                     | no
 
 The valid `action` values are `inc`, `dec`, `set`, `add`, or `sub`.
 `inc` and `dec` increment and decrement the metric's value by 1 respectively.
 If `set`, `add`, or `sub` is chosen, the extracted value must be convertible to a positive float and is set, added to, or subtracted from the metric's value.
 
+#### `metric.histogram`
 
-#### metric.histogram block
 Defines a histogram metric whose values are recorded in predefined buckets.
 
-
 The following arguments are supported:
 
-| Name                | Type          | Description                                                                         | Default                  | Required |
-|---------------------|---------------|-------------------------------------------------------------------------------------|--------------------------|----------|
-| `name`              | `string`      | The metric name.                                                                    |                          | yes      |
-| `buckets`           | `list(float)` | Prefined buckets                                                                    |                          | yes      |
-| `description`       | `string`      | The metric's description and help text.                                             | `""`                     | no       |
-| `source`            | `string`      | Key from the extracted data map to use for the metric. Defaults to the metric name. | `""`                     | no       |
-| `prefix`            | `string`      | The prefix to the metric name.                                                      | `"loki_process_custom_"` | no       |
-| `max_idle_duration` | `duration`    | Maximum amount of time to wait until the metric is marked as 'stale' and removed.   | `"5m"`                   | no       |
-| `value`             | `string`      | If set, the metric only changes if `source` exactly matches the `value`.            | `""`                     | no       |
+Name                | Type          | Description                                                                         | Default                  | Required
+--------------------|---------------|-------------------------------------------------------------------------------------|--------------------------|---------
+`buckets`           | `list(float)` | Prefined buckets                                                                    |                          | yes
+`name`              | `string`      | The metric name.                                                                    |                          | yes
+`description`       | `string`      | The metric's description and help text.                                             | `""`                     | no
+`max_idle_duration` | `duration`    | Maximum amount of time to wait until the metric is marked as 'stale' and removed.   | `"5m"`                   | no
+`prefix`            | `string`      | The prefix to the metric name.                                                      | `"loki_process_custom_"` | no
+`source`            | `string`      | Key from the extracted data map to use for the metric. Defaults to the metric name. | `""`                     | no
+`value`             | `string`      | If set, the metric only changes if `source` exactly matches the `value`.            | `""`                     | no
 
-#### metrics behavior
+#### `metrics` behavior
 
-If `value` is not present, all incoming log entries match.
+If `value` isn't present, all incoming log entries match.
 
 Label values on created metrics can be dynamic, which can cause exported metrics to explode in cardinality or go stale, for example, when a stream stops receiving new logs.
-To prevent unbounded growth of the `/metrics` endpoint, any metrics which have not been updated within `max_idle_duration` are removed.
+To prevent unbounded growth of the `/metrics` endpoint, any metrics which haven't been updated within `max_idle_duration` are removed.
 The `max_idle_duration` must be greater or equal to `"1s"`, and it defaults to `"5m"`.
 
 The metric values extracted from the log data are internally converted to floats.
@@ -729,11 +877,12 @@ The supported values are the following:
 * integer
 * floating point number
 * string - Two types of string format are supported:
-    * Strings that represent floating point numbers, for example, "0.804" is converted to 0.804.
-    * Duration format strings. Valid time units are “ns”, “us”, “ms”, “s”, “m”, “h”. A value in this format is converted to a floating point number of seconds, for example, "0.5ms" is converted to 0.0005.
+  * Strings that represent floating point numbers, for example, "0.804" is converted to 0.804.
+  * Duration format strings. Valid time units are `"ns"`, `"us"`, `"ms"`, `"s"`, `"m"`, `"h"`.
+    A value in this format is converted to a floating point number of seconds, for example, `"0.5ms"` is converted to `0.0005`.
 * boolean:
-    * true is converted to 1.
-    * false is converted to 0.
+  * `true` is converted to `1`.
+  * `false` is converted to `0`.
 
 The following pipeline creates a counter which increments every time any log line is received by using the `match_all` parameter.
 The pipeline creates a second counter which adds the byte size of these log lines by using the `count_entry_bytes` parameter.
@@ -767,7 +916,7 @@ stage.metrics {
 }
 ```
 
-Here, the first stage uses a regex to extract text in the format `order_status=<string>` in the log line.
+Here, the first stage uses a regular expression to extract text in the format `order_status=<string>` in the log line.
 The second stage, defines a counter which increments the `successful_orders_total` and `failed_orders_total` based on the previously extracted values.
 
 ```alloy
@@ -824,30 +973,28 @@ stage.metrics {
 }
 ```
 
-### stage.multiline block
+### `stage.multiline`
 
 The `stage.multiline` inner block merges multiple lines into a single block before passing it on to the next stage in the pipeline.
 
 The following arguments are supported:
 
-| Name            | Type       | Description                                        | Default | Required |
-| --------------- | ---------- | -------------------------------------------------- | ------- | -------- |
-| `firstline`     | `string`   | Name from extracted data to use for the log entry. |         | yes      |
-| `max_wait_time` | `duration` | The maximum time to wait for a multiline block.    | `"3s"`  | no       |
-| `max_lines`     | `number`   | The maximum number of lines a block can have.      | `128`   | no       |
-
+Name            | Type       | Description                                        | Default | Required
+----------------|------------|----------------------------------------------------|---------|---------
+`firstline`     | `string`   | Name from extracted data to use for the log entry. |         | yes
+`max_lines`     | `number`   | The maximum number of lines a block can have.      | `128`   | no
+`max_wait_time` | `duration` | The maximum time to wait for a multiline block.    | `"3s"`  | no
 
 A new block is identified by the RE2 regular expression passed in `firstline`.
 
-
 Any line that does _not_ match the expression is considered to be part of the block of the previous match.
 If no new logs arrive with `max_wait_time`, the block is sent on.
 The `max_lines` field defines the maximum number of lines a block can have.
 If this is exceeded, a new block is started.
 
-Let's see how this works in practice with an example stage and a stream of log entries from a Flask web service.
+The following example stage and stream of log entries from a Flask web service show how this works.
 
-```
+```text
 stage.multiline {
     firstline     = "^\\[\\d{4}-\\d{2}-\\d{2} \\d{1,2}:\\d{2}:\\d{2}\\]"
     max_wait_time = "10s"
@@ -878,20 +1025,19 @@ Exception: Sorry, this route always breaks
 All 'blocks' that form log entries of separate web requests start with a timestamp in square brackets.
 The stage detects this with the regular expression in `firstline` to collapse all lines of the traceback into a single block and thus a single Loki log entry.
 
-### stage.output block
+### `stage.output`
 
-The `stage.output` inner block configures a processing stage that reads from the extracted map and changes the content of the log entry that is forwarded to the next component.
+The `stage.output` inner block configures a processing stage that reads from the extracted map and changes the content of the log entry that's forwarded to the next component.
 
 The following arguments are supported:
 
-| Name     | Type     | Description                                        | Default | Required |
-| -------- | -------- | -------------------------------------------------- | ------- | -------- |
-| `source` | `string` | Name from extracted data to use for the log entry. |         | yes      |
-
+Name     | Type     | Description                                        | Default | Required
+---------|----------|----------------------------------------------------|---------|---------
+`source` | `string` | Name from extracted data to use for the log entry. |         | yes
 
-Let's see how this works for the following log line and three-stage pipeline:
+The following example log line and three-stage pipeline shows how this works.
 
-```
+```alloy
 {"user": "John Doe", "message": "hello, world!"}
 
 stage.json {
@@ -909,23 +1055,23 @@ stage.output {
 
 The first stage extracts the following key-value pairs into the shared map:
 
-```
+```text
 user: John Doe
 message: hello, world!
 ```
 
 Then, the second stage adds `user="John Doe"` to the label set of the log entry, and the final output stage changes the log line from the original JSON to `hello, world!`.
 
-### stage.pack block
+### `stage.pack`
 
 The `stage.pack` inner block configures a transforming stage that replaces the log entry with a JSON object that embeds extracted values and labels with it.
 
 The following arguments are supported:
 
-| Name               | Type           | Description                                                                     | Default | Required |
-| ------------------ | -------------- | ------------------------------------------------------------------------------- | ------- | -------- |
-| `labels`           | `list(string)` | The values from the extracted data and labels to pack with the log entry.       |         | yes      |
-| `ingest_timestamp` | `bool`         | Whether to replace the log entry timestamp with the time the `pack` stage runs. | `true`  | no       |
+Name               | Type           | Description                                                                     | Default | Required
+-------------------|----------------|---------------------------------------------------------------------------------|---------|---------
+`labels`           | `list(string)` | The values from the extracted data and labels to pack with the log entry.       |         | yes
+`ingest_timestamp` | `bool`         | Whether to replace the log entry timestamp with the time the `pack` stage runs. | `true`  | no
 
 This stage lets you embed extracted values and labels together with the log line, by packing them into a JSON object.
 The original message is stored under the `_entry` key, and all other keys retain their values.
@@ -935,12 +1081,13 @@ The querying capabilities of Loki make it easy to still access this data so it c
 
 For example, consider the following log entry:
 
-```
+```text
 log_line: "something went wrong"
 labels:   { "level" = "error", "env" = "dev", "user_id" = "f8fas0r" }
 ```
 
 and this processing stage:
+
 ```alloy
 stage.pack {
     labels = ["env", "user_id"]
@@ -957,36 +1104,35 @@ The stage transforms the log entry into the following JSON object, where the two
 }
 ```
 
-At query time, Loki's [`unpack` parser][unpack parser] can be used to access these embedded labels and replace the log line with the original one stored in the `_entry` field automatically.
+At query time, the Loki [`unpack` parser][unpack parser] can be used to access these embedded labels and replace the log line with the original one stored in the `_entry` field automatically.
 
 [unpack parser]: https://grafana.com/docs/loki/latest/logql/log_queries/#unpack
 
 When combining several log streams to use with the `pack` stage, you can set `ingest_timestamp` to true to avoid interlaced timestamps and out-of-order ingestion issues.
 
-### stage.regex block
+### `stage.regex`
 
 The `stage.regex` inner block configures a processing stage that parses log lines using regular expressions and uses named capture groups for adding data into the shared extracted map of values.
 
 The following arguments are supported:
 
-| Name         | Type     | Description                                                        | Default | Required |
-| ------------ | -------- | ------------------------------------------------------------------ | ------- | -------- |
-| `expression` | `string` | A valid RE2 regular expression. Each capture group must be named.  |         | yes      |
-| `source`     | `string` | Name from extracted data to parse. If empty, uses the log message. | `""`    | no       |
-
+Name         | Type     | Description                                                        | Default | Required
+-------------|----------|--------------------------------------------------------------------|---------|---------
+`expression` | `string` | A valid RE2 regular expression. Each capture group must be named.  |         | yes
+`source`     | `string` | Name from extracted data to parse. If empty, uses the log message. | `""`    | no
 
-The `expression` field needs to be a RE2 regex string.
+The `expression` field needs to be a RE2 regular expression string.
 Every matched capture group is added to the extracted map, so it must be named like: `(?P<name>re)`.
 The name of the capture group is then used as the key in the extracted map for the matched value.
 
-Because of how {{< param "PRODUCT_NAME" >}} syntax strings work, any backslashes in `expression` must be escaped with a double backslash; for example `"\\w"` or `"\\S+"`.
+Because of how {{< param "PRODUCT_NAME" >}} syntax strings work, any backslashes in `expression` must be escaped with a double backslash, for example, `"\\w"` or `"\\S+"`.
 
 If the `source` is empty or missing, then the stage parses the log line itself.
 If it's set, the stage parses a previously extracted value with the same name.
 
-Given the following log line and regex stage, the extracted values are shown below:
+Given the following log line and regular expression stage, the extracted values are shown below:
 
-```
+```alloy
 2019-01-01T01:00:00.000000001Z stderr P i'm a log message!
 
 stage.regex {
@@ -999,11 +1145,11 @@ flags: P,
 content: i'm a log message
 ```
 
-On the other hand, if the `source` value is set, then the regex is applied to the value stored in the shared map under that name.
+On the other hand, if the `source` value is set, then the regular expression is applied to the value stored in the shared map under that name.
 
-Let's see what happens when the following log line is put through this two-stage pipeline:
+The following log line is put through this two-stage pipeline:
 
-```
+```alloy
 {"timestamp":"2022-01-01T01:00:00.000000001Z"}
 
 stage.json {
@@ -1017,28 +1163,28 @@ stage.regex {
 
 The first stage adds the following key-value pair into the extracted map:
 
-```
+```text
 time: 2022-01-01T01:00:00.000000001Z
 ```
 
-Then, the regex stage parses the value for time from the shared values and appends the subsequent key-value pair back into the extracted values map:
+Then, the regular expression stage parses the value for time from the shared values and appends the subsequent key-value pair back into the extracted values map:
 
-```
+```text
 year: 2022
 ```
 
-### stage.replace block
+### `stage.replace`
 
 The `stage.replace` inner block configures a stage that parses a log line using a regular expression and replaces the log line contents.
-Named capture groups in the regex also support adding data into the shared extracted map.
+Named capture groups in the regular expression also support adding data into the shared extracted map.
 
 The following arguments are supported:
 
-| Name         | Type     | Description                                                     | Default | Required |
-| ------------ | -------- | --------------------------------------------------------------- | ------- | -------- |
-| `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       |
+Name         | Type     | Description                                                     | Default | Required
+-------------|----------|-----------------------------------------------------------------|---------|---------
+`expression` | `string` | A RE2 regular expression containing capture groups.             |         | yes
+`replace`    | `string` | Value replaced by the capture group.                            |         | no
+`source`     | `string` | Source of the data to parse. If empty, it uses the log message. |         | no
 
 Each capture group and named capture group in `expression` is replaced with the value given in `replace`.
 
@@ -1050,11 +1196,12 @@ 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.
 
-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*"`.
+Because of how {{< param "PRODUCT_NAME" >}} syntax treats backslashes in double-quoted strings, all backslashes in a regular 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.
+The following log line and stage shows how this works.
+Since `source` is omitted, the replacement occurs on the log line itself.
 
-```
+```alloy
 2023-01-01T01:00:00.000000001Z stderr P i'm a log message who has sensitive information with password xyz!
 
 stage.replace {
@@ -1065,7 +1212,7 @@ stage.replace {
 
 The log line is transformed to
 
-```
+```text
 2023-01-01T01:00:00.000000001Z stderr P i'm a log message who has sensitive information with password *****!
 ```
 
@@ -1073,7 +1220,7 @@ If `replace` is empty, then the captured value is omitted instead.
 
 In the following example, `source` is defined.
 
-```
+```alloy
 {"time":"2023-01-01T01:00:00.000000001Z", "level": "info", "msg":"11.11.11.11 - \"POST /loki/api/push/ HTTP/1.1\" 200 932 \"-\" \"Mozilla/5.0\"}
 
 stage.json {
@@ -1089,7 +1236,7 @@ stage.replace {
 
 The JSON stage adds the following key-value pairs into the extracted map:
 
-```
+```text
 time: 2023-01-01T01:00:00.000000001Z
 level: info
 msg: "11.11.11.11 - "POST /loki/api/push/ HTTP/1.1" 200 932 "-" "Mozilla/5.0"
@@ -1099,7 +1246,7 @@ The `replace` stage acts on the `msg` value. The capture group matches against `
 
 The `msg` value is finally transformed into:
 
-```
+```text
 msg: "11.11.11.11 - "POST redacted_url HTTP/1.1" 200 932 "-" "Mozilla/5.0"
 ```
 
@@ -1107,9 +1254,9 @@ The `replace` field can use a set of templating functions, by utilizing Go's [te
 
 [text/template]: https://pkg.go.dev/text/template
 
-Let's see how this works with named capture groups with a sample log line and stage.
+The following exampel shows how this works with named capture groups with a sample log line and stage.
 
-```
+```alloy
 11.11.11.11 - alloy [01/Jan/2023:00:00:01 +0200]
 
 stage.replace {
@@ -1118,10 +1265,10 @@ stage.replace {
 }
 ```
 
-Since `source` is empty, the regex parses the log line itself and extracts the named capture groups to the shared map of values.
+Since `source` is empty, the regular expression parses the log line itself and extracts the named capture groups to the shared map of values.
 The `replace` field acts on these extracted values and converts them to uppercase:
 
-```
+```text
 ip: 11.11.11.11
 identd: -
 user: FRANK
@@ -1130,30 +1277,31 @@ timestamp: 01/JAN/2023:00:00:01 +0200
 
 and the log line becomes:
 
-```
+```text
 11.11.11.11 - FRANK [01/JAN/2023:00:00:01 +0200]
 ```
 
 The following list contains available functions with examples of more complex `replace` fields.
 
-```
+```text
 ToLower, ToUpper, Replace, Trim, TrimLeftTrimRight, TrimPrefix, TrimSuffix, TrimSpace, Hash, Sha2Hash, regexReplaceAll, regexReplaceAllLiteral
 
 "{{ if eq .Value \"200\" }}{{ Replace .Value \"200\" \"HttpStatusOk\" -1 }}{{ else }}{{ .Value | ToUpper }}{{ end }}"
 "*IP4*{{ .Value | Hash "salt" }}*"
 ```
 
-### stage.sampling block
+### `stage.sampling`
 
-The `sampling` stage is used to sample the logs. Configuring the value `rate = 0.1` means that 10% of the logs will continue to be processed.
+The `sampling` stage is used to sample the logs.
+Configuring the value `rate = 0.1` means that 10% of the logs will continue to be processed.
 The remaining 90% of the logs will be dropped.
 
 The following arguments are supported:
 
-| Name                  | Type     | Description                                                                                        | Default        | Required |
-|-----------------------|----------|----------------------------------------------------------------------------------------------------|----------------|----------|
-| `rate`                | `float`  | The sampling rate in a range of `[0, 1]`                                                           |                | yes      |
-| `drop_counter_reason` | `string` | The label to add to `loki_process_dropped_lines_total` metric when logs are dropped by this stage. | sampling_stage | no       |
+Name                  | Type     | Description                                                                                        | Default        | Required
+----------------------|----------|----------------------------------------------------------------------------------------------------|----------------|---------
+`rate`                | `float`  | The sampling rate in a range of `[0, 1]`                                                           |                | yes
+`drop_counter_reason` | `string` | The label to add to `loki_process_dropped_lines_total` metric when logs are dropped by this stage. | sampling_stage | no
 
 For example, the configuration below will sample 25% of the logs and drop the remaining 75%.
 When logs are dropped, the `loki_process_dropped_lines_total` metric is incremented with an additional `reason=logs_sampling` label.
@@ -1165,15 +1313,15 @@ stage.sampling {
 }
 ```
 
-### stage.static_labels block
+### `stage.static_labels`
 
 The `stage.static_labels` inner block configures a static_labels processing stage that adds a static set of labels to incoming log entries.
 
 The following arguments are supported:
 
-| Name     | Type          | Description                                    | Default | Required |
-| -------- | ------------- | ---------------------------------------------- | ------- | -------- |
-| `values` | `map(string)` | Configures a `static_labels` processing stage. | `{}`    | no       |
+Name     | Type          | Description                                    | Default | Required
+---------|---------------|------------------------------------------------|---------|---------
+`values` | `map(string)` | Configures a `static_labels` processing stage. | `{}`    | no
 
 
 ```alloy
@@ -1185,7 +1333,29 @@ stage.static_labels {
 }
 ```
 
-### stage.template block
+### `stage.structured_metadata`
+
+The `stage.structured_metadata` inner block configures a stage that can read data from the extracted values map and add them to log entries as structured metadata.
+
+The following arguments are supported:
+
+Name     | Type          | Description                                                                 | Default | Required
+---------|---------------|-----------------------------------------------------------------------------|---------|---------
+`values` | `map(string)` | Specifies the list of labels to add from extracted values map to log entry. | `{}`    | no
+
+In a `structured_metadata` stage, the map's keys define the label to set and the values are how to look them up.
+If the value is empty, it's inferred to be the same as the key.
+
+```alloy
+stage.structured_metadata {
+    values = {
+      env  = "",         // Sets up an 'env' property to structured metadata, based on the 'env' extracted value.
+      user = "username", // Sets up a 'user' property to structured metadata, based on the 'username' extracted value.
+    }
+}
+```
+
+### `stage.template`
 
 The `stage.template` inner block configures a transforming stage that allows users to manipulate the values in the extracted map by using Go's `text/template` [package][] syntax.
 This stage is primarily useful for manipulating and standardizing data from previous stages before setting them as labels in a subsequent stage.
@@ -1197,21 +1367,21 @@ The template stage can also create new keys in the extracted map.
 
 The following arguments are supported:
 
-| Name       | Type     | Description                                                                          | Default | Required |
-| ---------- | -------- | ------------------------------------------------------------------------------------ | ------- | -------- |
-| `source`   | `string` | Name from extracted data to parse. If the key doesn't exist, a new entry is created. |         | yes      |
-| `template` | `string` | Go template string to use.                                                           |         | yes      |
+Name       | Type     | Description                                                                          | Default | Required
+-----------|----------|--------------------------------------------------------------------------------------|---------|---------
+`source`   | `string` | Name from extracted data to parse. If the key doesn't exist, a new entry is created. |         | yes
+`template` | `string` | Go template string to use.                                                           |         | yes
 
 The template string can be any valid template that can be used by Go's `text/template`.
 It supports all functions from the [sprig package][], as well as the following list of custom functions:
 
 [sprig package]: http://masterminds.github.io/sprig/
 
-```
+```text
 ToLower, ToUpper, Replace, Trim, TrimLeftTrimRight, TrimPrefix, TrimSuffix, TrimSpace, Hash, Sha2Hash, regexReplaceAll, regexReplaceAllLiteral
 ```
 
-More details on each of these functions can be found in the [supported functions][] section below.
+More details on each of these functions can be found in the [supported functions][] section.
 
 [supported functions]: #supported-functions
 
@@ -1244,7 +1414,8 @@ stage.template {
 }
 ```
 
-A special key named `Entry` can be used to reference the current line; this can be useful when you need to append/prepend something to the log line, like this snippet:
+A special key named `Entry` can be used to reference the current line.
+This can be useful when you need to append/prepend something to the log line, like this snippet:
 
 ```alloy
 stage.template {
@@ -1257,14 +1428,15 @@ stage.output {
 ```
 
 #### Supported functions
+
 In addition to supporting all functions from the [sprig package](http://masterminds.github.io/sprig/), the `template` stage supports the following custom functions.
 
-##### ToLower and ToUpper
+##### `ToLower` and `ToUpper`
 
-`ToLower` and `ToUpper` convert the entire string to lowercase and
-uppercase, respectively.
+`ToLower` and `ToUpper` convert the entire string to lowercase and uppercase, respectively.
+
+The following example shows how you can use this function.
 
-Examples:
 ```alloy
 stage.template {
     source   = "out"
@@ -1276,17 +1448,17 @@ stage.template {
 }
 ```
 
-##### Replace
+##### `Replace`
 
 The `Replace` function syntax is defined as `{{ Replace <string> <old> <new> <n> }}`.
 
-The function returns a copy of the input string, with instances of the `<old>`
-argument being replaced by `<new>`. The function replaces up to `<n>`
-non-overlapping instances of the second argument. If `<n>` is less than zero,
-there is no limit on the number of replacement. Finally, if `<old>` is empty,
-it matches before and after every UTF-8 character in the string.
+The function returns a copy of the input string, with instances of the `<old>` argument being replaced by `<new>`.
+The function replaces up to `<n>` non-overlapping instances of the second argument.
+If `<n>` is less than zero, there is no limit on the number of replacements.
+Finally, if `<old>` is empty, it matches before and after every UTF-8 character in the string.
 
 This example replaces the first two instances of the `loki` word by `Loki`:
+
 ```alloy
 stage.template {
     source   = "output"
@@ -1294,17 +1466,14 @@ stage.template {
 }
 ```
 
-##### Trim, TrimLeft, TrimRight, TrimSpace, TrimPrefix, TrimSuffix
+##### `Trim`, `TrimLeft`, `TrimRight`, `TrimSpace`, `TrimPrefix`, `TrimSuffix`
 
-* `Trim` returns a slice of the string `s` with all leading and trailing Unicode
-  code points contained in `cutset` removed.
-* `TrimLeft` and `TrimRight` are the same as Trim except that they
-  trim only leading and trailing characters, respectively.
-* `TrimSpace` returns a slice of the string s, with all leading and trailing
-white space removed, as defined by Unicode.
+* `Trim` returns a slice of the string `s` with all leading and trailing Unicode code points contained in `cutset` removed.
+* `TrimLeft` and `TrimRight` are the same as Trim except that they trim only leading and trailing characters, respectively.
+* `TrimSpace` returns a slice of the string s, with all leading and trailing white space removed, as defined by Unicode.
 * `TrimPrefix` and `TrimSuffix` trim the supplied prefix or suffix, respectively.
 
-Examples:
+The following example shows how you can use this function.
 
 ```alloy
 stage.template {
@@ -1321,16 +1490,14 @@ stage.template {
 }
 ```
 
-##### Regex
+##### `regexReplaceAll` and `regexReplaceAllLiteral`
 
-`regexReplaceAll` returns a copy of the input string, replacing matches of the
-Regexp with the replacement string. Inside the replacement string, `$` characters
-are interpreted as in Expand functions, so for instance, $1 represents the first captured
-submatch.
+`regexReplaceAll` returns a copy of the input string, replacing matches of the Regexp with the replacement string.
+Inside the replacement string, `$` characters are interpreted as in Expand functions.
+For example, $1 represents the first captured submatch.
 
-`regexReplaceAllLiteral` returns a copy of the input string, replacing matches
-of the Regexp with the replacement string. The replacement string is
-substituted directly, without using Expand.
+`regexReplaceAllLiteral` returns a copy of the input string, replacing matches of the Regexp with the replacement string.
+The replacement string is substituted directly, without using Expand.
 
 ```alloy
 stage.template {
@@ -1343,13 +1510,15 @@ stage.template {
 }
 ```
 
-##### Hash and Sha2Hash
+##### `Hash` and `Sha2Hash`
+
+`Hash` returns a `Sha3_256` hash of the string, represented as a hexadecimal number of 64 digits.
+You can use it to obfuscate sensitive data and PII in the logs.
+It requires a (fixed) salt value, to add complexity to low input domains, for example, all possible social security numbers.
+`Sha2Hash` returns a `Sha2_256` of the string which is faster and less CPU-intensive than `Hash`, however it's less secure.
 
-`Hash` returns a `Sha3_256` hash of the string, represented as a hexadecimal number of 64 digits. You can use it to obfuscate sensitive data and PII in the logs.
-It requires a (fixed) salt value, to add complexity to low input domains (e.g., all possible social security numbers).
-`Sha2Hash` returns a `Sha2_256` of the string which is faster and less CPU-intensive than `Hash`, however it is less secure.
+The following example shows how you can use this function.
 
-Examples:
 ```alloy
 stage.template {
     source   = "output"
@@ -1363,30 +1532,29 @@ stage.template {
 
 We recommend using Hash as it has a stronger hashing algorithm.
 
-### stage.tenant block
+### `stage.tenant`
 
-The `stage.tenant` inner block sets the tenant ID for the log entry by obtaining it from a
-field in the extracted data map, a label, or a provided value.
+The `stage.tenant` inner block sets the tenant ID for the log entry by obtaining it from a field in the extracted data map, a label, or a provided value.
 
 The following arguments are supported:
 
-| Name     | Type     | Description                                            | Default | Required |
-| -------- | -------- | ------------------------------------------------------ | ------- | -------- |
-| `label`  | `string` | The label to set as tenant ID.                         | `""`    | no       |
-| `source` | `string` | The name from the extracted value to use as tenant ID. | `""`    | no       |
-| `value`  | `string` | The value to set as the tenant ID.                     | `""`    | no       |
+Name     | Type     | Description                                            | Default | Required
+---------|----------|--------------------------------------------------------|---------|---------
+`label`  | `string` | The label to set as tenant ID.                         | `""`    | no
+`source` | `string` | The name from the extracted value to use as tenant ID. | `""`    | no
+`value`  | `string` | The value to set as the tenant ID.                     | `""`    | no
 
 The block expects only one of `label`, `source` or `value` to be provided.
 
 The following stage assigns the fixed value `team-a` as the tenant ID:
+
 ```alloy
 stage.tenant {
     value = "team-a"
 }
 ```
 
-This stage extracts the tenant ID from the `customer_id` field after
-parsing the log entry as JSON in the shared extracted map:
+This stage extracts the tenant ID from the `customer_id` field after parsing the log entry as JSON in the shared extracted map:
 
 ```alloy
 stage.json {
@@ -1408,36 +1576,33 @@ stage.tenant {
 }
 ```
 
-### stage.timestamp block
+### `stage.timestamp`
 
-The `stage.timestamp` inner block configures a processing stage that sets the
-timestamp of log entries before they're forwarded to the next component. When
-no timestamp stage is set, the log entry timestamp defaults to the time when
-the log entry was scraped.
+The `stage.timestamp` inner block configures a processing stage that sets the timestamp of log entries before they're forwarded to the next component.
+When no timestamp stage is set, the log entry timestamp defaults to the time when the log entry was scraped.
 
 The following arguments are supported:
 
-| Name                | Type           | Description                                                 | Default   | Required |
-| ------------------- | -------------- | ----------------------------------------------------------- | --------- | -------- |
-| `source`            | `string`       | Name from extracted values map to use for the timestamp.    |           | yes      |
-| `format`            | `string`       | Determines how to parse the source string.                  |           | yes      |
-| `fallback_formats`  | `list(string)` | Fallback formats to try if the `format` field fails.        | `[]`      | no       |
-| `location`          | `string`       | IANA Timezone Database location to use when parsing.        | `""`      | no       |
-| `action_on_failure` | `string`       | What to do when the timestamp can't be extracted or parsed. | `"fudge"` | no       |
+Name                | Type           | Description                                                 | Default   | Required
+--------------------|----------------|-------------------------------------------------------------|-----------|---------
+`format`            | `string`       | Determines how to parse the source string.                  |           | yes
+`source`            | `string`       | Name from extracted values map to use for the timestamp.    |           | yes
+`action_on_failure` | `string`       | What to do when the timestamp can't be extracted or parsed. | `"fudge"` | no
+`fallback_formats`  | `list(string)` | Fallback formats to try if the `format` field fails.        | `[]`      | no
+`location`          | `string`       | IANA Timezone Database location to use when parsing.        | `""`      | no
 
 {{< admonition type="note" >}}
 Be careful with further stages which may also override the timestamp.
 For example, a `stage.pack` with `ingest_timestamp` set to `true` could replace the timestamp which `stage.timestamp` had set earlier in the pipeline.
 {{< /admonition >}}
 
-The `source` field defines which value from the shared map of extracted values
-the stage should attempt to parse as a timestamp.
+The `source` field defines which value from the shared map of extracted values the stage should attempt to parse as a timestamp.
 
 The `format` field defines _how_ that source should be parsed.
 
 The `format` can be set to one of the following shorthand values for commonly used forms:
 
-```
+```text
 ANSIC: Mon Jan _2 15:04:05 2006
 UnixDate: Mon Jan _2 15:04:05 MST 2006
 RubyDate: Mon Jan 02 15:04:05 -0700 2006
@@ -1450,67 +1615,56 @@ RFC3339: 2006-01-02T15:04:05-07:00
 RFC3339Nano: 2006-01-02T15:04:05.999999999-07:00
 ```
 
-Additionally, support for common Unix timestamps is supported with the
-following format values:
+Additionally, support for common Unix timestamps is supported with the following format values:
 
-```
+```text
 Unix: 1562708916 or with fractions 1562708916.000000123
 UnixMs: 1562708916414
 UnixUs: 1562708916414123
 UnixNs: 1562708916000000123
 ```
 
-Otherwise, the field accepts a custom format string that defines how an
-arbitrary reference point in history should
-be interpreted by the stage. The arbitrary reference point is Mon Jan 2 15:04:05 -0700 MST 2006.
+Otherwise, the field accepts a custom format string that defines how an arbitrary reference point in history should be interpreted by the stage.
+The arbitrary reference point is Mon Jan 2 15:04:05 -0700 MST 2006.
 
-The string value of the field is passed directly to the layout parameter in
-Go's [`time.Parse`](https://pkg.go.dev/time#Parse) function.
+The string value of the field is passed directly to the layout parameter in Go's [`time.Parse`](https://pkg.go.dev/time#Parse) function.
 
-If the custom format has no year component, the stage uses the current year,
-according to the system's clock.
+If the custom format has no year component, the stage uses the current year, according to the system's clock.
 
-The following table shows the supported reference values to use when defining a
-custom format.
+The following table shows the supported reference values to use when defining a custom format.
 
-| Timestamp Component | Format value                                                                                                             |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| Year                | 06, 2006                                                                                                                 |
-| Month               | 1, 01, Jan, January                                                                                                      |
-| Day                 | 2, 02, _2 (two digits right justified)                                                                                   |
-| Day of the week     | Mon, Monday                                                                                                              |
-| Hour                | 3 (12-hour), 03 (12-hour zero prefixed), 15 (24-hour)                                                                    |
-| Minute              | 4, 04                                                                                                                    |
-| Second              | 5, 05                                                                                                                    |
-| Fraction of second  | .000 (ms zero prefixed), .000000 (μs), .000000000 (ns), .999 (ms without trailing zeroes), .999999 (μs), .999999999 (ns) |
-| 12-hour period      | pm, PM                                                                                                                   |
-| Timezone name       | MST                                                                                                                      |
-| Timezone offset     | -0700, -070000 (with seconds), -07, -07:00, -07:00:00 (with seconds)                                                     |
-| Timezone ISO-8601   | Z0700 (Z for UTC or time offset), Z070000, Z07, Z07:00, Z07:00:00                                                        |
+Timestamp Component | Format value
+--------------------|-------------------------------------------------------------------------------------------------------------------------
+Year                | 06, 2006
+Month               | 1, 01, Jan, January
+Day                 | 2, 02, _2 (two digits right justified)
+Day of the week     | Mon, Monday
+Hour                | 3 (12-hour), 03 (12-hour zero prefixed), 15 (24-hour)
+Minute              | 4, 04
+Second              | 5, 05
+Fraction of second  | .000 (ms zero prefixed), .000000 (μs), .000000000 (ns), .999 (ms without trailing zeroes), .999999 (μs), .999999999 (ns)
+12-hour period      | pm, PM
+Timezone name       | MST
+Timezone offset     | -0700, -070000 (with seconds), -07, -07:00, -07:00:00 (with seconds)
+Timezone ISO-8601   | Z0700 (Z for UTC or time offset), Z070000, Z07, Z07:00, Z07:00:00
 
 {{< admonition type="note" >}}
 If you define a custom timestamp, the `format` value for each timestamp component must be one of the values specified in the table above.
 For example, to indicate the year, the `format` value must be `06` or `2006` and not any other value like `23` or `2023`.
 {{< /admonition >}}
 
-The `fallback_formats` field defines one or more format fields to try and parse
-the timestamp with, if parsing with `format` fails.
+The `fallback_formats` field defines one or more format fields to try and parse the timestamp with, if parsing with `format` fails.
 
-The `location` field must be a valid IANA Timezone Database location and
-determines in which timezone the timestamp value is interpreted to be in.
+The `location` field must be a valid IANA Timezone Database location and determines in which timezone the timestamp value is interpreted to be in.
 
-The `action_on_failure` field defines what should happen when the source field
-doesn't exist in the shared extracted map, or if the timestamp parsing fails.
+The `action_on_failure` field defines what should happen when the source field doesn't exist in the shared extracted map, or if the timestamp parsing fails.
 
 The supported actions are:
 
-* fudge (default): Change the timestamp to the last known timestamp, summing up
-  1 nanosecond (to guarantee log entries ordering).
-* skip: Do not change the timestamp and keep the time when the log entry was
-  scraped.
+* fudge (default): Change the timestamp to the last known timestamp, summing up 1 nanosecond to guarantee log entries ordering.
+* skip: Don't change the timestamp and keep the time when the log entry was scraped.
 
-The following stage fetches the `time` value from the shared values map, parses
-it as a RFC3339 format, and sets it as the log entry's timestamp.
+The following stage fetches the `time` value from the shared values map, parses it as a RFC3339 format, and sets it as the log entry's timestamp.
 
 ```alloy
 stage.timestamp {
@@ -1528,179 +1682,13 @@ stage.timestamp {
 }
 ```
 
-### stage.geoip block
-
-The `stage.geoip` inner block configures a processing stage that reads an IP address and populates the shared map with geoip fields. Maxmind’s GeoIP2 database is used for the lookup.
-
-The following arguments are supported:
-
-| Name             | Type          | Description                                        | Default | Required |
-| ---------------- | ------------- | -------------------------------------------------- | ------- | -------- |
-| `db`             | `string`      | Path to the Maxmind DB file.                       |         | yes      |
-| `source`         | `string`      | IP from extracted data to parse.                   |         | yes      |
-| `db_type`        | `string`      | Maxmind DB type. Allowed values are "city", "asn", "country". |         | no       |
-| `custom_lookups` | `map(string)` | Key-value pairs of JMESPath expressions.           |         | no       |
-
-
-#### GeoIP with City database example:
-
-```
-{"log":"log message","client_ip":"34.120.177.193"}
-
-loki.process "example" {
-    stage.json {
-        expressions = {ip = "client_ip"}
-    }
-
-    stage.geoip {
-        source  = "ip"
-        db      = "/path/to/db/GeoLite2-City.mmdb"
-        db_type = "city"
-    }
-
-    stage.labels {
-        values = {
-            geoip_city_name          = "",
-            geoip_country_name       = "",
-            geoip_country_code       = "",
-            geoip_continent_name     = "",
-            geoip_continent_code     = "",
-            geoip_location_latitude  = "",
-            geoip_location_longitude = "",
-            geoip_postal_code        = "",
-            geoip_timezone           = "",
-            geoip_subdivision_name   = "",
-            geoip_subdivision_code   = "",
-        }
-    }
-}
-```
-
-The `json` stage extracts the IP address from the `client_ip` key in the log line.
-Then the extracted `ip` value is given as source to geoip stage. The geoip stage performs a lookup on the IP and populates the following fields in the shared map which are added as labels using the `labels` stage.
-
-The extracted data from the IP used in this example:
-
-- geoip_city_name: Kansas City
-- geoip_country_name: United States
-- geoip_country_code: US
-- geoip_continent_name: North America
-- geoip_continent_code: NA
-- geoip_location_latitude: 39.1027
-- geoip_location_longitude: -94.5778
-- geoip_postal_code: 64184
-- geoip_timezone: America/Chicago
-- geoip_subdivision_name: Missouri
-- geoip_subdivision_code: MO
-
-#### GeoIP with ASN (Autonomous System Number) database example
-
-```
-loki.process "example" {
-    stage.json {
-        expressions = {ip = "client_ip"}
-    }
-
-    stage.geoip {
-        source  = "ip"
-        db      = "/path/to/db/GeoIP2-ASN.mmdb"
-        db_type = "asn"
-    }
-
-    stage.labels {
-        values = {
-            geoip_autonomous_system_number       = "",
-            geoip_autonomous_system_organization = "",
-        }
-    }
-}
-```
-
-The `json` stage extracts the IP address from the `client_ip` key in the log line.
-Then the extracted `ip` value is given as source to geoip stage. The geoip stage performs a lookup on the IP and populates the shared map.
-
-The extracted data from the IP used in this example:
-
-- geoip_autonomous_system_number: 396982
-- geoip_autonomous_system_organization: GOOGLE-CLOUD-PLATFORM
-
-#### GeoIP with Country database example:
-
-```
-{"log":"log message","client_ip":"34.120.177.193"}
-
-loki.process "example" {
-    stage.json {
-        expressions = {ip = "client_ip"}
-    }
-
-    stage.geoip {
-        source  = "ip"
-        db      = "/path/to/db/GeoLite2-Country.mmdb"
-        db_type = "country"
-    }
-
-    stage.labels {
-        values = {
-            geoip_country_name       = "",
-            geoip_country_code       = "",
-            geoip_continent_name     = "",
-            geoip_continent_code     = "",
-        }
-    }
-}
-```
-
-The `json` stage extracts the IP address from the `client_ip` key in the log line.
-Then the extracted `ip` value is given as source to geoip stage. The geoip stage performs a lookup on the IP and populates the following fields in the shared map which are added as labels using the `labels` stage.
-
-The extracted data from the IP used in this example:
-
-- geoip_country_name: United States
-- geoip_country_code: US
-- geoip_continent_name: North America
-- geoip_continent_code: NA
-
-#### GeoIP with custom fields example
-
-If the MMDB file used is enriched with custom data, for example, private IP addresses as explained in [the Maxmind blog post](https://github.com/maxmind/mmdb-from-go-blogpost), then it can be extracted from the record using the `custom_lookups` attribute.
-
-```
-loki.process "example" {
-    stage.json {
-        expressions = {ip = "client_ip"}
-    }
-
-    stage.geoip {
-        source         = "ip"
-        db             = "/path/to/db/GeoIP2-Enriched.mmdb"
-        db_type        = "city"
-        custom_lookups = {
-            "department"  = "MyCompany.DeptName",
-            "parent_vnet" = "MyCompany.ParentVNet",
-            "subnet"      = "MyCompany.Subnet",
-        }
-    }
-
-    stage.labels {
-        values = {
-            department  = "",
-            parent_vnet = "",
-            subnet      = "",
-        }
-    }
-}
-```
-The `json` stage extracts the IP address from the `client_ip` key in the log line.
-Then the extracted `ip` value is given as source to geoip stage. The geoip stage performs a lookup on the IP and populates the shared map with the data from the city database results in addition to the custom lookups. Lastly, the custom lookup fields from the shared map are added as labels.
-
 ## Exported fields
 
 The following fields are exported and can be referenced by other components:
 
-| Name       | Type           | Description                                                   |
-| ---------- | -------------- | ------------------------------------------------------------- |
-| `receiver` | `LogsReceiver` | A value that other components can use to send log entries to. |
+Name       | Type           | Description
+-----------|----------------|--------------------------------------------------------------
+`receiver` | `LogsReceiver` | A value that other components can use to send log entries to.
 
 ## Component health
 
@@ -1708,7 +1696,7 @@ The following fields are exported and can be referenced by other components:
 
 ## Debug information
 
-`loki.process` does not expose any component-specific debug information.
+`loki.process` doesn't expose any component-specific debug information.
 
 ## Debug metrics
 
@@ -1717,8 +1705,7 @@ The following fields are exported and can be referenced by other components:
 
 ## Example
 
-This example creates a `loki.process` component that extracts the `environment`
-value from a JSON log line and sets it as a label named 'env'.
+This example creates a `loki.process` component that extracts the `environment` value from a JSON log line and sets it as a label named 'env'.
 
 ```alloy
 loki.process "local" {
diff --git a/docs/sources/reference/components/loki/loki.relabel.md b/docs/sources/reference/components/loki/loki.relabel.md
index af5e834293..ba5f2b7f60 100644
--- a/docs/sources/reference/components/loki/loki.relabel.md
+++ b/docs/sources/reference/components/loki/loki.relabel.md
@@ -6,33 +6,27 @@ description: Learn about loki.relabel
 title: loki.relabel
 ---
 
-# loki.relabel
+# `loki.relabel`
 
-The `loki.relabel` component rewrites the label set of each log entry passed to
-its receiver by applying one or more relabeling `rule`s and forwards the
-results to the list of receivers in the component's arguments.
+The `loki.relabel` component rewrites the label set of each log entry passed to its receiver by applying one or more relabeling `rule`s and forwards the results to the list of receivers in the component's arguments.
 
-If no labels remain after the relabeling rules are applied, then the log
-entries are dropped.
+If no labels remain after the relabeling rules are applied, then the log entries are dropped.
 
-The most common use of `loki.relabel` is to filter log entries or standardize
-the label set that is passed to one or more downstream receivers. The `rule`
-blocks are applied to the label set of each log entry in order of their
-appearance in the configuration file. The configured rules can be retrieved by
-calling the function in the `rules` export field.
+The most common use of `loki.relabel` is to filter log entries or standardize the label set that is passed to one or more downstream receivers.
+The `rule` blocks are applied to the label set of each log entry in order of their appearance in the configuration file.
+The configured rules can be retrieved by calling the function in the `rules` export field.
 
-If you're looking for a way to process the log entry contents, take a look at
-[the `loki.process` component][loki.process] instead.
+If you're looking for a way to process the log entry contents, use [the `loki.process` component][loki.process] instead.
 
 [loki.process]: ../loki.process/
 
-Multiple `loki.relabel` components can be specified by giving them different labels.
+Youc an specify multiple `loki.relabel` components by giving them different labels.
 
 ## Usage
 
 ```alloy
-loki.relabel "LABEL" {
-  forward_to = RECEIVER_LIST
+loki.relabel "<LABEL>" {
+  forward_to = <RECEIVER_LIST>
 
   rule {
     ...
@@ -44,7 +38,7 @@ loki.relabel "LABEL" {
 
 ## Arguments
 
-The following arguments are supported:
+You can use the following arguments with `loki.relabel`:
 
 Name             | Type             | Description                                                    | Default | Required
 -----------------|------------------|----------------------------------------------------------------|---------|---------
@@ -53,15 +47,15 @@ Name             | Type             | Description
 
 ## Blocks
 
-The following blocks are supported inside the definition of `loki.relabel`:
+You can use the following blocks with `loki.relabel`:
 
-Hierarchy | Name     | Description                                        | Required
-----------|----------|----------------------------------------------------|---------
-rule      | [rule][] | Relabeling rules to apply to received log entries. | no
+Name           | Description                                        | Required
+---------------|----------------------------------------------------|---------
+[`rule`][rule] | Relabeling rules to apply to received log entries. | no
 
-[rule]: #rule-block
+[rule]: #rule
 
-### rule block
+### `rule`
 
 {{< docs/shared lookup="reference/components/rule-block-logs.md" source="alloy" version="<ALLOY_VERSION>" >}}
 
@@ -81,7 +75,7 @@ In those cases, exported fields are kept at their last healthy values.
 
 ## Debug information
 
-`loki.relabel` does not expose any component-specific debug information.
+`loki.relabel` doesn't expose any component-specific debug information.
 
 ## Debug metrics
 
diff --git a/docs/sources/reference/components/loki/loki.rules.kubernetes.md b/docs/sources/reference/components/loki/loki.rules.kubernetes.md
index 0eabf5b2df..a7d77b9e3e 100644
--- a/docs/sources/reference/components/loki/loki.rules.kubernetes.md
+++ b/docs/sources/reference/components/loki/loki.rules.kubernetes.md
@@ -5,21 +5,18 @@ aliases:
 title: loki.rules.kubernetes
 ---
 
-# loki.rules.kubernetes
+# `loki.rules.kubernetes`
 
-`loki.rules.kubernetes` discovers `PrometheusRule` Kubernetes resources and
-loads them into a Loki instance.
+`loki.rules.kubernetes` discovers `PrometheusRule` Kubernetes resources and loads them into a Loki instance.
 
 * You can specify multiple `loki.rules.kubernetes` components by giving them different labels.
-* [Kubernetes label selectors][] can be used to limit the `Namespace` and
-  `PrometheusRule` resources considered during reconciliation.
+* [Kubernetes label selectors][] can be used to limit the `Namespace` and `PrometheusRule` resources considered during reconciliation.
 * Compatible with the Ruler APIs of Grafana Loki, Grafana Cloud, and Grafana Enterprise Metrics.
 * Compatible with the `PrometheusRule` CRD from the [prometheus-operator][].
 * This component accesses the Kubernetes REST API from [within a Pod][].
 
 {{< admonition type="note" >}}
-This component requires [Role-based access control (RBAC)][] to be set up
-in Kubernetes for {{< param "PRODUCT_NAME" >}} to access it via the Kubernetes REST API.
+This component requires [Role-based access control (RBAC)][] to be set up in Kubernetes for {{< param "PRODUCT_NAME" >}} to access it via the Kubernetes REST API.
 
 [Role-based access control (RBAC)]: https://kubernetes.io/docs/reference/access-authn-authz/rbac/
 {{< /admonition >}}
@@ -31,65 +28,62 @@ in Kubernetes for {{< param "PRODUCT_NAME" >}} to access it via the Kubernetes R
 ## Usage
 
 ```alloy
-loki.rules.kubernetes "LABEL" {
-  address = LOKI_RULER_URL
+loki.rules.kubernetes "<LABEL>" {
+  address = "<LOKI_RULER_URL>"
 }
 ```
 
 ## Arguments
 
-`loki.rules.kubernetes` supports the following arguments:
+You can use the following arguments with `loki.rules.kubernetes`:
 
-Name                    | Type       | Description                                                                          | Default | Required
-------------------------|------------|--------------------------------------------------------------------------------------|---------|---------
-`address`               | `string`   | URL of the Loki ruler.                                                               |         | yes
-`tenant_id`             | `string`   | Loki tenant ID.                                                                      |         | no
-`use_legacy_routes`     | `bool`     | Whether to use deprecated ruler API endpoints.                                       | false   | no
-`sync_interval`         | `duration` | Amount of time between reconciliations with Loki.                                    | "30s"   | no
+Name                    | Type       | Description                                                                     | Default | Required
+------------------------|------------|---------------------------------------------------------------------------------|---------|---------
+`address`               | `string`   | URL of the Loki ruler.                                                          |         | yes
+`bearer_token_file`     | `string`   | File containing a bearer token to authenticate with.                            |         | no
+`bearer_token`          | `secret`   | Bearer token to authenticate with.                                              |         | no
+`enable_http2`          | `bool`     | Whether HTTP2 is supported for requests.                                        | `true`  | no
+`follow_redirects`      | `bool`     | Whether redirects returned by the server should be followed.                    | `true`  | no
 `loki_namespace_prefix` | `string`   | Prefix used to differentiate multiple {{< param "PRODUCT_NAME" >}} deployments. | "alloy" | no
-`bearer_token`          | `secret`   | Bearer token to authenticate with.                                                   |         | no
-`bearer_token_file`     | `string`   | File containing a bearer token to authenticate with.                                 |         | no
-`proxy_url`             | `string`   | HTTP proxy to proxy requests through.                                                |         | no
-`follow_redirects`      | `bool`     | Whether redirects returned by the server should be followed.                         | `true`  | no
-`enable_http2`          | `bool`     | Whether HTTP2 is supported for requests.                                             | `true`  | no
+`proxy_url`             | `string`   | HTTP proxy to proxy requests through.                                           |         | no
+`sync_interval`         | `duration` | Amount of time between reconciliations with Loki.                               | "30s"   | no
+`tenant_id`             | `string`   | Loki tenant ID.                                                                 |         | no
+`use_legacy_routes`     | `bool`     | Whether to use deprecated ruler API endpoints.                                  | false   | no
 
  At most, one of the following can be provided:
- - [`bearer_token` argument](#arguments).
- - [`bearer_token_file` argument](#arguments).
- - [`basic_auth` block][basic_auth].
- - [`authorization` block][authorization].
- - [`oauth2` block][oauth2].
+
+* [`authorization`][authorization] block
+* [`basic_auth`][basic_auth] block
+* [`bearer_token_file`][arguments] argument
+* [`bearer_token` ][arguments] argument
+* [`oauth2`][oauth2] block
 
  [arguments]: #arguments
 
-If no `tenant_id` is provided, the component assumes that the Loki instance at
-`address` is running in single-tenant mode and no `X-Scope-OrgID` header is sent.
+If no `tenant_id` is provided, the component assumes that the Loki instance at `address` is running in single-tenant mode and no `X-Scope-OrgID` header is sent.
 
-The `sync_interval` argument determines how often Loki's ruler API is accessed
-to reload the current state. Interaction with the Kubernetes API works
-differently. Updates are processed as events from the Kubernetes API server
-according to the informer pattern.
+The `sync_interval` argument determines how often the Loki ruler API is accessed to reload the current state.
+Interaction with the Kubernetes API works differently.
+Updates are processed as events from the Kubernetes API server according to the informer pattern.
 
-You can use the `loki_namespace_prefix` argument to separate the rules managed
-by multiple {{< param "PRODUCT_NAME" >}} deployments across your infrastructure. You should set the prefix to a
-unique value for each deployment.
+You can use the `loki_namespace_prefix` argument to separate the rules managed by multiple {{< param "PRODUCT_NAME" >}} deployments across your infrastructure.
+You should set the prefix to a unique value for each deployment.
 
 ## Blocks
 
-The following blocks are supported inside the definition of
-`loki.rules.kubernetes`:
-
-Hierarchy                                  | Block                  | Description                                              | Required
--------------------------------------------|------------------------|----------------------------------------------------------|---------
-rule_namespace_selector                    | [label_selector][]     | Label selector for `Namespace` resources.                | no
-rule_namespace_selector > match_expression | [match_expression][]   | Label match expression for `Namespace` resources.        | no
-rule_selector                              | [label_selector][]     | Label selector for `PrometheusRule` resources.           | no
-rule_selector > match_expression           | [match_expression][]   | Label match expression for `PrometheusRule` resources.   | no
-basic_auth                                 | [basic_auth][]         | Configure basic_auth for authenticating to the endpoint. | no
-authorization                              | [authorization][]      | Configure generic authorization to the endpoint.         | no
-oauth2                                     | [oauth2][]             | Configure OAuth2 for authenticating to the endpoint.     | no
-oauth2 > tls_config                        | [tls_config][]         | Configure TLS settings for connecting to the endpoint.   | no
-tls_config                                 | [tls_config][]         | Configure TLS settings for connecting to the endpoint.   | no
+You can use the following blocks with `loki.rules.kubernetes`:
+
+Hierarchy                                  | Block                                          | Description                                              | Required
+-------------------------------------------|------------------------------------------------|----------------------------------------------------------|---------
+rule_namespace_selector                    | [label_selector][]                             | Label selector for `Namespace` resources.                | no
+rule_namespace_selector > match_expression | rule_namespace_selector > [match_expression][] | Label match expression for `Namespace` resources.        | no
+rule_selector                              | [label_selector][]                             | Label selector for `PrometheusRule` resources.           | no
+rule_selector > match_expression           | rule_selector > [match_expression][]           | Label match expression for `PrometheusRule` resources.   | no
+ [basic_auth][basic_auth]                                 | Configure `basic_auth` for authenticating to the endpoint. | no
+ [authorization][authorization]                              | Configure generic authorization to the endpoint.         | no
+ [`oauth2`][oauth2]                                     | Configure OAuth 2.0 for authenticating to the endpoint.     | no
+ `oauth2` > [`tls_config`][tls_config]                        | Configure TLS settings for connecting to the endpoint.   | no
+ [`tls_config`][tls_config]                                 | Configure TLS settings for connecting to the endpoint.   | no
 
 The `>` symbol indicates deeper levels of nesting. For example,
 `oauth2 > tls_config` refers to a `tls_config` block defined inside
@@ -150,7 +144,7 @@ The `operator` argument should be one of the following strings:
 
 ## Exported fields
 
-`loki.rules.kubernetes` does not export any fields.
+`loki.rules.kubernetes` doesn't export any fields.
 
 ## Component health
 
@@ -161,17 +155,18 @@ The `operator` argument should be one of the following strings:
 `loki.rules.kubernetes` exposes resource-level debug information.
 
 The following are exposed per discovered `PrometheusRule` resource:
+
 * The Kubernetes namespace.
 * The resource name.
-* The resource uid.
+* The resource UID.
 * The number of rule groups.
 
 The following are exposed per discovered Loki rule namespace resource:
+
 * The namespace name.
 * The number of rule groups.
 
-Only resources managed by the component are exposed - regardless of how many
-actually exist.
+Only resources managed by the component are exposed - regardless of how many actually exist.
 
 ## Debug metrics