Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update shared content topics #5845

Merged
merged 10 commits into from
Nov 27, 2023
Merged

Update shared content topics #5845

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
de6b4ef
Update layout and syntax in shared topics
clayton-cornell Nov 23, 2023
70bf28b
Updates to language passive voice use etc
clayton-cornell Nov 23, 2023
d3568dd
General updates to words syntax and voice
clayton-cornell Nov 23, 2023
da8b6cc
Fix sorting in table
clayton-cornell Nov 23, 2023
c7932d5
Fix table spacing
clayton-cornell Nov 23, 2023
e7a25ef
Merge branch 'main' into docs/update_shared_content
clayton-cornell Nov 23, 2023
691ed16
Correct capitalization of boolean
clayton-cornell Nov 24, 2023
90f1b0e
Merge branch 'main' into docs/update_shared_content
clayton-cornell Nov 24, 2023
fa3a76f
Apply suggestions from code review
clayton-cornell Nov 24, 2023
05a5af6
Update docs/sources/shared/flow/reference/components/otelcol-debug-me…
clayton-cornell Nov 24, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 6 additions & 7 deletions docs/sources/shared/flow/reference/components/authorization-block.md
View file
Open in desktop
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
Comment on lines +15 to +17
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not convinced that the tables should be alphabetized. Having custom ordering for the tables means we can group related arguments together, even if they don't have similar ordering, and allows us to order things in a way that increases in increasing argument specificity, with more general and common arguments towards the top of the list.

(And for a less compelling argument, people usually see forms as "username and password" but alphabetical sorting means that we're presenting it as "password and username", which is slightly jarring but not a huge deal).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @rfratto. Also, sorting rows alphabetically will be an extra burden when writing docs :/

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rfratto @ptodev I did some research on this over the past 3 days, and consulted the Grafana doc team as well. The advice is to sort lists/tables alphabetically unless the order is important to understanding the information in the list/table (for example required vs optional arguments). This guideline will be added to the Grafana Writer's Toolkit.

Semantic sorting does work (username/password is a great example), but sorting this way adds its own overhead to the doc maintenance. One person's ordering (for example sorting most-used to least used things) isn't always the next person's ordering. Semantic sorting also requires that the SME (developer/community contributor) knows where in the existing lists/tables to insert new arguments. Some people place new content at the bottom of the table/list, some in the middle. It's pretty subjective and very difficult to validate.

Other precedents for sorting alphabetically can be found in OSS documentation such as Linux man pages (which sort command arguments alphabetically) - example: https://man7.org/linux/man-pages/man1/ssh.1.html

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ack, I'm fine with this outcome. Plus, this is something we could undo in the future if alpabetical sorting turns out to cause unforeseen issues.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, there's always a path back if it isn't working for some reason.


`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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
clayton-cornell marked this conversation as resolved.
Show resolved Hide resolved
`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