Edit cycle on Alloy docs to catch typos and rework some text (#109)

* Fix typo in heading * Updates from review * Fix command description * Style updates for some reference topics * Modify and rework tutorials and add prereqs
grafana · Apr 3, 2024 · 90253d3 · 90253d3
1 parent ac72ca8
commit 90253d3
Show file tree

Hide file tree

Showing 12 changed files with 197 additions and 159 deletions.
diff --git a/docs/sources/concepts/configuration-syntax/components.md b/docs/sources/concepts/configuration-syntax/components.md
@@ -1,11 +1,11 @@
 ---
 canonical: https://grafana.com/docs/alloy/latest/concepts/configuration-syntax/components/
 description: Learn about the components configuration language
-title: Components configuration language
+title: Components configuration
 weight: 300
 ---
 
-# Components configuration language
+# Components configuration
 
 Components are the defining feature of {{< param "PRODUCT_NAME" >}}.
 Components are small, reusable pieces of business logic that perform a single task like retrieving secrets or collecting Prometheus metrics, and you can wire them together to form programmable pipelines of telemetry data.

diff --git a/docs/sources/introduction/_index.md b/docs/sources/introduction/_index.md
@@ -75,9 +75,9 @@ binaries and images with BoringCrypto enabled. Builds and Docker images for Linu
 
 * [Install][] {{< param "PRODUCT_NAME" >}}.
 * Learn about the core [Concepts][] of {{< param "PRODUCT_NAME" >}}.
-* Follow the [Tutorials][] for hands-on learning of {{< param "PRODUCT_NAME" >}}.
+* Follow the [Tutorials][] for hands-on learning about {{< param "PRODUCT_NAME" >}}.
 * Consult the [Tasks][] instructions to accomplish common objectives with {{< param "PRODUCT_NAME" >}}.
-* Check out the [Reference][] documentation to find specific information you might be looking for.
+* Check out the [Reference][] documentation to find information about the Alloy components, configuration blocks, and command line tools.
 
 [OpenTelemetry]: https://opentelemetry.io/ecosystem/distributions/
 [Install]: ../get-started/install/

diff --git a/docs/sources/reference/components/discovery.azure.md b/docs/sources/reference/components/discovery.azure.md
@@ -13,7 +13,7 @@ title: discovery.azure
 ## Usage
 
 ```alloy
-discovery.azure "LABEL" {
+discovery.azure "<LABEL>" {
 }
 ```
 
@@ -64,9 +64,9 @@ Name            | Type     | Description          | Default | Required
 ### managed_identity block
 The `managed_identity` block configures Managed Identity authentication for the Azure API.
 
-Name | Type | Description | Default | Required
----- | ---- | ----------- | ------- | --------
-`client_id` | `string` | Managed Identity client ID. | | yes
+Name        | Type     | Description                 | Default | Required
+------------|----------|-----------------------------|---------|---------
+`client_id` | `string` | Managed Identity client ID. |         | yes
 
 ### tls_config block
 
@@ -77,7 +77,7 @@ Name | Type | Description | Default | Required
 The following fields are exported and can be referenced by other components:
 
 Name      | Type                | Description
---------- | ------------------- | -----------
+----------|---------------------|--------------------------------------------------
 `targets` | `list(map(string))` | The set of targets discovered from the Azure API.
 
 Each target includes the following labels:
@@ -100,28 +100,27 @@ Each discovered VM maps to a single target. The `__address__` label is set to th
 
 ## Component health
 
-`discovery.azure` is only reported as unhealthy when given an invalid
-configuration. In those cases, exported fields retain their last healthy
-values.
+`discovery.azure` is only reported as unhealthy when given an invalid configuration.
+In those cases, exported fields retain their last healthy values.
 
 ## Debug information
 
-`discovery.azure` does not expose any component-specific debug information.
+`discovery.azure` doesn't expose any component-specific debug information.
 
 ## Debug metrics
 
-`discovery.azure` does not expose any component-specific debug metrics.
+`discovery.azure` doesn't expose any component-specific debug metrics.
 
 ## Example
 
 ```alloy
 discovery.azure "example" {
   port = 80
-  subscription_id = AZURE_SUBSCRIPTION_ID
+  subscription_id = <AZURE_SUBSCRIPTION_ID>
   oauth {
-      client_id = AZURE_CLIENT_ID
-      client_secret = AZURE_CLIENT_SECRET
-      tenant_id = AZURE_TENANT_ID
+      client_id = <AZURE_CLIENT_ID>
+      client_secret = <AZURE_CLIENT_SECRET>
+      tenant_id = <AZURE_TENANT_ID>
   }
 }
 
@@ -132,23 +131,24 @@ prometheus.scrape "demo" {
 
 prometheus.remote_write "demo" {
   endpoint {
-    url = PROMETHEUS_REMOTE_WRITE_URL
+    url = <PROMETHEUS_REMOTE_WRITE_URL>
 
     basic_auth {
-      username = USERNAME
-      password = PASSWORD
+      username = <USERNAME>
+      password = <PASSWORD>
     }
   }
 }
 ```
+
 Replace the following:
-  - `AZURE_SUBSCRIPTION_ID`: Your Azure subscription ID.
-  - `AZURE_CLIENT_ID`: Your Azure client ID.
-  - `AZURE_CLIENT_SECRET`: Your Azure client secret.
-  - `AZURE_TENANT_ID`: Your Azure tenant ID.
-  - `PROMETHEUS_REMOTE_WRITE_URL`: The URL of the Prometheus remote_write-compatible server to send metrics to.
-  - `USERNAME`: The username to use for authentication to the remote_write API.
-  - `PASSWORD`: The password to use for authentication to the remote_write API.
+  - _`<AZURE_SUBSCRIPTION_ID>`_: Your Azure subscription ID.
+  - _`<AZURE_CLIENT_ID>`_: Your Azure client ID.
+  - _`<AZURE_CLIENT_SECRET>`_: Your Azure client secret.
+  - _`<AZURE_TENANT_ID>`_: Your Azure tenant ID.
+  - _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus remote_write-compatible server to send metrics to.
+  - _`<USERNAME>`_: The username to use for authentication to the remote_write API.
+  - _`<PASSWORD>`_: The password to use for authentication to the remote_write API.
 
 <!-- START GENERATED COMPATIBLE COMPONENTS -->
 

diff --git a/docs/sources/reference/components/discovery.consul.md b/docs/sources/reference/components/discovery.consul.md
@@ -153,19 +153,19 @@ prometheus.scrape "demo" {
 
 prometheus.remote_write "demo" {
   endpoint {
-    url = PROMETHEUS_REMOTE_WRITE_URL
+    url = <PROMETHEUS_REMOTE_WRITE_URL>
 
     basic_auth {
-      username = USERNAME
-      password = PASSWORD
+      username = <USERNAME>
+      password = <PASSWORD>
     }
   }
 }
 ```
 Replace the following:
-  - `PROMETHEUS_REMOTE_WRITE_URL`: The URL of the Prometheus remote_write-compatible server to send metrics to.
-  - `USERNAME`: The username to use for authentication to the remote_write API.
-  - `PASSWORD`: The password to use for authentication to the remote_write API.
+  - _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus remote_write-compatible server to send metrics to.
+  - _`<USERNAME>`_: The username to use for authentication to the remote_write API.
+  - _`<PASSWORD>`_: The password to use for authentication to the remote_write API.
 
 <!-- START GENERATED COMPATIBLE COMPONENTS -->
 

diff --git a/docs/sources/reference/components/discovery.consulagent.md b/docs/sources/reference/components/discovery.consulagent.md
@@ -24,18 +24,18 @@ discovery.consulagent "LABEL" {
 
 The following arguments are supported:
 
-| Name               | Type           | Description                                                                                                                               | Default          | Required |
-| ------------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | -------- |
-| `server`           | `string`       | Host and port of the Consul Agent API.                                                                                                    | `localhost:8500` | no       |
-| `token`            | `secret`       | Secret token used to access the Consul Agent API.                                                                                         |                  | no       |
-| `datacenter`       | `string`       | Datacenter in which the Consul Agent is configured to run. If not provided, the datacenter will be retrieved from the local Consul Agent. |                  | no       |
-| `tag_separator`    | `string`       | The string by which Consul tags are joined into the tag label.                                                                            | `,`              | no       |
-| `scheme`           | `string`       | The scheme to use when talking to the Consul Agent.                                                                                       | `http`           | no       |
-| `username`         | `string`       | The username to use.                                                                                                                      |                  | no       |
-| `password`         | `secret`       | The password to use.                                                                                                                      |                  | no       |
-| `services`         | `list(string)` | A list of services for which targets are retrieved. If omitted, all services are scraped.                                                 |                  | no       |
-| `tags`             | `list(string)` | An optional list of tags used to filter nodes for a given service. Services must contain all tags in the list.                            |                  | no       |
-| `refresh_interval` | `duration`     | Frequency to refresh list of containers.                                                                                                  | `"30s"`          | no       |
+| Name               | Type           | Description                                                                                                                          | Default          | Required |
+|--------------------|----------------|--------------------------------------------------------------------------------------------------------------------------------------|------------------|----------|
+| `server`           | `string`       | Host and port of the Consul Agent API.                                                                                               | `localhost:8500` | no       |
+| `token`            | `secret`       | Secret token used to access the Consul Agent API.                                                                                    |                  | no       |
+| `datacenter`       | `string`       | Datacenter in which the Consul Agent is configured to run. If not provided, the datacenter is retrieved from the local Consul Agent. |                  | no       |
+| `tag_separator`    | `string`       | The string by which Consul tags are joined into the tag label.                                                                       | `,`              | no       |
+| `scheme`           | `string`       | The scheme to use when talking to the Consul Agent.                                                                                  | `http`           | no       |
+| `username`         | `string`       | The username to use.                                                                                                                 |                  | no       |
+| `password`         | `secret`       | The password to use.                                                                                                                 |                  | no       |
+| `services`         | `list(string)` | A list of services for which targets are retrieved. If omitted, all services are scraped.                                            |                  | no       |
+| `tags`             | `list(string)` | An optional list of tags used to filter nodes for a given service. Services must contain all tags in the list.                       |                  | no       |
+| `refresh_interval` | `duration`     | Frequency to refresh list of containers.                                                                                             | `"30s"`          | no       |
 
 ## Blocks
 
@@ -62,28 +62,27 @@ The following fields are exported and can be referenced by other components:
 
 Each target includes the following labels:
 
-- `__meta_consulagent_address`: the address of the target.
-- `__meta_consulagent_dc`: the datacenter name for the target.
-- `__meta_consulagent_health`: the health status of the service.
-- `__meta_consulagent_metadata_<key>`: each node metadata key value of the target.
-- `__meta_consulagent_node`: the node name defined for the target.
-- `__meta_consulagent_service`: the name of the service the target belongs to.
-- `__meta_consulagent_service_address`: the service address of the target.
-- `__meta_consulagent_service_id`: the service ID of the target.
-- `__meta_consulagent_service_metadata_<key>`: each service metadata key value of the target.
-- `__meta_consulagent_service_port`: the service port of the target.
-- `__meta_consulagent_tagged_address_<key>`: each node tagged address key value of the target.
-- `__meta_consulagent_tags`: the list of tags of the target joined by the tag separator.
+- `__meta_consulagent_address`: The address of the target.
+- `__meta_consulagent_dc`: The datacenter name for the target.
+- `__meta_consulagent_health`: The health status of the service.
+- `__meta_consulagent_metadata_<key>`: Each node metadata key value of the target.
+- `__meta_consulagent_node`: The node name defined for the target.
+- `__meta_consulagent_service`: The name of the service the target belongs to.
+- `__meta_consulagent_service_address`: The service address of the target.
+- `__meta_consulagent_service_id`: The service ID of the target.
+- `__meta_consulagent_service_metadata_<key>`: Each service metadata key value of the target.
+- `__meta_consulagent_service_port`: The service port of the target.
+- `__meta_consulagent_tagged_address_<key>`: Each node tagged address key value of the target.
+- `__meta_consulagent_tags`: The list of tags of the target joined by the tag separator.
 
 ## Component health
 
-`discovery.consulagent` is only reported as unhealthy when given an invalid
-configuration. In those cases, exported fields retain their last healthy
-values.
+`discovery.consulagent` is only reported as unhealthy when given an invalid configuration.
+In those cases, exported fields retain their last healthy values.
 
 ## Debug information
 
-`discovery.consulagent` does not expose any component-specific debug information.
+`discovery.consulagent` doesn't expose any component-specific debug information.
 
 ## Debug metrics
 
@@ -111,21 +110,21 @@ prometheus.scrape "demo" {
 
 prometheus.remote_write "demo" {
   endpoint {
-    url = PROMETHEUS_REMOTE_WRITE_URL
+    url = <PROMETHEUS_REMOTE_WRITE_URL>
 
     basic_auth {
-      username = USERNAME
-      password = PASSWORD
+      username = <USERNAME>
+      password = <PASSWORD>
     }
   }
 }
 ```
 
 Replace the following:
 
-- `PROMETHEUS_REMOTE_WRITE_URL`: The URL of the Prometheus remote_write-compatible server to send metrics to.
-- `USERNAME`: The username to use for authentication to the remote_write API.
-- `PASSWORD`: The password to use for authentication to the remote_write API.
+- _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus remote_write-compatible server to send metrics to.
+- _`<USERNAME>`_: The username to use for authentication to the remote_write API.
+- _`<PASSWORD>`_: The password to use for authentication to the remote_write API.
 
 <!-- START GENERATED COMPATIBLE COMPONENTS -->
 

diff --git a/docs/sources/reference/components/discovery.digitalocean.md b/docs/sources/reference/components/discovery.digitalocean.md
@@ -46,7 +46,7 @@ Exactly one of the [`bearer_token`](#arguments) and [`bearer_token_file`](#argum
 {{< docs/shared lookup="reference/components/http-client-proxy-config-description.md" source="alloy" version="<ALLOY_VERSION>" >}}
 
 ## Blocks
-The `discovery.digitalocean` component does not support any blocks, and is configured fully through arguments.
+The `discovery.digitalocean` component doesn't support any blocks, and is configured fully through arguments.
 
 
 ## Exported fields
@@ -83,11 +83,11 @@ values.
 
 ## Debug information
 
-`discovery.digitalocean` does not expose any component-specific debug information.
+`discovery.digitalocean` doesn't expose any component-specific debug information.
 
 ## Debug metrics
 
-`discovery.digitalocean` does not expose any component-specific debug metrics.
+`discovery.digitalocean` doesn't expose any component-specific debug metrics.
 
 ## Example
 
@@ -106,19 +106,19 @@ prometheus.scrape "demo" {
 
 prometheus.remote_write "demo" {
   endpoint {
-    url = PROMETHEUS_REMOTE_WRITE_URL
+    url = <PROMETHEUS_REMOTE_WRITE_URL>
 
     basic_auth {
-      username = USERNAME
-      password = PASSWORD
+      username = <USERNAME>
+      password = <PASSWORD>
     }
   }
 }
 ```
 Replace the following:
-  - `PROMETHEUS_REMOTE_WRITE_URL`: The URL of the Prometheus remote_write-compatible server to send metrics to.
-  - `USERNAME`: The username to use for authentication to the remote_write API.
-  - `PASSWORD`: The password to use for authentication to the remote_write API.
+  - _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus remote_write-compatible server to send metrics to.
+  - _`<USERNAME>`_: The username to use for authentication to the remote_write API.
+  - _`<PASSWORD>`_: The password to use for authentication to the remote_write API.
 
 <!-- START GENERATED COMPATIBLE COMPONENTS -->
 

diff --git a/docs/sources/tasks/migrate/_index.md b/docs/sources/tasks/migrate/_index.md
@@ -6,7 +6,7 @@ title: Migrate to Grafana Alloy
 weight: 100
 ---
 
-# HMigrate to {{% param "FULL_PRODUCT_NAME" %}}
+# Migrate to {{% param "FULL_PRODUCT_NAME" %}}
 
 This section details how to migrate to {{< param "PRODUCT_NAME" >}} from other common solutions.
 

diff --git a/docs/sources/tasks/migrate/from-operator.md b/docs/sources/tasks/migrate/from-operator.md
@@ -31,7 +31,7 @@ You can migrate from Grafana Agent Operator to {{< param "PRODUCT_NAME" >}}.
       create: false
     ```
 
-    This configuration deploys {{< param "PRODUCT_NAME" >}} as a `StatefulSet` using the built-in [clustering][] functionality to allow distributing scrapes across all {{< param "PRODUCT_NAME" >}} Pods.
+    This configuration deploys {{< param "PRODUCT_NAME" >}} as a `StatefulSet` using the built-in [clustering][] functionality to allow distributing scrapes across all {{< param "PRODUCT_NAME" >}} pods.
 
     This is one of many deployment possible modes. For example, you may want to use a `DaemonSet` to collect host-level logs or metrics.
     See the {{< param "PRODUCT_NAME" >}} [deployment guide][] for more details about different topologies.
@@ -142,10 +142,10 @@ alloy:
     varlog: true
 ```
 
-This command installs a release named `grafana-agent-logs` in the `monitoring` namespace:
+This command installs a release named `alloy-logs` in the `monitoring` namespace:
 
 ```
-helm upgrade grafana-agent-logs grafana/grafana-agent -i -n monitoring -f values-logs.yaml --set-file agent.configMap.content=agent-logs.alloy
+helm upgrade alloy-logs grafana/alloy -i -n monitoring -f values-logs.yaml --set-file alloy.configMap.content=config-logs.alloy
 ```
 
 This simple configuration scrapes logs for every Pod on each node:
@@ -268,7 +268,7 @@ The logging subsystem is very powerful and has many options for processing logs.
 ## Integrations
 
 The `Integration` CRD isn't supported with {{< param "PRODUCT_NAME" >}}.
-However, all Grafana Agent Static integrations have an equivalent component in the [`prometheus.exporter`][prometheus.exporter] namespace.
+However, all Grafana Agent Static mode integrations have an equivalent component in the [`prometheus.exporter`][prometheus.exporter] namespace.
 The [reference documentation][component documentation] should help convert those integrations to their {{< param "PRODUCT_NAME" >}} equivalent.
 
 <!-- ToDo: Validate path -->