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

chore(external docs): First batch of editorial edits for the Functions doc #18780

Merged
merged 5 commits into from
Oct 17, 2023
Merged

chore(external docs): First batch of editorial edits for the Functions doc #18780

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d3da178
make edits
maycmlee Oct 5, 2023
8ef2e7a
more edits
maycmlee Oct 5, 2023
c16c460
apply suggestions
maycmlee Oct 5, 2023
10d917e
Apply suggestions from code review
maycmlee Oct 16, 2023
326ada7
cue fmt
jszwedko Oct 17, 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
14 changes: 7 additions & 7 deletions website/cue/reference/remap/functions.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,10 +59,10 @@ remap: {

// Reusable text
_enrichment_table_explainer: """
For `file` enrichment tables this condition needs to be a VRL object in which
For `file` enrichment tables, this condition needs to be a VRL object in which
the key-value pairs indicate a field to search mapped to a value to search in that field.
This function returns the rows that match the provided condition(s). _All_ fields need to
match for rows to be returned; if any fields don't match, no rows are returned.
match for rows to be returned; if any fields do not match, then no rows are returned.

There are currently two forms of search criteria:

Expand All @@ -72,15 +72,15 @@ remap: {
performance perspective.

2. **Date range search**. The given field must be greater than or equal to the `from` date
and less than or equal to the `to` date. Note that a date range search involves
sequentially scanning through the rows that have been located via any exact match
and less than or equal to the `to` date. A date range search involves
sequentially scanning through the rows that have been located using any exact match
criteria. This can be an expensive operation if there are many rows returned by any exact
match criteria. We recommend using date ranges as the _only_ criteria when the enrichment
match criteria. Therefore, use date ranges as the _only_ criteria when the enrichment
data set is very small.

For `geoip` enrichment tables this condition needs to be a VRL object with a single key-value pair
For `geoip` enrichment tables, this condition needs to be a VRL object with a single key-value pair
whose value needs to be a valid IP address. Example: `{"ip": .ip }`. If a return field is expected
and without a value, `null` will be used. This table can return following fields:
and without a value, `null` is used. This table can return the following fields:

* ISP databases:
* `autonomous_system_number`
Expand Down
4 changes: 2 additions & 2 deletions website/cue/reference/remap/functions/append.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,13 @@ remap: functions: append: {
arguments: [
{
name: "value"
description: "The initial array"
description: "The initial array."
required: true
type: ["array"]
},
{
name: "items"
description: "The items to append"
description: "The items to append."
required: true
type: ["array"]
},
Expand Down
4 changes: 2 additions & 2 deletions website/cue/reference/remap/functions/assert.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,14 +26,14 @@ remap: functions: assert: {
description: """
An optional custom error message. If the equality assertion fails, `message` is
appended to the default message prefix. See the [examples](#assert-examples) below
for a sample fully formed log message.
for a fully formed log message sample.
"""
required: false
type: ["string"]
},
]
internal_failure_reasons: [
"`condition` evaluates to `false`",
"`condition` evaluates to `false`.",
]
return: types: ["null"]

Expand Down
4 changes: 2 additions & 2 deletions website/cue/reference/remap/functions/assert_eq.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ remap: functions: assert_eq: {

description: """
Asserts that two expressions, `left` and `right`, have the same value. The program is
aborted with the `message` if they are unequal.
aborted with `message` if they do not have the same value.
"""

notices: [
Expand Down Expand Up @@ -34,7 +34,7 @@ remap: functions: assert_eq: {
description: """
An optional custom error message. If the equality assertion fails, `message` is
appended to the default message prefix. See the [examples](#assert_eq-examples)
below for a sample fully formed log message.
below for a fully formed log message sample.
"""
required: false
type: ["string"]
Expand Down
6 changes: 3 additions & 3 deletions website/cue/reference/remap/functions/chunks.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ package metadata
remap: functions: chunks: {
category: "Array"
description: """
Chunks `value` into slices of length `chunk_size` bytes
Chunks `value` into slices of length `chunk_size` bytes.
"""

arguments: [
Expand All @@ -21,8 +21,8 @@ remap: functions: chunks: {
},
]
internal_failure_reasons: [
"`chunk_size` must be at least 1 byte",
"`chunk_size` is too large",
"`chunk_size` must be at least 1 byte.",
"`chunk_size` is too large.",
]
return: {
types: ["array"]
Expand Down
2 changes: 1 addition & 1 deletion website/cue/reference/remap/functions/compact.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ package metadata
remap: functions: compact: {
category: "Enumerate"
description: """
Compacts the `value` by removing "empty" values, where emptiness is defined using the
Compacts the `value` by removing empty values, where empty values are defined using the
available parameters.
"""

Expand Down
12 changes: 6 additions & 6 deletions website/cue/reference/remap/functions/decrypt.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ remap: functions: decrypt: {
arguments: [
{
name: "ciphertext"
description: "The string to decrypt. The should be raw bytes (not encoded)."
description: "The string in raw bytes (not encoded) to decrypt."
required: true
type: ["string"]
},
Expand All @@ -45,14 +45,14 @@ remap: functions: decrypt: {
},
{
name: "key"
description: "The key for decryption. The should be raw bytes of the key (not encoded). The length must match the algorithm requested."
description: "The key in raw bytes (not encoded) for decryption. The length must match the algorithm requested."
required: true
type: ["string"]
},
{
name: "iv"
description: #"""
The IV for decryption. The should be raw bytes of the IV (not encoded). The length must match the algorithm requested.
The IV in raw bytes (not encoded) for decryption. The length must match the algorithm requested.
A new IV should be generated for every message. You can use `random_bytes` to generate a cryptographically secure random value.
The value should match the one used during encryption.
"""#
Expand All @@ -61,9 +61,9 @@ remap: functions: decrypt: {
},
]
internal_failure_reasons: [
"`algorithm` isn't a supported algorithm",
"`key` length doesn't match the key size required for the algorithm specified",
"`iv` length doesn't match the iv size required for the algorithm specified",
"`algorithm` is not a supported algorithm.",
"`key` length does not match the key size required for the algorithm specified.",
"`iv` length does not match the `iv` size required for the algorithm specified.",
]
return: types: ["string"]

Expand Down
10 changes: 5 additions & 5 deletions website/cue/reference/remap/functions/encode_key_value.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ package metadata
remap: functions: encode_key_value: {
category: "Codec"
description: """
Encodes the `value` to in key/value format with customizable delimiters. Default delimiters match
Encodes the `value` into key-value format with customizable delimiters. Default delimiters match
the [logfmt](\(urls.logfmt)) format.
"""
notices: [
Expand All @@ -21,7 +21,7 @@ remap: functions: encode_key_value: {
},
{
name: "fields_ordering"
description: "The ordering of fields to preserve. Any fields not in this list will appear unordered, after any ordered fields."
description: "The ordering of fields to preserve. Any fields not in this list are listed unordered, after all ordered fields."
required: false
type: ["array"]
},
Expand All @@ -34,21 +34,21 @@ remap: functions: encode_key_value: {
},
{
name: "field_delimiter"
description: "The string that separates each key/value pair."
description: "The string that separates each key-value pair."
required: false
default: " "
type: ["string"]
},
{
name: "flatten_boolean"
description: "Whether to encode key/value with a boolean value as a standalone key if `true` and nothing if `false`."
description: "Whether to encode key-value with a boolean value as a standalone key if `true` and nothing if `false`."
required: false
type: ["boolean"]
default: false
},
]
internal_failure_reasons: [
"`fields_ordering` contains a non-string element",
"`fields_ordering` contains a non-string element.",
]
return: types: ["string"]

Expand Down
4 changes: 2 additions & 2 deletions website/cue/reference/remap/functions/encode_logfmt.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,13 +16,13 @@ remap: functions: encode_logfmt: {
},
{
name: "fields_ordering"
description: "The ordering of fields to preserve. Any fields not in this list will appear unordered, after any ordered fields."
description: "The ordering of fields to preserve. Any fields not in this list are listed unordered, after all ordered fields."
required: false
type: ["array"]
},
]
internal_failure_reasons: [
"`fields_ordering` contains a non-string element",
"`fields_ordering` contains a non-string element.",
]
return: types: ["string"]

Expand Down
2 changes: 1 addition & 1 deletion website/cue/reference/remap/functions/encode_percent.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ remap: functions: encode_percent: {
},
{
name: "ascii_set"
description: "The ascii set to use when encoding the data."
description: "The ASCII set to use when encoding the data."
required: false
type: ["string"]
default: "NON_ALPHANUMERIC"
Expand Down
10 changes: 5 additions & 5 deletions website/cue/reference/remap/functions/encrypt.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,24 +54,24 @@ remap: functions: encrypt: {
},
{
name: "key"
description: "The key for encryption. The should be raw bytes of the key (not encoded). The length must match the algorithm requested."
description: "The key in raw bytes (not encoded) for encryption. The length must match the algorithm requested."
required: true
type: ["string"]
},
{
name: "iv"
description: #"""
The IV for encryption. The should be raw bytes of the IV (not encoded). The length must match the algorithm requested.
The IV in raw bytes (not encoded) for encryption. The length must match the algorithm requested.
A new IV should be generated for every message. You can use `random_bytes` to generate a cryptographically secure random value.
"""#
required: true
type: ["string"]
},
]
internal_failure_reasons: [
"`algorithm` isn't a supported algorithm",
"`key` length doesn't match the key size required for the algorithm specified",
"`iv` length doesn't match the iv size required for the algorithm specified",
"`algorithm` is not a supported algorithm.",
"`key` length does not match the key size required for the algorithm specified.",
"`iv` length does not match the `iv` size required for the algorithm specified.",
]
return: types: ["string"]

Expand Down
10 changes: 4 additions & 6 deletions website/cue/reference/remap/functions/filter.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,20 +6,18 @@ remap: functions: filter: {
Filter elements from a collection.

This function currently *does not* support recursive iteration.
If you have a need for recursive iteration using `filter`, then
[please let us know](\(urls.new_feature_request))!
Comment on lines -9 to -10
Copy link
Contributor Author

Choose a reason for hiding this comment

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

I removed this because I didn't know if we wanted to change it to contact Datadog support and link to https://docs.datadoghq.com/help/. We would then need to have information for the support team so they know what to do when users reach about it. If we don't, we can still say something like:

Copy link
Member

Choose a reason for hiding this comment

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

Gotcha, yeah, that seems fine to drop this block.


The function uses the "function closure syntax" to allow reading
the key/value or index/value combination for each item in the
The function uses the function closure syntax to allow reading
the key-value or index-value combination for each item in the
collection.

The same scoping rules apply to closure blocks as they do for
regular blocks, meaning, any variable defined in parent scopes
regular blocks. This means that any variable defined in parent scopes
are accessible, and mutations to those variables are preserved,
maycmlee marked this conversation as resolved.
Show resolved Hide resolved
but any new variables instantiated in the closure block are
unavailable outside of the block.

Check out the examples below to learn about the closure syntax.
See the examples below to learn about the closure syntax.
"""

arguments: [
Expand Down
8 changes: 2 additions & 6 deletions website/cue/reference/remap/functions/for_each.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,22 +6,18 @@ remap: functions: for_each: {
Iterate over a collection.

This function currently *does not* support recursive iteration.
If you have a need for recursive iteration using `for_each`,
which can't be solved using the `map_keys` or `map_values`
enumeration functions (which *do* support recursion), then
[please let us know](\(urls.new_feature_request))!
Comment on lines -9 to -12
Copy link
Contributor Author

Choose a reason for hiding this comment

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

Same as previous, I removed this because I didn't know if we wanted to change it to contact Datadog support and link to https://docs.datadoghq.com/help/.

See map_keys or map_values for recursive iteration using for_each.

Copy link
Member

Choose a reason for hiding this comment

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

Same, we can drop. Ideally we'd have one link in the Vector docs and a different one in the Datadog docs.


The function uses the "function closure syntax" to allow reading
the key/value or index/value combination for each item in the
collection.

The same scoping rules apply to closure blocks as they do for
regular blocks, meaning, any variable defined in parent scopes
regular blocks. This means that any variable defined in parent scopes
are accessible, and mutations to those variables are preserved,
maycmlee marked this conversation as resolved.
Show resolved Hide resolved
but any new variables instantiated in the closure block are
unavailable outside of the block.

Check out the examples below to learn about the closure syntax.
See the examples below to learn about the closure syntax.
"""

arguments: [
Expand Down
2 changes: 1 addition & 1 deletion website/cue/reference/remap/functions/format_int.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ remap: functions: format_int: {
},
]
internal_failure_reasons: [
"base is not between 2 and 36",
"The base is not between 2 and 36.",
]
return: types: ["string"]

Expand Down
3 changes: 1 addition & 2 deletions website/cue/reference/remap/functions/from_unix_timestamp.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,7 @@ remap: functions: from_unix_timestamp: {
description: """
Converts the `value` integer from a [Unix timestamp](\(urls.unix_timestamp)) to a VRL `timestamp`.

Converts from the number of seconds since the Unix epoch by default, but milliseconds or nanoseconds can also be
specified by `unit`.
Converts from the number of seconds since the Unix epoch by default. To convert from milliseconds or nanoseconds, set the `unit` argument to `milliseconds` or `nanoseconds`.
"""

arguments: [
Expand Down
8 changes: 4 additions & 4 deletions website/cue/reference/remap/functions/get_enrichment_table_record.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ remap: functions: get_enrichment_table_record: {
category: "Enrichment"
description: """
Searches an [enrichment table](\(urls.enrichment_tables_concept)) for a row that matches the
provided condition. A single row must be matched. If either no rows or more than one row is
provided condition. A single row must be matched. If no rows are found or more than one row is
found, an error is returned.

\(remap._enrichment_table_explainer)
Expand Down Expand Up @@ -37,15 +37,15 @@ remap: functions: get_enrichment_table_record: {
},
{
name: "case_sensitive"
description: "Should text fields match case exactly."
description: "Whether the text fields match the case exactly."
required: false
type: ["boolean"]
default: true
},
]
internal_failure_reasons: [
"The row isn't found",
"Multiple rows are found that match the condition",
"The row is not found.",
"Multiple rows are found that match the condition.",
]
return: types: ["object"]

Expand Down
2 changes: 1 addition & 1 deletion website/cue/reference/remap/functions/get_secret.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ remap: functions: get_secret: {

examples: [
{
title: "Get the Datadog API key from the event metadata."
title: "Get the Datadog API key from the event metadata"
source: #"""
get_secret("datadog_api_key")
"""#
Expand Down
4 changes: 2 additions & 2 deletions website/cue/reference/remap/functions/hmac.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ remap: functions: hmac: {
string using either [encode_base16](\(urls.vrl_functions)/#encode_base16) or
[encode_base64](\(urls.vrl_functions)/#encode_base64).

This function is infallible if either the default `algorithm` value, or a recognized-valid compile-time
`algorithm` string literal is used. Otherwise it is fallible.
This function is infallible if either the default `algorithm` value or a recognized-valid compile-time
`algorithm` string literal is used. Otherwise, it is fallible.
"""

arguments: [
Expand Down
2 changes: 1 addition & 1 deletion website/cue/reference/remap/functions/ip_aton.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ remap: functions: ip_aton: {
},
]
internal_failure_reasons: [
"`value` isn't a valid IPv4 address",
"`value` is not a valid IPv4 address.",
]
return: types: ["integer"]

Expand Down
4 changes: 2 additions & 2 deletions website/cue/reference/remap/functions/ip_cidr_contains.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,8 @@ remap: functions: ip_cidr_contains: {
},
]
internal_failure_reasons: [
"`cidr` isn't a valid CIDR",
"`ip` isn't a valid IP address",
"`cidr` is not a valid CIDR.",
"`ip` is not a valid IP address.",
]
return: types: ["boolean"]

Expand Down
Loading
Loading