Skip to content

Commit

Permalink
Update shared content topics (#5845)
Browse files Browse the repository at this point in the history 
* Update layout and syntax in shared topics

* Updates to language passive voice use etc

* General updates to words syntax and voice

* Fix sorting in table

* Fix table spacing

* Correct capitalization of boolean

* Apply suggestions from code review

Co-authored-by: Robert Fratto <[email protected]>

* Update docs/sources/shared/flow/reference/components/otelcol-debug-metrics-block.md

---------

Co-authored-by: Robert Fratto <[email protected]>
  • Loading branch information
@clayton-cornell @rfratto
clayton-cornell and rfratto authored Nov 27, 2023
1 parent f232fb4 commit dcfdce5
Show file tree
Hide file tree
Showing 34 changed files with 286 additions and 330 deletions.
13 changes: 6 additions & 7 deletions docs/sources/shared/flow/reference/components/authorization-block.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 an `authorization` block.
6 changes: 3 additions & 3 deletions docs/sources/shared/flow/reference/components/azuread-block.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,11 @@ 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:
* `"AzurePublic"`
* `"AzureChina"`
* `"AzureGovernment"`
* `"AzureGovernment"`
13 changes: 6 additions & 7 deletions docs/sources/shared/flow/reference/components/basic-auth-block.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 a `basic_auth` block.
9 changes: 3 additions & 6 deletions docs/sources/shared/flow/reference/components/exporter-component-exports.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 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" >}}
33 changes: 15 additions & 18 deletions docs/sources/shared/flow/reference/components/extract-field-block.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 key 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 added to logs, metrics, or spans. | `""` | no

When you don't specify the `tag_name`, a default tag name is used with the format:
* `k8s.pod.annotations.<annotation key>`
* `k8s.pod.labels.<label key>`

For example, if `tag_name` is not specified and the key is `git_sha`, then the attribute name will be
`k8s.pod.annotations.git_sha`.
For example, if `tag_name` isn't specified and the key is `git_sha`, the attribute name will be `k8s.pod.annotations.git_sha`.

Either the `key` attribute or the `key_regex` attribute should be set, not both.
When `key_regex` is present, `tag_name` supports back reference to both
named capturing and positioned capturing.
You can set either the `key` attribute or the `key_regex` attribute, but not both.
When `key_regex` is present, `tag_name` supports back reference to both named capturing and positioned capturing.

For example, assume your pod spec contains the following labels:
* `app.kubernetes.io/component: mysql`
* `app.kubernetes.io/version: 5.7.21`

If you'd like to add tags for all labels with prefix `app.kubernetes.io/` and trim the prefix,
then you can specify the following extraction rules:
If you'd like to add tags for all labels with the prefix `app.kubernetes.io/` and trim the prefix, then you can specify the following extraction rules:

```river
extract {
Expand All @@ -48,6 +45,6 @@ extract {
}
```

These rules will add the `component` and `version` tags to the spans or metrics.
These rules add the `component` and `version` tags to the spans or metrics.

The `from` attribute can be set to either `"pod"` or `"namespace"`.
You can set the `from` attribute to either `"pod"` or `"namespace"`.
18 changes: 9 additions & 9 deletions docs/sources/shared/flow/reference/components/field-filter-block.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,14 +13,14 @@ headless: true

The following attributes are supported:

Name | Type | Description | Default | Required
---- |----------|-----------------------------------------------------------------------------------|---------| --------
`key` | `string` | The key or name of the field or labels that a filter can use. | | yes
`value` | `string` | The value associated with the key that a filter can use. | | yes
`op` | `string` | The filter operation to apply on the given key: value pair. | `equals` | no
Name | Type | Description | Default | Required
--------|----------|---------------------------------------------------------------|----------|---------
`key` | `string` | The key or name of the field or labels that a filter can use. | | yes
`value` | `string` | The value associated with the key that a filter can use. | | yes
`op` | `string` | The filter operation to apply on the given key: value pair. | `equals` | no

For `op` the following values are allowed:
* `equals`: The field value must be equal to the provided value.
For `op`, the following values are allowed:
* `equals`: The field value must equal the provided value.
* `not-equals`: The field value must not be equal to the provided value.
* `exists`: The field value must exist. (Only for `annotation` fields).
* `does-not-exist`: The field value must not exist. (Only for `annotation` fields).
* `exists`: The field value must exist. Only applicable to `annotation` fields.
* `does-not-exist`: The field value must not exist. Only applicable to `annotation` fields.
18 changes: 8 additions & 10 deletions docs/sources/shared/flow/reference/components/http-client-config-block.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,12 @@ description: Shared content, http client config block
headless: true
---

Name | Type | Description | Default | Required
---- | ---- | ----------- | ------- | --------
`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
--------------------|----------|--------------------------------------------------------------|---------|---------
`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
`proxy_url` | `string` | HTTP proxy to send requests through. | | no

`bearer_token`, `bearer_token_file`, `basic_auth`, `authorization`, and
`oauth2` are mutually exclusive and only one can be provided inside of a
`http_client_config` block.
`bearer_token`, `bearer_token_file`, `basic_auth`, `authorization`, and `oauth2` are mutually exclusive, and only one can be provided inside of a `http_client_config` block.
25 changes: 9 additions & 16 deletions docs/sources/shared/flow/reference/components/local-file-arguments-text.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,28 +12,21 @@ headless: true

### File change detectors

File change detectors are used for detecting when the file needs to be re-read
from disk. `local.file` supports two detectors: `fsnotify` and `poll`.
File change detectors detect when the file needs to be re-read from disk. `local.file` supports two detectors: `fsnotify` and `poll`.

#### fsnotify

The `fsnotify` detector subscribes to filesystem events which indicate when the
watched file had been updated. This requires a filesystem which supports events
at the Operating System level: network-based filesystems like NFS or FUSE won't
work.
The `fsnotify` detector subscribes to filesystem events, which indicate when the watched file is updated.
This detector requires a filesystem that supports events at the operating system level. Network-based filesystems like NFS or FUSE won't work.

When a filesystem event is received, the component will reread the watched
file. This will happen for any filesystem event to the file, including a change
of permissions.
The component re-reads the watched file when a filesystem event is received.
This re-read happens for any filesystem event related to the file, including a permissions change.

`fsnotify` also polls for changes to the file with the configured
`poll_frequency` as a fallback.
`fsnotify` also polls for changes to the file with the configured `poll_frequency` as a fallback.

`fsnotify` will stop receiving filesystem events if the watched file has been
deleted, renamed, or moved. The subscription will be re-established on the next
poll once the watched file exists again.
`fsnotify` stops receiving filesystem events if the watched file has been deleted, renamed, or moved.
The subscription is re-established on the next poll once the watched file exists again.

#### poll

The `poll` file change detector will cause the watched file to be reread
every `poll_frequency`, regardless of whether the file changed.
The `poll` file change detector causes the watched file to be re-read every `poll_frequency`, regardless of whether the file changed.
25 changes: 12 additions & 13 deletions docs/sources/shared/flow/reference/components/loki-server-grpc.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,17 +12,16 @@ headless: true

The `grpc` block configures the gRPC server.

The following arguments can be used to configure the `grpc` block. Any omitted
fields take their default values.
You can use the following arguments to configure the `grpc` block. Any omitted fields take their default values.

Name | Type | Description | Default | Required
---------------------------------|------------|----------------------------------------------------------------------------------------------------------------------|--------------|----------
`listen_address` | `string` | Network address on which the server will listen for new connections. Defaults to accepting all incoming connections. | `""` | no
`listen_port` | `int` | Port number on which the server will listen for new connections. Defaults to a random free port being assigned. | `0` | no
`conn_limit` | `int` | Maximum number of simultaneous http connections. Defaults to no limit. | `0` | no
`max_connection_age` | `duration` | The duration for the maximum amount of time a connection may exist before it will be closed. | `"infinity"` | no
`max_connection_age_grace` | `duration` | An additive period after `max_connection_age` after which the connection will be forcibly closed. | `"infinity"` | no
`max_connection_idle` | `duration` | The duration after which an idle connection should be closed. | `"infinity"` | no
`server_max_recv_msg_size` | `int` | Limit on the size of a gRPC message this server can receive (bytes). | `4MB` | no
`server_max_send_msg_size` | `int` | Limit on the size of a gRPC message this server can send (bytes). | `4MB` | no
`server_max_concurrent_streams` | `int` | Limit on the number of concurrent streams for gRPC calls (0 = unlimited). | `100` | no
Name | Type | Description | Default | Required
--------------------------------|------------|---------------------------------------------------------------------------------------------------------------------|--------------|---------
`conn_limit` | `int` | Maximum number of simultaneous HTTP connections. Defaults to no limit. | `0` | no
`listen_address` | `string` | Network address on which the server listens for new connections. It defaults to accepting all incoming connections. | `""` | no
`listen_port` | `int` | Port number on which the server listens for new connections. Defaults to a random free port. | `0` | no
`max_connection_age_grace` | `duration` | An additive period after `max_connection_age` after which the connection is forcibly closed. | `"infinity"` | no
`max_connection_age` | `duration` | The duration for the maximum time a connection may exist before it is closed. | `"infinity"` | no
`max_connection_idle` | `duration` | The duration after which an idle connection is closed. | `"infinity"` | no
`server_max_concurrent_streams` | `int` | Limit on the number of concurrent streams for gRPC calls (0 = unlimited). | `100` | no
`server_max_recv_msg_size` | `int` | Limit on the size of a gRPC message this server can receive (bytes). | `4MB` | no
`server_max_send_msg_size` | `int` | Limit on the size of a gRPC message this server can send (bytes). | `4MB` | no
Loading

0 comments on commit dcfdce5

Please sign in to comment.