Vector Remap Language

https://vector.dev/docs/reference/vrl/
Admin
Vector Remap Language (VRL) is a domain-specific language for safely and performantly transforming...
Tokens:149,422
Snippets:1,655
Trust Score:9.8
Update:3 months ago
Show doc for...
Tokens:
Raw
### Find Substring at Start

Source: https://vector.dev/docs/reference/vrl/functions

Finds the starting position of a substring that appears at the beginning of the string.

```VRL
find("foobar", "foo")
```

--------------------------------

### Check for string start with mismatch

Source: https://vector.dev/docs/reference/vrl/examples

Demonstrates a case-sensitive check where the string does not start with the specified substring.

```VRL
starts_with("foobar", "F")
```

--------------------------------

### Example Log Event

Source: https://vector.dev/docs/reference/vrl

A sample Vector log event in JSON format.

```json
{
  "message": "key1=value1 key2=value2"
}
```

--------------------------------

### Get Hostname

Source: https://vector.dev/docs/reference/vrl/examples

Retrieves the local system's hostname.

```vector
get_hostname!()
```

--------------------------------

### Slice a string from a start index

Source: https://vector.dev/docs/reference/vrl/examples

Returns a portion of a string from the specified start index to the end of the string.

```VRL
slice!("foobar", 3)
```

--------------------------------

### VRL Comment Example

Source: https://vector.dev/docs/reference/vrl/expressions

Demonstrates the syntax for single-line comments in VRL, identified by the '#' character.

```VRL
# comment
```

--------------------------------

### VRL Multi-line Comment Example

Source: https://vector.dev/docs/reference/vrl/expressions

Shows how to create multi-line comments in VRL by preceding each line with '#'.

```VRL
# multi-line
# comment
```

--------------------------------

### Get Environment Variable

Source: https://vector.dev/docs/reference/vrl/examples

Retrieves the value of the 'HOME' environment variable.

```vector
get_env_var!("HOME")
```

--------------------------------

### Basic Remap Transform with VRL

Source: https://vector.dev/docs/reference/vrl

This example shows a basic `remap` transform in a Vector configuration that uses VRL to delete a field and add a timestamp.

```yaml
transforms:
  modify:
    type: remap
    inputs:
      - logs
    source: |
      del(.user_info)
      .timestamp = now()

```

--------------------------------

### VRL Type Coercion and Function Usage

Source: https://vector.dev/docs/reference/vrl

Demonstrates VRL's progressive type safety. The first example shows how VRL infers types and uses error handling for potentially incompatible operations. The second example shows explicit type coercion for guaranteed type safety.

```vrl
.foo # any
.foo = downcase!(.foo) # string
.foo = upcase(.foo) # string
```

```vrl
.foo = string!(.foo) # string

.foo = downcase(.foo) # string
```

--------------------------------

### Assert Equality (Successful)

Source: https://vector.dev/docs/reference/vrl/examples

Use `assert_eq!` to verify that two expressions are equal. The program aborts if they are not. This example shows a successful equality assertion.

```VRL
assert_eq!(1, 1)
```

--------------------------------

### Get Missing Index

Source: https://vector.dev/docs/reference/vrl/examples

Demonstrates that `get` returns `null` when an index in the path is out of bounds for an array.

```vector
get!(value: {"foo": { "bar": [92, 42] }}, path: ["foo", "bar", 1, -1])
```

--------------------------------

### Log Message with Info Level

Source: https://vector.dev/docs/reference/vrl/examples

Use the `log` function to output a message to stdout at a specified level. This example logs a simple string at the 'info' level with a rate limit.

```VRL
log("Hello, World!", level: "info", rate_limit_secs: 60)
```

--------------------------------

### Assert Equality (Unsuccessful)

Source: https://vector.dev/docs/reference/vrl/examples

Use `assert_eq!` to verify that two expressions are equal. The program aborts if they are not. This example shows an unsuccessful equality assertion.

```VRL
assert_eq!(127, [1, 2, 3])
```

--------------------------------

### Slice an array from a start index

Source: https://vector.dev/docs/reference/vrl/examples

Returns a portion of an array from the specified start index to the end of the array.

```VRL
slice!([0, 1, 2], 1)
```

--------------------------------

### Calculate MD5 hash

Source: https://vector.dev/docs/reference/vrl/examples

Generates an MD5 hash for a given string value. This is a basic example of using the md5 function.

```VRL
md5("foo")
```

--------------------------------

### Check if a string starts with a substring (case insensitive)

Source: https://vector.dev/docs/reference/vrl/examples

Determines if a string begins with a specified substring, ignoring character case.

```VRL
starts_with("The Needle In The Haystack", "the needle", case_sensitive: false)
```

--------------------------------

### Parse Custom Logs with VRL using Regex and Key/Value

Source: https://vector.dev/docs/reference/vrl

This example demonstrates a multi-step VRL transformation: first, parsing a custom log format using `parse_regex!`, then coercing data types, and finally extracting structured data using `split` and `parse_key_value`. It also merges the extracted structured data back into the event.

```json
{
  "message": "2021/01/20 06:39:15 +0000 [error] 17755#17755: *3569904 open() \"/usr/share/nginx/html/test.php\" failed (2: No such file or directory), client: xxx.xxx.xxx.xxx, server: localhost, request: \"GET /test.php HTTP/1.1\", host: \"yyy.yyy.yyy.yyy\""
}
```

```vrl
. |= parse_regex!(.message, r'^ (?P<timestamp>\d+/\d+/\d+ \d+:\d+:\d+ \+\d+) \[(?P<severity>\w+)\] (?P<pid>\d+)#(?P<tid>\d+):(?: \*(?P<connid>\d+))? (?P<message>.*)$')

# Coerce parsed fields
.timestamp = parse_timestamp(.timestamp, "%Y/%m/%d %H:%M:%S %z") ?? now()
.pid = to_int!(.pid)
.tid = to_int!(.tid)

# Extract structured data
message_parts = split(.message, ", ", limit: 2)
structured = parse_key_value(message_parts[1], key_value_delimiter: ":", field_delimiter: ",") ?? {}
.message = message_parts[0]
. = merge(., structured)
```

```json
{
  "log": {
    "client": "xxx.xxx.xxx.xxx",
    "connid": "3569904",
    "host": "yyy.yyy.yyy.yyy",
    "message": "open() \"/usr/share/nginx/html/test.php\" failed (2: No such file or directory)",
    "pid": 17755,
    "request": "GET /test.php HTTP/1.1",
    "server": "localhost",
    "severity": "error",
    "tid": 17755,
    "timestamp": "2021-01-20T06:39:15Z"
  }
}
```

--------------------------------

### Remove and Compact Array

Source: https://vector.dev/docs/reference/vrl/examples

This example demonstrates how `compact: true` with `remove!` can remove an entire field if it becomes empty after an element is deleted from an array.

```vector
remove!(value: {"foo": [42], "bar": true }, path: ["foo", 0], compact: true)
```

--------------------------------

### Get from variable

Source: https://vector.dev/docs/reference/vrl/functions

Demonstrates retrieving a value from a variable that holds an object.

```Vector Script
var = { "foo": true }
get!(value: var, path: ["foo"])

```

--------------------------------

### Check if a string starts with a substring (case sensitive)

Source: https://vector.dev/docs/reference/vrl/examples

Determines if a string begins with a specified substring, considering character case.

```VRL
starts_with("The Needle In The Haystack", "The Needle")
```

--------------------------------

### Perform a basic DNS lookup

Source: https://vector.dev/docs/reference/vrl/examples

Executes a DNS lookup for a given domain name, defaulting to an 'A' record type. The example shows how to process and filter the results, including setting a static TTL and removing specific record types.

```VRL
res = dns_lookup!("dns.google")
# reset non-static ttl so result is static
res.answers = map_values(res.answers) -> |value| {
  value.ttl = 600
  value
}
# remove extra responses for example
res.answers = filter(res.answers) -> |_, value| {
    value.rData == "8.8.8.8"
}
# remove class since this is also dynamic
res.additional = map_values(res.additional) -> |value| {
    del(value.class)
    value
}
res

```

--------------------------------

### Find Substring with Offset

Source: https://vector.dev/docs/reference/vrl/functions

Finds the starting position of a substring, beginning the search from a specified offset.

```VRL
find("foobarfoobarfoo", "bar", 4)
```

--------------------------------

### Get keys from an object

Source: https://vector.dev/docs/reference/vrl/examples

Retrieves all top-level keys from a given object.

```vector
keys({
    "key1": "val1",
    "key2": "val2"
})
```

--------------------------------

### Infallible Function Call Example

Source: https://vector.dev/docs/reference/vrl/expressions

Shows a simple call to an infallible function, 'split', which does not require error handling.

```VRL
split("apples and pears and bananas", " and ")
```

--------------------------------

### Find substring in string

Source: https://vector.dev/docs/reference/vrl/examples

Locates the starting position of a substring within a string. Returns null if the substring is not found.

```VRL
find("foobar", "bar")
```

```VRL
find("foobar", "foo")
```

```VRL
find("foobar", "baz")
```

```VRL
find("foobarfoobarfoo", "bar", 4)
```

--------------------------------

### Find substring using regex

Source: https://vector.dev/docs/reference/vrl/examples

Locates the starting position of a pattern matched by a regular expression within a string.

```VRL
find("foobar", r'b.r')
```

--------------------------------

### Calculate SHA-1 hash

Source: https://vector.dev/docs/reference/vrl/examples

Generates a SHA-1 hash for a given string value. This is a straightforward example of using the sha1 function.

```VRL
sha1("foo")
```

--------------------------------

### Assert Equality with Custom Message

Source: https://vector.dev/docs/reference/vrl/examples

Use `assert_eq!` to verify equality and provide a custom message that will be logged if the assertion fails. This example demonstrates an unsuccessful assertion with a custom log message.

```VRL
assert_eq!(1, 0, message: "Unequal integers")
```

--------------------------------

### Compact a complex object using null: false

Source: https://vector.dev/docs/reference/vrl/examples

Compact an object while preserving null values by setting `null: false`. This example shows how to retain nulls and empty arrays while removing empty objects and strings.

```vector
compact({ "a": {}, "b": null, "c": [null], "d": "", "e": "-", "f": true }, null: false)
```

--------------------------------

### Set Nested Array Index

Source: https://vector.dev/docs/reference/vrl/examples

This example shows how `set!` can insert an element at a specific index in a nested array, creating intermediate `null` values if necessary.

```vector
set!(value: {"foo": { "bar": [] }}, path: ["foo", "bar", 1], data: "baz")
```

--------------------------------

### Log Error Message

Source: https://vector.dev/docs/reference/vrl/examples

Use the `log` function to output an error message. This example demonstrates logging an error that occurs during a type conversion, checking for a non-null error value.

```VRL
. = { "field": "not an integer" }
_, err = to_int(.field)
if err != null {
    log(err, level: "error")
}
```

--------------------------------

### Assert Condition (False) with Message

Source: https://vector.dev/docs/reference/vrl/examples

Use `assert!` to verify a condition. The program aborts with the provided message if the condition is false. This example shows an unsuccessful assertion.

```VRL
assert!("foo" == "bar", message: "\"foo\" must be \"foo\"!")
```

--------------------------------

### Get with invalid indexing

Source: https://vector.dev/docs/reference/vrl/functions

Attempting to index an array with a non-integer path segment results in a null return.

```Vector Script
get!(value: [42], path: ["foo"])

```

--------------------------------

### Assert Condition (True) with Message

Source: https://vector.dev/docs/reference/vrl/examples

Use `assert!` to verify a condition. The program aborts with the provided message if the condition is false. This example shows a successful assertion.

```VRL
assert!("foo" == "foo", message: "\"foo\" must be \"foo\"!")
```

--------------------------------

### Parse Custom Logs with Regex and Key/Value

Source: https://vector.dev/docs/reference/vrl/examples

Parses a custom log message using a combination of `parse_regex`, `parse_timestamp`, `to_int`, `split`, `parse_key_value`, and `merge`. This example demonstrates complex log structure extraction.

```json
{
  "message": "2021/01/20 06:39:15 +0000 [error] 17755#17755: *3569904 open() \"/usr/share/nginx/html/test.php\" failed (2: No such file or directory), client: xxx.xxx.xxx.xxx, server: localhost, request: \"GET /test.php HTTP/1.1\", host: \"yyy.yyy.yyy.yyy\""
}
```

```VRL
. |= parse_regex!(.message, r'^\d+/\d+/\d+ \d+:\d+:\d+ \+\d+ \[(?P<severity>\w+)\] (?P<pid>\d+)#(?P<tid>\d+):(?: \*(?P<connid>\d+))? (?P<message>.*)$')

# Coerce parsed fields
.timestamp = parse_timestamp(.timestamp, "%Y/%m/%d %H:%M:%S %z") ?? now()
.pid = to_int!(.pid)
.tid = to_int!(.tid)

# Extract structured data
message_parts = split(.message, ", ", limit: 2)
structured = parse_key_value(message_parts[1], key_value_delimiter: ":", field_delimiter: ",") ?? {}
.message = message_parts[0]
. = merge(., structured)
```

```json
{
  "log": {
    "client": "xxx.xxx.xxx.xxx",
    "connid": "3569904",
    "host": "yyy.yyy.yyy.yyy",
    "message": "open() \"/usr/share/nginx/html/test.php\" failed (2: No such file or directory)",
    "pid": 17755,
    "request": "GET /test.php HTTP/1.1",
    "server": "localhost",
    "severity": "error",
    "tid": 17755,
    "timestamp": "2021-01-20T06:39:15Z"
  }
}
```

--------------------------------

### Handle Division by Zero in VRL

Source: https://vector.dev/docs/reference/vrl/errors

Demonstrates how to safely perform division by checking for null errors when a divisor might be zero.

```VRL
result, err = 27 / .some_value
if err != null {
	# Handle error
}
```

--------------------------------

### Convert to SCREAMING_SNAKE_CASE

Source: https://vector.dev/docs/reference/vrl/examples

Converts an input string to SCREAMING_SNAKE_CASE. This example shows conversion from kebab-case without specifying the original case.

```vector
screamingsnakecase("input-string")

```

--------------------------------

### Filter Transform with Simple VRL Condition

Source: https://vector.dev/docs/reference/vrl

This example demonstrates a `filter` transform in Vector configuration that uses a simple VRL condition to exclude events where the 'severity' field is 'info'.

```yaml
transforms:
  filter_out_info:
    type: filter
    inputs:
      - logs
    condition: '.severity != "info"'

```

--------------------------------

### Get with invalid segment type

Source: https://vector.dev/docs/reference/vrl/functions

The `get` function raises an error if a path segment is not a string or an integer.

```Vector Script
get!(value: {"foo": { "bar": [92, 42] }}, path: ["foo", true])

```

--------------------------------

### Get from external target

Source: https://vector.dev/docs/reference/vrl/functions

Retrieves a value from the current event using the `get` function with an external target.

```Vector Script
get!(value: ., path: ["foo"])

```

--------------------------------

### starts_with

Source: https://vector.dev/docs/reference/vrl/functions

Checks if a string begins with a specified substring, with an option for case sensitivity.

```APIDOC
## starts_with

### Description
Determines whether `value` begins with `substring`.

### Function Signature
starts_with(value: <string> ,substring: <string> , [case_sensitive: <boolean> ] )

### Parameters
#### value
- **value** (string) - Required - The string to search.
#### substring
- **substring** (string) - Required - The substring that the `value` must start with.
#### case_sensitive
- **case_sensitive** (boolean) - Optional - Whether the match should be case sensitive. Defaults to `true`.

### Examples
##### String starts with (case sensitive)
```
starts_with("The Needle In The Haystack", "The Needle")
```
Returns: `true`

##### String starts with (case insensitive)
```
starts_with("The Needle In The Haystack", "the needle", case_sensitive: false)
```
Returns: `true`

##### String starts with (case sensitive failure)
```
starts_with("foobar", "F")
```
Returns: `false`
```

--------------------------------

### Get Field from External Target

Source: https://vector.dev/docs/reference/vrl/examples

Retrieves a field's value from the current event context (represented by `.`) using the `get` function.

```vector
get!(value: ., path: ["foo"])
```

--------------------------------

### Get Returns Null for Unknown Field

Source: https://vector.dev/docs/reference/vrl/examples

Shows that the `get` function returns `null` when the specified path does not exist in the provided value.

```vector
get!(value: {"foo": "bar"}, path: ["baz"])
```

--------------------------------

### Get Single-Segment Top-Level Field

Source: https://vector.dev/docs/reference/vrl/examples

Retrieves the value of a top-level field using its name. This is a basic usage of the dynamic `get` function.

```vector
get!(value: {"foo": "bar"}, path: ["foo"])
```

--------------------------------

### Get Invalid Indexing

Source: https://vector.dev/docs/reference/vrl/examples

Shows that `get` returns `null` when attempting to access an array element with a path segment that is not a valid index (e.g., a string).

```vector
get!(value: [42], path: ["foo"])
```

--------------------------------

### Format Timestamp with Custom Format

Source: https://vector.dev/docs/reference/vrl/examples

Formats a timestamp using a custom format string. Example uses '%v %R' for day-month-year and hour:minute.

```VRL
format_timestamp!(t'2020-10-21T16:00:00Z', format: "%v %R")
```

--------------------------------

### Simple Variable Assignment and Comparison

Source: https://vector.dev/docs/reference/vrl/expressions

Demonstrates assigning a value to a variable and then comparing it.

```VRL
my_variable = 1
my_variable == 1
```

```boolean
true
```

--------------------------------

### find

Source: https://vector.dev/docs/reference/vrl/functions

Finds the starting position of the first occurrence of a pattern within a string. Returns null if the pattern is not found. Supports string or regex patterns and an optional starting offset.

```APIDOC
## find

### Description
Determines from left to right the start position of the first found element in `value` that matches `pattern`. Returns null if not found.

### Function Signature
`find(value: <string>, pattern: <string | regex>, [from: <integer>]) -> <integer | null>`

### Parameters
- **value** (string) - Required - The string to find the pattern in.
- **pattern** (string | regex) - Required - The regular expression or string pattern to match against.
- **from** (integer) - Optional - Offset to start searching. Defaults to `0`.

### Examples
##### Match text
```
find("foobar", "bar")
```

##### Match text at start
```
find("foobar", "foo")
```

##### Match regex
```
find("foobar", r'b.r')
```

##### No matches
```
find("foobar", "baz")
```

##### With an offset
```
find("foobarfoobarfoo", "bar", 4)
```
```

--------------------------------

### Basic HTTP GET Request

Source: https://vector.dev/docs/reference/vrl/examples

Makes a basic HTTP GET request to a URL and parses the JSON response. It then redacts the origin IP and filters out headers containing 'id'.

```vector
. = parse_json!(http_request!("https://httpbin.org/get"))

# Redact the origin ip
.origin = redact!(.origin, filters: [r'.*'], redactor: {"type": "text", "replacement": "***"})
# Delete any ids in headers
.headers = filter(object!(.headers)) -> |key, _value| { !contains(key, "id", false) }
.
```

--------------------------------

### Parse Syslog Log (RFC 5424)

Source: https://vector.dev/docs/reference/vrl/examples

Parses a syslog message according to RFC 5424 format. Ensure the input string starts with a valid syslog header.

```vrl
parse_syslog!(s'<13>1 2020-03-13T20:45:38.119Z dynamicwireless.name non 2426 ID931 [exampleSDID@32473 iut="3" eventSource= "Application" eventID="1011"] Try to override the THX port, maybe it will reboot the neural interface!')
```

--------------------------------

### Get Invalid Segment Type

Source: https://vector.dev/docs/reference/vrl/examples

Illustrates that `get` returns `null` if a path segment's type is incompatible with the data structure (e.g., using a boolean as a key for an object).

```vector
get!(value: {"foo": { "bar": [92, 42] }}, path: ["foo", true])
```

--------------------------------

### VRL Compile-Time Error Example

Source: https://vector.dev/docs/reference/vrl

This example demonstrates a VRL compile-time error due to an incorrect argument type passed to the `parse_json!` function. The compiler provides detailed feedback, including suggestions for error handling and type coercion.

```vrl
parse_json!(1)
```

```text
error[E110]: invalid argument type
  ┌─ :2:13
  │
2 │ parse_json!(1)
  │             ^
  │             │
  │             this expression resolves to the exact type integer
  │             but the parameter "value" expects the exact type string
  │
  = try: ensuring an appropriate type at runtime
  =
  =     1 = string!(1)
  =     parse_json!(1)
  =
  = try: coercing to an appropriate type and specifying a default value as a fallback in case coercion fails
  =
  =     1 = to_string(1) ?? "default"
  =     parse_json!(1)
  =
  = see documentation about error handling at https://errors.vrl.dev/#handling
  = learn more about error code 110 at https://errors.vrl.dev/110
  = see language documentation at https://vrl.dev
  = try your code in the VRL REPL, learn more at https://vrl.dev/examples
```

--------------------------------

### Assert Condition (False) - Simple

Source: https://vector.dev/docs/reference/vrl/examples

Use `assert!` to verify a condition. The program aborts if the condition is false. This is a simple assertion that will always fail.

```VRL
assert!(false)
```

--------------------------------

### Get length of an array

Source: https://vector.dev/docs/reference/vrl/examples

Returns the number of elements in an array.

```vector
length(["Trail Blazers", "Supersonics", "Grizzlies"])
```

--------------------------------

### Get length of an object

Source: https://vector.dev/docs/reference/vrl/examples

Calculates the number of top-level keys in an object.

```vector
length({
    "portland": "Trail Blazers",
    "seattle": "Supersonics"
})
```

--------------------------------

### Root Event Path

Source: https://vector.dev/docs/reference/vrl/expressions

Selects the entire event data.

```Vector Event
{
  "log": {
    "message": "Hello, World!"
  }
}
```

```VRL
.
```

--------------------------------

### Parse User Agent (Fast Mode)

Source: https://vector.dev/docs/reference/vrl/examples

Parses a user agent string in 'fast' mode, providing basic information about the browser, device, and OS. Fields may be null if parsing fails.

```vrl
parse_user_agent("Mozilla Firefox 1.0.1 Mozilla/5.0 (X11; U; Linux i686; de-DE; rv:1.7.6) Gecko/20050223 Firefox/1.0.1")
```

--------------------------------

### Relative File Directory Name

Source: https://vector.dev/docs/reference/vrl/functions

Demonstrates that a relative file path has the current directory '.' as its directory name.

```VRL
dirname!("file.txt")
```

--------------------------------

### Calculate HMAC with variable hash algorithm

Source: https://vector.dev/docs/reference/vrl/examples

Demonstrates calculating an HMAC where the hashing algorithm is determined by a variable. It includes error handling for the HMAC calculation.

```VRL
.hash_algo = "SHA-256"
hmac_bytes, err = hmac("Hello there", "super-secret-key", algorithm: .hash_algo)
if err == null {
    .hmac = encode_base16(hmac_bytes)
}
```

--------------------------------

### Named Function Invocation (Unordered)

Source: https://vector.dev/docs/reference/vrl/expressions

Invokes the 'split' function using named arguments, demonstrating that the order of named arguments does not matter.

```VRL
split(pattern: ", ", value: "hello, world!")
```

--------------------------------

### String Array Literal

Source: https://vector.dev/docs/reference/vrl/expressions

An example of an array literal containing only string values.

```VRL
["first", "second", "third"]
```

--------------------------------

### Find No Matches

Source: https://vector.dev/docs/reference/vrl/functions

Demonstrates the result when a pattern is not found within the string.

```VRL
find("foobar", "baz")
```

--------------------------------

### strip_whitespace

Source: https://vector.dev/docs/reference/vrl/functions

Strips whitespace from the start and end of a string. Whitespace is defined by the Unicode White_Space property.

```APIDOC
## strip_whitespace(value: string)

### Description
Strips whitespace from the start and end of `value`, where whitespace is defined by the Unicode `White_Space` property.

### Parameters
#### Path Parameters
- **value** (string) - Required - The string to trim.

### Request Example
```
strip_whitespace("  A sentence.  ")
```

### Response
#### Success Response (200)
- **return** (string) - The trimmed string.

### Response Example
```
A sentence.
```
```

--------------------------------

### Parse URL with Credentials and Port

Source: https://vector.dev/docs/reference/vrl/examples

Parses a full URL string including scheme, username, password, host, port, path, query parameters, and fragment. Handles various URL components.

```vrl
parse_url!("ftp://foo:bar@example.com:4343/foobar?hello=world#123")
```

--------------------------------

### Encode String to Snappy and then Base64

Source: https://vector.dev/docs/reference/vrl/examples

Encodes a string using Snappy compression and then encodes the compressed data using Base64. This is useful for reducing data size for transmission or storage.

```VRL
encode_base64(encode_snappy!("The quick brown fox jumps over 13 lazy dogs."))
```

--------------------------------

### Get Field from Variable

Source: https://vector.dev/docs/reference/vrl/examples

Retrieves a field's value from a variable that holds a data structure.

```vector
var = { "foo": true }
get!(value: var, path: ["foo"])
```

--------------------------------

### Encode String to Base64 (Default)

Source: https://vector.dev/docs/reference/vrl/examples

Encodes a string to Base64 using default settings, including padding.

```VRL
encode_base64("please encode me")
```

--------------------------------

### Get Array Element by Index

Source: https://vector.dev/docs/reference/vrl/examples

Accesses an element within an array using its zero-based index.

```vector
get!(value: [92, 42], path: [0])
```

--------------------------------

### Get length of a string

Source: https://vector.dev/docs/reference/vrl/examples

Returns the number of bytes in a string. For character count, use `strlen`.

```vector
length("The Planet of the Apes Musical")
```

--------------------------------

### Multiple Parsing Strategies with Fallback

Source: https://vector.dev/docs/reference/vrl/examples

Applies multiple parsing functions sequentially (`parse_syslog`, `parse_common_log`, `parse_regex`) and merges the result. This is useful when log formats can vary.

```json
{
  "message": "\u003c102\u003e1 2020-12-22T15:22:31.111Z vector-user.biz su 2666 ID389 - Something went wrong"
}
```

```VRL
structured =
  parse_syslog(.message) ??
  parse_common_log(.message) ??
  parse_regex!(.message, r'^\d+/\d+/\d+ \d+:\d+:\d+ \[(?P<severity>\w+)\] (?P<pid>\d+)#(?P<tid>\d+):(?: \*(?P<connid>\d+))? (?P<message>.*)$')
. = merge(., structured)
```

```json
{
  "log": {
    "appname": "su",
    "facility": "ntp",
    "hostname": "vector-user.biz",
    "message": "Something went wrong",
    "msgid": "ID389",
    "procid": 2666,
    "severity": "info",
    "timestamp": "2020-12-22T15:22:31.111Z",
    "version": 1
  }
}
```

--------------------------------

### Get length of a nested object

Source: https://vector.dev/docs/reference/vrl/examples

Calculates the number of top-level keys in a nested object structure.

```vector
length({
    "home": {
        "city":  "Portland",
        "state": "Oregon"
    },
    "name": "Trail Blazers",
    "mascot": {
        "name": "Blaze the Trail Cat"
    }
})
```

--------------------------------

### Get with missing index

Source: https://vector.dev/docs/reference/vrl/functions

Accessing an array index that is out of bounds results in a null return value.

```Vector Script
get!(value: {"foo": { "bar": [92, 42] }}, path: ["foo", "bar", 1, -1])

```

--------------------------------

### Split an empty path

Source: https://vector.dev/docs/reference/vrl/examples

Splitting an empty path results in an empty array.

```VRL
split_path("")
```

--------------------------------

### Get Multi-Segment Nested Field

Source: https://vector.dev/docs/reference/vrl/examples

Retrieves a value from a nested structure by providing a sequence of path segments.

```vector
get!(value: {"foo": { "bar": true }}, path: ["foo", "bar"])
```

--------------------------------

### Get values from object

Source: https://vector.dev/docs/reference/vrl/examples

Extracts all the values from a given object and returns them as an array. Uses the `values` function.

```vector
values({"key1": "val1", "key2": "val2"})
```

--------------------------------

### Use Multiple Parsing Strategies in VRL

Source: https://vector.dev/docs/reference/vrl

This VRL script demonstrates how to apply multiple parsing strategies sequentially using the `??` (or) operator. It attempts to parse the message using `parse_syslog`, then `parse_common_log`, and finally a custom regex, merging the result of the first successful parse. This is useful for handling logs that might conform to different formats.

```json
{
  "message": "\u003c102\u003e1 2020-12-22T15:22:31.111Z vector-user.biz su 2666 ID389 - Something went wrong"
}
```

```vrl
structured =
  parse_syslog(.message) ??
  parse_common_log(.message) ??
  parse_regex!(.message, r'^ (?P<timestamp>\d+/\d+/\d+ \d+:\d+:\d+) \[(?P<severity>\w+) \] (?P<pid>\d+)#(?P<tid>\d+):(?: \*(?P<connid>\d+))? (?P<message>.*)$')
. = merge(., structured)
```

```json
{
  "log": {
    "appname": "su",
    "facility": "ntp",
    "hostname": "vector-user.biz",
    "message": "Something went wrong",
    "msgid": "ID389",
    "procid": 2666,
    "severity": "info",
    "timestamp": "2020-12-22T15:22:31.111Z",
    "version": 1
  }
}
```

--------------------------------

### Slice a string with positive indices

Source: https://vector.dev/docs/reference/vrl/examples

Returns a portion of a string between specified start and end positions. Indices are zero-based.

```VRL
slice!("Supercalifragilisticexpialidocious", start: 5, end: 13)
```

--------------------------------

### Parse Gigabytes to Bytes (Decimal)

Source: https://vector.dev/docs/reference/vrl/examples

Parses a gigabyte string into bytes using decimal units and a base of 10 with parse_bytes!.

```VRL
parse_bytes!("1GB", unit: "B", base: "10")
```

--------------------------------

### Integer and Float Equality Comparison

Source: https://vector.dev/docs/reference/vrl/expressions

Compares an integer with a float for equality, demonstrating type coercion during comparison.

```VRL
1 == 1.0
```

--------------------------------

### Empty Array Literal

Source: https://vector.dev/docs/reference/vrl/expressions

Represents an empty array literal in VRL. This can be used as a starting point for building arrays.

```VRL
[]
```

--------------------------------

### get

Source: https://vector.dev/docs/reference/vrl/functions

Dynamically retrieves the value of a given path from an object or array. Handles nested structures and array indexing.

```APIDOC
## get

### Description
Dynamically get the value of a given path. If you know the path you want to look up, use static paths such as `.foo.bar[1]` to get the value of that path. However, if you do not know the path names, use the dynamic `get` function to get the requested value.

### Function Signature
`get(value: <object | array>, path: <array>) -> <any>, <error>`

### Parameters
#### Value
- **value** (object | array) - Required - The object or array to query.

#### Path
- **path** (array) - Required - An array of path segments to look for the value.

### Errors
- The `path` segment must be a string or an integer.

### Examples
#### Single-segment top-level field
```
get!(value: {"foo": "bar"}, path: ["foo"])
```

Return:
```
bar
```

#### Returns null for unknown field
```
get!(value: {"foo": "bar"}, path: ["baz"])
```

Return:
```
null
```

#### Multi-segment nested field
```
get!(value: {"foo": { "bar": true }}, path: ["foo", "bar"])
```

Return:
```
true
```

#### Array indexing
```
get!(value: [92, 42], path: [0])
```

Return:
```
92
```

#### Array indexing (negative)
```
get!(value: ["foo", "bar", "baz"], path: [-2])
```

Return:
```
bar
```

#### Nested indexing
```
get!(value: {"foo": { "bar": [92, 42] }}, path: ["foo", "bar", 1])
```

Return:
```
42
```

#### External target
Input:
```json
{
  "foo": true
}
```

Source:
```
get!(value: ., path: ["foo"])
```

Return:
```
true
```

#### Variable
```
var = { "foo": true }
get!(value: var, path: ["foo"])
```

Return:
```
true
```

#### Missing index
```
get!(value: {"foo": { "bar": [92, 42] }}, path: ["foo", "bar", 1, -1])
```

Return:
```
null
```

#### Invalid indexing
```
get!(value: [42], path: ["foo"])
```

Return:
```
null
```

#### Invalid segment type
```
get!(value: {"foo": { "bar": [92, 42] }}, path: ["foo", true])
```

Raises:
```
function call error for "get" at (0:62): path segment must be either string or integer, not boolean
```
```

--------------------------------

### Encode String to Zlib and then Base64

Source: https://vector.dev/docs/reference/vrl/examples

Encodes a string using Zlib compression and then encodes the compressed data using Base64. This is a common method for data compression and encoding.

```VRL
encode_base64(encode_zlib("please encode me"))
```

--------------------------------

### Parse Nginx access log (main format)

Source: https://vector.dev/docs/reference/vrl/examples

Parses an Nginx access log line using the 'main' format. This format includes client IP, user, timestamp, request details, status, size, referer, and user agent.

```vrl
parse_nginx_log!(
    s'172.24.0.3 - alice [31/Dec/2024:17:32:06 +0000] "GET / HTTP/1.1" 200 615 "https://domain.tld/path" "curl/8.11.1" "1.2.3.4, 10.10.1.1"',
    "main"
)
```

--------------------------------

### Get nested indexing

Source: https://vector.dev/docs/reference/vrl/functions

Combines object and array indexing to retrieve values from deeply nested structures.

```Vector Script
get!(value: {"foo": { "bar": [92, 42] }}, path: ["foo", "bar", 1])

```

--------------------------------

### Get array indexing

Source: https://vector.dev/docs/reference/vrl/functions

Accesses an element in an array using its zero-based index provided in the path array.

```Vector Script
get!(value: [92, 42], path: [0])

```

--------------------------------

### Multiline If Predicate

Source: https://vector.dev/docs/reference/vrl/expressions

Shows how to use multiple expressions within an 'if' predicate, separated by semicolons or newlines.

```VRL
x = 3
if (x = x + 1; x == 5) {
	# not evaluated
	null
} else if (
	x = x + 1
	x == 5
) {
	"Hello, World!"
}
```

--------------------------------

### Get single-segment top-level field

Source: https://vector.dev/docs/reference/vrl/functions

Retrieves the value of a top-level field from an object using a dynamic path.

```Vector Script
get!(value: {"foo": "bar"}, path: ["foo"])

```

--------------------------------

### Handle Invalid Syslog Facility Keyword

Source: https://vector.dev/docs/reference/vrl/functions

Demonstrates error handling for an invalid Syslog facility keyword when converting to a code.

```VRL
to_syslog_facility_code!(s'foobar')
```

--------------------------------

### Get Nested Array Element

Source: https://vector.dev/docs/reference/vrl/examples

Combines nested object access and array indexing to retrieve a specific value.

```vector
get!(value: {"foo": { "bar": [92, 42] }}, path: ["foo", "bar", 1])
```

--------------------------------

### Format Timestamp with Timezone Conversion

Source: https://vector.dev/docs/reference/vrl/examples

Formats a timestamp and converts it to a specified timezone. The example converts to 'Europe/Berlin' time.

```VRL
format_timestamp!(t'2021-02-10T23:32:00+00:00', format: "%d %B %Y %H:%M", timezone: "Europe/Berlin")
```

--------------------------------

### Convert Syslog Facility Code to Keyword

Source: https://vector.dev/docs/reference/vrl/functions

Converts a Syslog facility code (integer) to its corresponding keyword (string). Requires error handling as invalid codes will raise an error.

```VRL
to_syslog_facility!(4)
```

--------------------------------

### Root Directory Name

Source: https://vector.dev/docs/reference/vrl/functions

Shows that the directory name of the root path '/' is itself.

```VRL
dirname!("/")
```

--------------------------------

### Get Type Definition at Runtime

Source: https://vector.dev/docs/reference/vrl/examples

Retrieves the type definition of an expression at runtime. This is an unstable debug function; its behavior is not guaranteed.

```vector
type_def(42)
```

--------------------------------

### Parse Gigabytes to Bytes (Ambiguous Binary)

Source: https://vector.dev/docs/reference/vrl/examples

Parses a gigabyte string into bytes using ambiguous binary units and a base of 2 with parse_bytes!.

```VRL
parse_bytes!("1GB", unit: "B", base: "2")
```

--------------------------------

### Get Array Element by Negative Index

Source: https://vector.dev/docs/reference/vrl/examples

Retrieves an array element using a negative index, which counts from the end of the array.

```vector
get!(value: ["foo", "bar", "baz"], path: [-2])
```

--------------------------------

### Assigning an Undefined Variable

Source: https://vector.dev/docs/reference/vrl/errors

Demonstrates how to fix an undefined variable by assigning it a value before referencing it.

```VRL
my_variable
```

```VRL
+my_variable = true
my_variable
```

--------------------------------

### Get Non-existent Secret

Source: https://vector.dev/docs/reference/vrl/examples

Demonstrates calling get_secret with a key that does not exist in the event metadata. This will likely return null or an empty value.

```vector
get_secret("i_dont_exist")
```

--------------------------------

### Convert Syslog Facility Keyword to Code

Source: https://vector.dev/docs/reference/vrl/functions

Converts a Syslog facility keyword (string) to its corresponding integer code. Requires error handling as invalid keywords will raise an error.

```VRL
to_syslog_facility_code!("authpriv")
```

--------------------------------

### Get Secret from Event Metadata

Source: https://vector.dev/docs/reference/vrl/examples

Retrieves the value of a specified secret from the event's metadata. Ensure the secret key exists.

```vector
get_secret("datadog_api_key")
```

--------------------------------

### Parse Simple Query String

Source: https://vector.dev/docs/reference/vrl/examples

Parses a basic query string into a key-value map.

```VRL
parse_query_string("foo=1&bar=2")
```

--------------------------------

### Calculate Haversine Distance in Kilometers

Source: https://vector.dev/docs/reference/vrl/examples

Calculates the haversine distance and bearing between two geographical points in kilometers. No special setup is required.

```vector
haversine(0.0, 0.0, 10.0, 10.0)
```

--------------------------------

### Get array indexing (negative)

Source: https://vector.dev/docs/reference/vrl/functions

Supports negative indexing for arrays, where -1 refers to the last element, -2 to the second to last, and so on.

```Vector Script
get!(value: ["foo", "bar", "baz"], path: [-2])

```

--------------------------------

### Perform DNS lookup with custom class and qtype

Source: https://vector.dev/docs/reference/vrl/examples

Performs a DNS lookup specifying the record class and query type. This allows for more targeted DNS queries beyond the default 'A' record.

```VRL
res = dns_lookup!("dns.google", class: "IN", qtype: "A")
# reset non-static ttl so result is static
res.answers = map_values(res.answers) -> |value| {
  value.ttl = 600
  value
}
# remove extra responses for example
res.answers = filter(res.answers) -> |_, value| {
    value.rData == "8.8.8.8"
}
# remove class since this is also dynamic
res.additional = map_values(res.additional) -> |value| {
    del(value.class)
    value
}
res

```

--------------------------------

### Extract basename from file path

Source: https://vector.dev/docs/reference/vrl/examples

Use `basename` to get the filename component of a path. If the path ends with a separator, it returns the directory name.

```vrl
basename!("/usr/local/bin/vrl")
```

```vrl
basename!("/home/user/file.txt")
```

```vrl
basename!("/home/user/")
```

```vrl
basename!("/")
```

--------------------------------

### Calculate negative Seahash

Source: https://vector.dev/docs/reference/vrl/examples

Demonstrates a Seahash calculation that results in a negative value due to the conversion to a signed 64-bit integer. This highlights the potential for wrap-around.

```VRL
seahash("bar")
```

--------------------------------

### Round Number Down (0.45)

Source: https://vector.dev/docs/reference/vrl/examples

Demonstrates rounding down behavior for numbers less than .5 using the `round` function. For example, 5.45 rounds down to 5.

```Vector
round(5.45)
```
Tokens:
Raw