From e56219cbb365ded010b8df1469ceff6253ca4006 Mon Sep 17 00:00:00 2001 From: Clayton Cornell Date: Fri, 17 Nov 2023 12:48:29 -0800 Subject: [PATCH 1/9] First pass at aligning style --- .../reference/components/discovery.azure.md | 97 ++++++----- .../reference/components/discovery.consul.md | 102 ++++++------ .../components/discovery.consulagent.md | 52 +++--- .../components/discovery.digitalocean.md | 41 +++-- .../reference/components/discovery.dns.md | 41 +++-- .../reference/components/discovery.docker.md | 150 ++++++++---------- .../components/authorization-block.md | 13 +- .../reference/components/azuread-block.md | 4 +- .../reference/components/basic-auth-block.md | 13 +- .../components/exporter-component-exports.md | 9 +- .../components/extract-field-block.md | 27 ++-- .../components/field-filter-block.md | 10 +- .../components/http-client-config-block.md | 18 +-- .../components/local-file-arguments-text.md | 25 ++- .../reference/components/loki-server-grpc.md | 25 ++- .../reference/components/loki-server-http.md | 19 ++- .../components/managed_identity-block.md | 8 +- .../components/match-properties-block.md | 18 +-- .../flow/reference/components/oauth2-block.md | 21 ++- .../components/otelcol-compression-field.md | 7 +- .../components/otelcol-debug-metrics-block.md | 12 +- .../otelcol-filter-attribute-block.md | 12 +- .../otelcol-filter-library-block.md | 12 +- .../otelcol-filter-log-severity-block.md | 13 +- .../components/otelcol-filter-regexp-block.md | 8 +- .../otelcol-filter-resource-block.md | 10 +- .../components/otelcol-grpc-authority.md | 7 +- .../components/otelcol-grpc-balancer-name.md | 8 +- .../components/otelcol-queue-block.md | 27 ++-- .../components/otelcol-retry-block.md | 34 ++-- .../components/otelcol-tls-config-block.md | 38 +++-- .../reference/components/output-block-logs.md | 15 +- .../components/output-block-metrics.md | 12 +- .../components/output-block-traces.md | 15 +- .../flow/reference/components/output-block.md | 19 ++- .../components/prom-operator-scrape.md | 8 +- .../reference/components/rule-block-logs.md | 44 ++--- .../flow/reference/components/rule-block.md | 42 ++--- .../flow/reference/components/sigv4-block.md | 14 +- .../reference/components/tls-config-block.md | 25 ++- 40 files changed, 507 insertions(+), 568 deletions(-) diff --git a/docs/sources/flow/reference/components/discovery.azure.md b/docs/sources/flow/reference/components/discovery.azure.md index 5192299a1eeb..85ae5d9f5ab8 100644 --- a/docs/sources/flow/reference/components/discovery.azure.md +++ b/docs/sources/flow/reference/components/discovery.azure.md @@ -26,25 +26,24 @@ discovery.azure "LABEL" { The following arguments are supported: -Name | Type | Description | Default | Required -------------------- | ---------- | ---------------------------------------------------------------------- | -------------------- | -------- -`environment` | `string` | Azure environment. | `"AzurePublicCloud"` | no -`port` | `number` | Port to be appended to the `__address__` label for each target. | `80` | no -`subscription_id` | `string` | Azure subscription ID. | | no -`refresh_interval` | `duration` | Interval at which to refresh the list of targets. | `5m` | 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 +Name | Type | Description | Default | Required +-------------------|------------|-----------------------------------------------------------------|----------------------|--------- +`enable_http2` | `bool` | Whether HTTP2 is supported for requests. | `true` | no +`environment` | `string` | Azure environment. | `"AzurePublicCloud"` | no +`follow_redirects` | `bool` | Whether redirects returned by the server should be followed. | `true` | no +`port` | `number` | Port to be appended to the `__address__` label for each target. | `80` | no +`proxy_url` | `string` | HTTP proxy to proxy requests through. | | no +`refresh_interval` | `duration` | Interval at which to refresh the list of targets. | `5m` | no +`subscription_id` | `string` | Azure subscription ID. | | no ## Blocks -The following blocks are supported inside the definition of -`discovery.azure`: +The following blocks are supported inside the definition of `discovery.azure`: -Hierarchy | Block | Description | Required ---------- | ----- | ----------- | -------- -oauth | [oauth][] | OAuth configuration for Azure API. | no -managed_identity | [managed_identity][] | Managed Identity configuration for Azure API. | no -tls_config | [tls_config][] | TLS configuration for requests to the Azure API. | no +Hierarchy | Block | Description | Required +-----------------|----------------------|--------------------------------------------------|--------- +managed_identity | [managed_identity][] | Managed Identity configuration for Azure API. | no +oauth | [oauth][] | OAuth configuration for Azure API. | no +tls_config | [tls_config][] | TLS configuration for requests to the Azure API. | no Exactly one of the `oauth` or `managed_identity` blocks must be specified. @@ -52,32 +51,32 @@ Exactly one of the `oauth` or `managed_identity` blocks must be specified. [managed_identity]: #managed_identity-block [tls_config]: #tls_config-block -### oauth block -The `oauth` block configures OAuth authentication for the Azure API. +### managed_identity +The `managed_identity` block configures Managed Identity authentication for the Azure API. -Name | Type | Description | Default | Required ----- | ---- | ----------- | ------- | -------- -`client_id` | `string` | OAuth client ID. | | yes -`client_secret` | `string` | OAuth client secret. | | yes -`tenant_id` | `string` | OAuth tenant ID. | | yes +Name | Type | Description | Default | Required +------------|----------|-----------------------------|---------|--------- +`client_id` | `string` | Managed Identity client ID. | | yes -### managed_identity block -The `managed_identity` block configures Managed Identity authentication for the Azure API. +### oauth +The `oauth` block configures OAuth 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` | OAuth client ID. | | yes +`client_secret` | `string` | OAuth client secret. | | yes +`tenant_id` | `string` | OAuth tenant ID. | | yes -### tls_config block +### tls_config -{{< docs/shared lookup="flow/reference/components/tls-config-block.md" source="agent" version="" >}} +{{< docs/shared lookup="flow/reference/components/tls-config-block.md" source="agent" version="" >}} ## Exported fields 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: @@ -88,11 +87,11 @@ Each target includes the following labels: * `__meta_azure_machine_resource_group`: The name of the resource group the VM is in. * `__meta_azure_machine_name`: The name of the VM. * `__meta_azure_machine_computer_name`: The host OS name of the VM. -* `__meta_azure_machine_os_type`: The OS the VM is running (either `Linux` or `Windows`). +* `__meta_azure_machine_os_type`: The OS the VM is running, either `Linux` or `Windows`. * `__meta_azure_machine_location`: The region the VM is in. * `__meta_azure_machine_private_ip`: The private IP address of the VM. * `__meta_azure_machine_public_ip`: The public IP address of the VM. -* `__meta_azure_machine_tag_*`: A tag on the VM. There will be one label per tag. +* `__meta_azure_machine_tag_*`: A tag on the VM. There is one label per tag. * `__meta_azure_machine_scale_set`: The name of the scale set the VM is in. * `__meta_azure_machine_size`: The size of the VM. @@ -106,22 +105,22 @@ 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 ```river discovery.azure "example" { port = 80 - subscription_id = AZURE_SUBSCRIPTION_ID + subscription_id = oauth { - client_id = AZURE_CLIENT_ID - client_secret = AZURE_CLIENT_SECRET - tenant_id = AZURE_TENANT_ID + client_id = + client_secret = + tenant_id = } } @@ -132,20 +131,20 @@ prometheus.scrape "demo" { prometheus.remote_write "demo" { endpoint { - url = PROMETHEUS_REMOTE_WRITE_URL + url = basic_auth { - username = USERNAME - password = PASSWORD + username = + 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. + - ``: Your Azure subscription ID. + - ``: Your Azure client ID. + - ``: Your Azure client secret. + - ``: Your Azure tenant ID. + - ``: The URL of the Prometheus remote_write-compatible server to send metrics to. + - ``: The username to use for authentication to the remote_write API. + - ``: The password to use for authentication to the remote_write API. diff --git a/docs/sources/flow/reference/components/discovery.consul.md b/docs/sources/flow/reference/components/discovery.consul.md index 884fa1fe602f..28dbfccbf5b0 100644 --- a/docs/sources/flow/reference/components/discovery.consul.md +++ b/docs/sources/flow/reference/components/discovery.consul.md @@ -27,31 +27,31 @@ discovery.consul "LABEL" { The following arguments are supported: -Name | Type | Description | Default | Required ----- | ---- | ----------- | ------- | -------- -`server` | `string` | Host and port of the Consul API. | `localhost:8500` | no -`token` | `secret` | Secret token used to access the Consul API. | | no -`datacenter` | `string` | Datacenter to query. If not provided, the default is used. | | no -`namespace` | `string` | Namespace to use (only supported in Consul Enterprise). | | no -`partition` | `string` | Admin partition to use (only supported in Consul Enterprise). | | 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 Consul. | `http` | no -`username` | `string` | The username to use (deprecated in favor of the basic_auth configuration). | | no -`password` | `secret` | The password to use (deprecated in favor of the basic_auth configuration). | | no -`allow_stale` | `bool` | Allow stale Consul results (see [official documentation][consistency documentation]). Will reduce load on Consul. | `true` | 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 -`node_meta` | `map(string)` | Node metadata key/value pairs to filter nodes for a given service. | | no -`refresh_interval` | `duration` | Frequency to refresh list of containers. | `"30s"` | 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 +Name | Type | Description | Default | Required +--------------------|----------------|---------------------------------------------------------------------------------------------------------------------------|------------------|--------- +`allow_stale` | `bool` | Allow stale Consul results. Refer to the [official documentation][consistency documentation]. Will reduce load on Consul. | `true` | no +`bearer_token_file` | `string` | File containing a bearer token to authenticate with. | | no +`bearer_token` | `secret` | Bearer token to authenticate with. | | no +`datacenter` | `string` | Datacenter to query. If not provided, the default is used. | | 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 +`namespace` | `string` | Namespace to use. Only supported in Consul Enterprise. | | no +`node_meta` | `map(string)` | Node metadata key/value pairs to filter nodes for a given service. | | no +`partition` | `string` | Admin partition to use. Only supported in Consul Enterprise. | | no +`password` | `secret` | The password to use. Deprecated in favor of the basic_auth configuration. | | no +`proxy_url` | `string` | HTTP proxy to proxy requests through. | | no +`refresh_interval` | `duration` | Frequency to refresh list of containers. | `"30s"` | no +`scheme` | `string` | The scheme to use when talking to Consul. | `http` | no +`server` | `string` | Host and port of the Consul API. | `localhost:8500` | no +`services` | `list(string)` | A list of services for which targets are retrieved. If omitted, all services are scraped. | | no +`tag_separator` | `string` | The string by which Consul tags are joined into the tag label. | `,` | 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 +`token` | `secret` | Secret token used to access the Consul API. | | no +`username` | `string` | The username to use. Deprecated in favor of the basic_auth configuration. | | no At most one of the following can be provided: - [`bearer_token` argument](#arguments). - - [`bearer_token_file` argument](#arguments). + - [`bearer_token_file` argument](#arguments). - [`basic_auth` block][basic_auth]. - [`authorization` block][authorization]. - [`oauth2` block][oauth2]. @@ -64,44 +64,42 @@ Name | Type | Description | Default | Required The following blocks are supported inside the definition of `discovery.consul`: -Hierarchy | Block | Description | Required ---------- | ----- | ----------- | -------- -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 +Hierarchy | Block | Description | Required +--------------------|-------------------|----------------------------------------------------------|--------- +authorization | [authorization][] | Configure generic authorization to the endpoint. | no +basic_auth | [basic_auth][] | Configure basic_auth for authenticating 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 -The `>` symbol indicates deeper levels of nesting. For example, -`oauth2 > tls_config` refers to a `tls_config` block defined inside -an `oauth2` block. +The `>` symbol indicates deeper levels of nesting. For example, `oauth2 > tls_config` refers to a `tls_config` block defined inside an `oauth2` block. [basic_auth]: #basic_auth-block [authorization]: #authorization-block [oauth2]: #oauth2-block [tls_config]: #tls_config-block -### basic_auth block +### authorization -{{< docs/shared lookup="flow/reference/components/basic-auth-block.md" source="agent" version="" >}} +{{< docs/shared lookup="flow/reference/components/authorization-block.md" source="agent" version="" >}} -### authorization block +### basic_auth -{{< docs/shared lookup="flow/reference/components/authorization-block.md" source="agent" version="" >}} +{{< docs/shared lookup="flow/reference/components/basic-auth-block.md" source="agent" version="" >}} -### oauth2 block +### oauth2 -{{< docs/shared lookup="flow/reference/components/oauth2-block.md" source="agent" version="" >}} +{{< docs/shared lookup="flow/reference/components/oauth2-block.md" source="agent" version="" >}} -### tls_config block +### oauth2 > tls_config -{{< docs/shared lookup="flow/reference/components/tls-config-block.md" source="agent" version="" >}} +{{< docs/shared lookup="flow/reference/components/tls-config-block.md" source="agent" version="" >}} ## Exported fields The following fields are exported and can be referenced by other components: -Name | Type | Description ----- | ---- | ----------- +Name | Type | Description +----------|---------------------|----------------------------------------------------------- `targets` | `list(map(string))` | The set of targets discovered from the Consul catalog API. Each target includes the following labels: @@ -109,9 +107,9 @@ Each target includes the following labels: * `__meta_consul_address`: the address of the target. * `__meta_consul_dc`: the datacenter name for the target. * `__meta_consul_health`: the health status of the service. -* `__meta_consul_partition`: the admin partition name where the service is registered. * `__meta_consul_metadata_`: each node metadata key value of the target. * `__meta_consul_node`: the node name defined for the target. +* `__meta_consul_partition`: the admin partition name where the service is registered. * `__meta_consul_service_address`: the service address of the target. * `__meta_consul_service_id`: the service ID of the target. * `__meta_consul_service_metadata_`: each service metadata key value of the target. @@ -122,17 +120,15 @@ Each target includes the following labels: ## Component health -`discovery.consul` is only reported as unhealthy when given an invalid -configuration. In those cases, exported fields retain their last healthy -values. +`discovery.consul` is only reported as unhealthy when given an invalid configuration. In those cases, exported fields retain their last healthy values. ## Debug information -`discovery.consul` does not expose any component-specific debug information. +`discovery.consul` doesn't expose any component-specific debug information. ## Debug metrics -`discovery.consul` does not expose any component-specific debug metrics. +`discovery.consul` doesn't expose any component-specific debug metrics. ## Example @@ -154,16 +150,16 @@ prometheus.scrape "demo" { prometheus.remote_write "demo" { endpoint { - url = PROMETHEUS_REMOTE_WRITE_URL + url = basic_auth { - username = USERNAME - password = PASSWORD + username = + 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. + - ``: The URL of the Prometheus remote_write-compatible server to send metrics to. + - ``: The username to use for authentication to the remote_write API. + - ``: The password to use for authentication to the remote_write API. diff --git a/docs/sources/flow/reference/components/discovery.consulagent.md b/docs/sources/flow/reference/components/discovery.consulagent.md index 6ff793d1933e..67859e575dca 100644 --- a/docs/sources/flow/reference/components/discovery.consulagent.md +++ b/docs/sources/flow/reference/components/discovery.consulagent.md @@ -27,23 +27,22 @@ 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 | +|--------------------|----------------|----------------------------------------------------------------------------------------------------------------|------------------|----------| +| `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 | +| `password` | `secret` | The password to use. | | no | +| `refresh_interval` | `duration` | Frequency to refresh list of containers. | `"30s"` | no | +| `scheme` | `string` | The scheme to use when talking to the Consul Agent. | `http` | no | +| `server` | `string` | Host and port of the Consul Agent API. | `localhost:8500` | no | +| `services` | `list(string)` | A list of services for which targets are retrieved. If omitted, all services are scraped. | | no | +| `tag_separator` | `string` | The string by which Consul tags are joined into the tag label. | `,` | 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 | +| `token` | `secret` | Secret token used to access the Consul Agent API. | | no | +| `username` | `string` | The username to use. | | no | ## Blocks -The following blocks are supported inside the definition of -`discovery.consulagent`: +The following blocks are supported inside the definition of `discovery.consulagent`: | Hierarchy | Block | Description | Required | | ---------- | -------------- | ------------------------------------------------------ | -------- | @@ -51,9 +50,9 @@ The following blocks are supported inside the definition of [tls_config]: #tls_config-block -### tls_config block +### tls_config -{{< docs/shared lookup="flow/reference/components/tls-config-block.md" source="agent" version="" >}} +{{< docs/shared lookup="flow/reference/components/tls-config-block.md" source="agent" version="" >}} ## Exported fields @@ -70,23 +69,22 @@ Each target includes the following labels: - `__meta_consulagent_health`: the health status of the service. - `__meta_consulagent_metadata_`: 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_`: each service metadata key value of the target. - `__meta_consulagent_service_port`: the service port of the target. +- `__meta_consulagent_service`: the name of the service the target belongs to. - `__meta_consulagent_tagged_address_`: 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` doen't expose any component-specific debug information. ## Debug metrics @@ -114,11 +112,11 @@ prometheus.scrape "demo" { prometheus.remote_write "demo" { endpoint { - url = PROMETHEUS_REMOTE_WRITE_URL + url = basic_auth { - username = USERNAME - password = PASSWORD + username = + password = } } } @@ -126,6 +124,6 @@ prometheus.remote_write "demo" { 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. +- ``: The URL of the Prometheus remote_write-compatible server to send metrics to. +- ``: The username to use for authentication to the remote_write API. +- ``: The password to use for authentication to the remote_write API. diff --git a/docs/sources/flow/reference/components/discovery.digitalocean.md b/docs/sources/flow/reference/components/discovery.digitalocean.md index 18b42714b421..88ab1127e4c2 100644 --- a/docs/sources/flow/reference/components/discovery.digitalocean.md +++ b/docs/sources/flow/reference/components/discovery.digitalocean.md @@ -31,13 +31,13 @@ The following arguments are supported: Name | Type | Description | Default | Required ------------------- | ---------- | ---------------------------------------------------------------------- | ------- | -------- -`port` | `number` | Port to be appended to the `__address__` label for each Droplet. | `80` | no -`refresh_interval` | `duration` | Frequency to refresh list of Droplets. | `"1m"` | 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 +`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 +`port` | `number` | Port to be appended to the `__address__` label for each Droplet. | `80` | no +`proxy_url` | `string` | HTTP proxy to proxy requests through. | | no +`refresh_interval` | `duration` | Frequency to refresh list of Droplets. | `"1m"` | no The DigitalOcean API uses bearer tokens for authentication, see more about it in the [DigitalOcean API documentation](https://docs.digitalocean.com/reference/api/api-reference/#section/Authentication). @@ -46,31 +46,30 @@ Exactly one of the [`bearer_token`](#arguments) and [`bearer_token_file`](#argum [arguments]: #arguments ## 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 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 DigitalOcean API. Each target includes the following labels: * `__meta_digitalocean_droplet_id`: ID of the Droplet. * `__meta_digitalocean_droplet_name`: Name of the Droplet. -* `__meta_digitalocean_image`: The image slug (unique text identifier of the image) used to create the Droplet. +* `__meta_digitalocean_features`: Optional properties configured for the Droplet, such as IPV6 networking, private networking, or backups. * `__meta_digitalocean_image_name`: Name of the image used to create the Droplet. +* `__meta_digitalocean_image`: The image slug (unique text identifier of the image) used to create the Droplet. * `__meta_digitalocean_private_ipv4`: The private IPv4 address of the Droplet. * `__meta_digitalocean_public_ipv4`: The public IPv4 address of the Droplet. * `__meta_digitalocean_public_ipv6`: The public IPv6 address of the Droplet. * `__meta_digitalocean_region`: The region the Droplet is running in. * `__meta_digitalocean_size`: The size of the Droplet. * `__meta_digitalocean_status`: The current status of the Droplet. -* `__meta_digitalocean_features`: Optional properties configured for the Droplet, such as IPV6 networking, private networking, or backups. * `__meta_digitalocean_tags`: The tags assigned to the Droplet. * `__meta_digitalocean_vpc`: The ID of the VPC where the Droplet is located. @@ -78,21 +77,21 @@ Each discovered Droplet maps to one target. ## Component health -`discovery.digitalocean` is only reported as unhealthy when given an invalid -configuration. In those cases, exported fields retain their last healthy -values. +`discovery.digitalocean` is only reported as unhealthy when given an invalid configuration. +In those cases, exported fields retain their last healthy 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 This would result in targets with `__address__` labels like: `192.0.2.1:8080`: + ```river discovery.digitalocean "example" { port = 8080 @@ -107,16 +106,16 @@ prometheus.scrape "demo" { prometheus.remote_write "demo" { endpoint { - url = PROMETHEUS_REMOTE_WRITE_URL + url = basic_auth { - username = USERNAME - password = PASSWORD + username = + 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. + - ``: The URL of the Prometheus remote_write-compatible server to send metrics to. + - ``: The username to use for authentication to the remote_write API. + - ``: The password to use for authentication to the remote_write API. diff --git a/docs/sources/flow/reference/components/discovery.dns.md b/docs/sources/flow/reference/components/discovery.dns.md index 3a2615d5df29..975b9d2f49d1 100644 --- a/docs/sources/flow/reference/components/discovery.dns.md +++ b/docs/sources/flow/reference/components/discovery.dns.md @@ -26,42 +26,41 @@ discovery.dns "LABEL" { The following arguments are supported: -Name | Type | Description | Default | Required ----- | ---- | ----------- | ------- | -------- -`names` | `list(string)` | DNS names to look up. | | yes -`port` | `number` | Port to use for collecting metrics. Not used for SRV records. | `0` | no -`refresh_interval` | `duration` | How often to query DNS for updates. | `"30s"` | no -`type` | `string` | Type of DNS record to query. Must be one of SRV, A, AAAA, or MX. | `"SRV"` | no +Name | Type | Description | Default | Required +-------------------|----------------|------------------------------------------------------------------|---------|--------- +`names` | `list(string)` | DNS names to look up. | | yes +`port` | `number` | Port to use for collecting metrics. Not used for SRV records. | `0` | no +`refresh_interval` | `duration` | How often to query DNS for updates. | `"30s"` | no +`type` | `string` | Type of DNS record to query. Must be one of SRV, A, AAAA, or MX. | `"SRV"` | no ## Exported fields The following field is exported and can be referenced by other components: -Name | Type | Description ----- | ---- | ----------- +Name | Type | Description +----------|---------------------|--------------------------------------------------- `targets` | `list(map(string))` | The set of targets discovered from the docker API. Each target includes the following labels: +* `__meta_dns_mx_record_target`: Target field of the MX record. * `__meta_dns_name`: Name of the record that produced the discovered target. -* `__meta_dns_srv_record_target`: Target field of the SRV record. * `__meta_dns_srv_record_port`: Port field of the SRV record. -* `__meta_dns_mx_record_target`: Target field of the MX record. +* `__meta_dns_srv_record_target`: Target field of the SRV record. ## Component health -`discovery.dns` is only reported as unhealthy when given an invalid -configuration. In those cases, exported fields retain their last healthy -values. +`discovery.dns` is only reported as unhealthy when given an invalid configuration. +In those cases, exported fields retain their last healthy values. ## Debug information -`discovery.dns` does not expose any component-specific debug information. +`discovery.dns` doesn't expose any component-specific debug information. ## Debug metrics -`discovery.dns` does not expose any component-specific debug metrics. +`discovery.dns` doesn't expose any component-specific debug metrics. ## Example @@ -81,16 +80,16 @@ prometheus.scrape "demo" { prometheus.remote_write "demo" { endpoint { - url = PROMETHEUS_REMOTE_WRITE_URL + url = basic_auth { - username = USERNAME - password = PASSWORD + username = + 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. \ No newline at end of file + - ``: The URL of the Prometheus remote_write-compatible server to send metrics to. + - ``: The username to use for authentication to the remote_write API. + - ``: The password to use for authentication to the remote_write API. diff --git a/docs/sources/flow/reference/components/discovery.docker.md b/docs/sources/flow/reference/components/discovery.docker.md index 076f00f75b21..6adb01251a1d 100644 --- a/docs/sources/flow/reference/components/discovery.docker.md +++ b/docs/sources/flow/reference/components/discovery.docker.md @@ -27,21 +27,21 @@ discovery.docker "LABEL" { The following arguments are supported: -Name | Type | Description | Default | Required ----- | ---- | ----------- | ------- | -------- -`host` | `string` | Address of the Docker Daemon to connect to. | | yes -`port` | `number` | Port to use for collecting metrics when containers don't have any port mappings. | `80` | no -`host_networking_host` | `string` | Host to use if the container is in host networking mode. | `"localhost"` | no -`refresh_interval` | `duration` | Frequency to refresh list of containers. | `"1m"` | 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 +Name | Type | Description | Default | Required +-----------------------|------------|----------------------------------------------------------------------------------|---------------|--------- +`host` | `string` | Address of the Docker Daemon to connect to. | | 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 +`host_networking_host` | `string` | Host to use if the container is in host networking mode. | `"localhost"` | no +`port` | `number` | Port to use for collecting metrics when containers don't have any port mappings. | `80` | no +`proxy_url` | `string` | HTTP proxy to proxy requests through. | | no +`refresh_interval` | `duration` | Frequency to refresh list of containers. | `"1m"` | no At most one of the following can be provided: - [`bearer_token` argument](#arguments). - - [`bearer_token_file` argument](#arguments). + - [`bearer_token_file` argument](#arguments). - [`basic_auth` block][basic_auth]. - [`authorization` block][authorization]. - [`oauth2` block][oauth2]. @@ -50,20 +50,18 @@ Name | Type | Description | Default | Required ## Blocks -The following blocks are supported inside the definition of -`discovery.docker`: +The following blocks are supported inside the definition of `discovery.docker`: -Hierarchy | Block | Description | Required ---------- | ----- | ----------- | -------- -filter | [filter][] | Filters discoverable 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 +Hierarchy | Block | Description | Required +--------------------|-------------------|----------------------------------------------------------|--------- +authorization | [authorization][] | Configure generic authorization to the endpoint. | no +basic_auth | [basic_auth][] | Configure basic_auth for authenticating to the endpoint. | no +filter | [filter][] | Filters discoverable resources. | 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 -The `>` symbol indicates deeper levels of nesting. For example, -`oauth2 > tls_config` refers to a `tls_config` block defined inside -an `oauth2` block. +The `>` symbol indicates deeper levels of nesting. +For example, `oauth2 > tls_config` refers to a `tls_config` block defined inside an `oauth2` block. [filter]: #filter-block [basic_auth]: #basic_auth-block @@ -71,91 +69,82 @@ an `oauth2` block. [oauth2]: #oauth2-block [tls_config]: #tls_config-block -### filter block +### authorization -The `filter` block configures a filter to pass to the Docker Engine to limit -the amount of containers returned. The `filter` block can be specified multiple -times to provide more than one filter. +{{< docs/shared lookup="flow/reference/components/authorization-block.md" source="agent" version="" >}} -Name | Type | Description | Default | Required ----- | ---- | ----------- | ------- | -------- -`name` | `string` | Filter name to use. | | yes -`values` | `list(string)` | Values to pass to the filter. | | yes +### basic_auth -Refer to [List containers][List containers] from the Docker Engine API -documentation for the list of supported filters and their meaning. +{{< docs/shared lookup="flow/reference/components/basic-auth-block.md" source="agent" version="" >}} -[List containers]: https://docs.docker.com/engine/api/v1.41/#tag/Container/operation/ContainerList +### filter -### basic_auth block +The `filter` block configures a filter to pass to the Docker Engine to limit the amount of containers returned. +The `filter` block can be specified multiple times to provide more than one filter. -{{< docs/shared lookup="flow/reference/components/basic-auth-block.md" source="agent" version="" >}} +Name | Type | Description | Default | Required +---------|----------------|-------------------------------|---------|--------- +`name` | `string` | Filter name to use. | | yes +`values` | `list(string)` | Values to pass to the filter. | | yes -### authorization block +Refer to [List containers][List containers] from the Docker Engine API +documentation for the list of supported filters and their meaning. -{{< docs/shared lookup="flow/reference/components/authorization-block.md" source="agent" version="" >}} +[List containers]: https://docs.docker.com/engine/api/v1.41/#tag/Container/operation/ContainerList -### oauth2 block +### oauth2 -{{< docs/shared lookup="flow/reference/components/oauth2-block.md" source="agent" version="" >}} +{{< docs/shared lookup="flow/reference/components/oauth2-block.md" source="agent" version="" >}} -### tls_config block +### oauth2 > tls_config -{{< docs/shared lookup="flow/reference/components/tls-config-block.md" source="agent" version="" >}} +{{< docs/shared lookup="flow/reference/components/tls-config-block.md" source="agent" version="" >}} ## Exported fields The following fields are exported and can be referenced by other components: -Name | Type | Description ----- | ---- | ----------- +Name | Type | Description +----------|---------------------|--------------------------------------------------- `targets` | `list(map(string))` | The set of targets discovered from the docker API. Each target includes the following labels: * `__meta_docker_container_id`: ID of the container. +* `__meta_docker_container_label_`: Each label from the container. * `__meta_docker_container_name`: Name of the container. * `__meta_docker_container_network_mode`: Network mode of the container. -* `__meta_docker_container_label_`: Each label from the container. * `__meta_docker_network_id`: ID of the Docker network the container is in. +* `__meta_docker_network_ingress`: Set to `true` if the Docker network is an ingress network. +* `__meta_docker_network_internal`: Set to `true` if the Docker network is an internal network. +* `__meta_docker_network_ip`: The IP of the container in the network. +* `__meta_docker_network_label_`: Each label from the network the container is in. * `__meta_docker_network_name`: Name of the Docker network the container is in. -* `__meta_docker_network_ingress`: Set to `true` if the Docker network is an - ingress network. -* `__meta_docker_network_internal`: Set to `true` if the Docker network is an - internal network. -* `__meta_docker_network_label_`: Each label from the network the - container is in. * `__meta_docker_network_scope`: The scope of the network the container is in. -* `__meta_docker_network_ip`: The IP of the container in the network. * `__meta_docker_port_private`: The private port on the container. -* `__meta_docker_port_public`: The publicly exposed port from the container, - if a port mapping exists. -* `__meta_docker_port_public_ip`: The public IP of the container, if a port - mapping exists. +* `__meta_docker_port_public_ip`: The public IP of the container, if a port mapping exists. +* `__meta_docker_port_public`: The publicly exposed port from the container, if a port mapping exists. -Each discovered container maps to one target per unique combination of networks -and port mappings used by the container. +Each discovered container maps to one target per unique combination of networks and port mappings used by the container. ## Component health -`discovery.docker` is only reported as unhealthy when given an invalid -configuration. In those cases, exported fields retain their last healthy -values. +`discovery.docker` is only reported as unhealthy when given an invalid configuration. +In those cases, exported fields retain their last healthy values. ## Debug information -`discovery.docker` does not expose any component-specific debug information. +`discovery.docker` doesn't expose any component-specific debug information. ## Debug metrics -`discovery.docker` does not expose any component-specific debug metrics. +`discovery.docker` doesn't expose any component-specific debug metrics. ## Examples ### Linux or macOS hosts -This example discovers Docker containers when the host machine is macOS or -Linux: +This example discovers Docker containers when the host machine is macOS or Linux: ```river discovery.docker "containers" { @@ -169,19 +158,19 @@ prometheus.scrape "demo" { prometheus.remote_write "demo" { endpoint { - url = PROMETHEUS_REMOTE_WRITE_URL + url = basic_auth { - username = USERNAME - password = PASSWORD + username = + 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. + - ``: The URL of the Prometheus remote_write-compatible server to send metrics to. + - ``: The username to use for authentication to the remote_write API. + - ``: The password to use for authentication to the remote_write API. ### Windows hosts @@ -199,19 +188,20 @@ prometheus.scrape "demo" { prometheus.remote_write "demo" { endpoint { - url = PROMETHEUS_REMOTE_WRITE_URL + url = basic_auth { - username = USERNAME - password = PASSWORD + username = + 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. + - ``: The URL of the Prometheus remote_write-compatible server to send metrics to. + - ``: The username to use for authentication to the remote_write API. + - ``: The password to use for authentication to the remote_write API. -> **NOTE**: This example requires the "Expose daemon on tcp://localhost:2375 -> without TLS" setting to be enabled in the Docker Engine settings. +{{% admonition type="note" %}} +This example requires the "Expose daemon on tcp://localhost:2375 without TLS" setting to be enabled in the Docker Engine settings. +{{% /admonition %}} diff --git a/docs/sources/shared/flow/reference/components/authorization-block.md b/docs/sources/shared/flow/reference/components/authorization-block.md index 190cd11f8bb9..79ffc301039d 100644 --- a/docs/sources/shared/flow/reference/components/authorization-block.md +++ b/docs/sources/shared/flow/reference/components/authorization-block.md @@ -10,11 +10,10 @@ description: Shared content, authorization block headless: true --- -Name | Type | Description | Default | Required ----- | ---- | ----------- | ------- | -------- -`type` | `string` | Authorization type, for example, "Bearer". | | no -`credentials` | `secret` | Secret value. | | no -`credentials_file` | `string` | File containing the secret value. | | no +Name | Type | Description | Default | Required +-------------------|----------|--------------------------------------------|---------|--------- +`credentials_file` | `string` | File containing the secret value. | | no +`credentials` | `secret` | Secret value. | | no +`type` | `string` | Authorization type, for example, "Bearer". | | no -`credential` and `credentials_file` are mutually exclusive and only one can be -provided inside of an `authorization` block. +`credential` and `credentials_file` are mutually exclusive and only one can be provided inside of an `authorization` block. diff --git a/docs/sources/shared/flow/reference/components/azuread-block.md b/docs/sources/shared/flow/reference/components/azuread-block.md index ebdf436d02fe..2ffb379fff08 100644 --- a/docs/sources/shared/flow/reference/components/azuread-block.md +++ b/docs/sources/shared/flow/reference/components/azuread-block.md @@ -10,8 +10,8 @@ description: Shared content, azuread block headless: true --- -Name | Type | Description | Default | Required ----- | ---- | ----------- | ------- | -------- +Name | Type | Description | Default | Required +--------|----------|------------------|-----------------|--------- `cloud` | `string` | The Azure Cloud. | `"AzurePublic"` | no The supported values for `cloud` are: diff --git a/docs/sources/shared/flow/reference/components/basic-auth-block.md b/docs/sources/shared/flow/reference/components/basic-auth-block.md index 06c81f660e3c..19b956c7ca9a 100644 --- a/docs/sources/shared/flow/reference/components/basic-auth-block.md +++ b/docs/sources/shared/flow/reference/components/basic-auth-block.md @@ -10,11 +10,10 @@ description: Shared content, basic auth block headless: true --- -Name | Type | Description | Default | Required ----- | ---- | ----------- | ------- | -------- -`username` | `string` | Basic auth username. | | no -`password` | `secret` | Basic auth password. | | no -`password_file` | `string` | File containing the basic auth password. | | no +Name | Type | Description | Default | Required +----------------|----------|------------------------------------------|---------|--------- +`password_file` | `string` | File containing the basic auth password. | | no +`password` | `secret` | Basic auth password. | | no +`username` | `string` | Basic auth username. | | no -`password` and `password_file` are mutually exclusive and only one can be -provided inside of a `basic_auth` block. +`password` and `password_file` are mutually exclusive and only one can be provided inside of a `basic_auth` block. diff --git a/docs/sources/shared/flow/reference/components/exporter-component-exports.md b/docs/sources/shared/flow/reference/components/exporter-component-exports.md index beb717a13fae..4bf4ae82b44d 100644 --- a/docs/sources/shared/flow/reference/components/exporter-component-exports.md +++ b/docs/sources/shared/flow/reference/components/exporter-component-exports.md @@ -13,15 +13,12 @@ headless: true The following fields are exported and can be referenced by other components. Name | Type | Description ---------- | ------------------- | ----------- +----------|---------------------|---------------------------------------------------------- `targets` | `list(map(string))` | The targets that can be used to collect exporter metrics. -For example, the `targets` can either be passed to a `discovery.relabel` -component to rewrite the targets' label sets, or to a `prometheus.scrape` -component that collects the exposed metrics. +For example, the `targets` can either be passed to a `discovery.relabel` component to rewrite the targets' label sets, or to a `prometheus.scrape` component that collects the exposed metrics. -The exported targets will use the configured [in-memory traffic][] address -specified by the [run command][]. +The exported targets will use the configured [in-memory traffic][] address specified by the [run command][]. [in-memory traffic]: {{< relref "../../../../flow/concepts/component_controller.md#in-memory-traffic" >}} [run command]: {{< relref "../../../../flow/reference/cli/run.md" >}} diff --git a/docs/sources/shared/flow/reference/components/extract-field-block.md b/docs/sources/shared/flow/reference/components/extract-field-block.md index 5036097d155f..2f30a1b137dc 100644 --- a/docs/sources/shared/flow/reference/components/extract-field-block.md +++ b/docs/sources/shared/flow/reference/components/extract-field-block.md @@ -12,31 +12,28 @@ headless: true The following attributes are supported: -Name | Type | Description | Default | Required ----- |----------------|----------------------------------------------------------------------------------------------------------|---------| -------- -`tag_name` | `string` | The name of the resource attribute that will be added to logs, metrics, or spans. | `""` | no -`key` | `string` | The annotation (or label) name. This must exactly match an annotation (or label) name. | `""` | no -`key_regex` | `string` | A regular expression used to extract a key that matches the regex. | `""` | no -`regex` | `string` | An optional field used to extract a sub-string from a complex field value. | `""` | no -`from` | `string` | The source of the labels or annotations. Allowed values are `pod` and `namespace`. | `pod` | no - -When `tag_name` is not specified, a default tag name will be used with the format: +Name | Type | Description | Default | Required +------------|----------|------------------------------------------------------------------------------------|---------|--------- +`from` | `string` | The source of the labels or annotations. Allowed values are `pod` and `namespace`. | `pod` | no +`key_regex` | `string` | A regular expression used to extract a key that matches the regular expression. | `""` | no +`key` | `string` | The annotation or label name. This must exactly match an annotation or label name. | `""` | no +`regex` | `string` | An optional field used to extract a sub-string from a complex field value. | `""` | no +`tag_name` | `string` | The name of the resource attribute that will be added to logs, metrics, or spans. | `""` | no + +When `tag_name` isn't specified, a default tag name is used with the format: * `k8s.pod.annotations.` * `k8s.pod.labels.