VRL Function Reference

Here you'll find a comprehensive list of all built-in VRL functions. Functions are categorized by their purpose and sorted alphabetically for easy discovery. To use these functions in Vector, please see the function call expression and the Vector remap transform.

Array functions

append

Appends each item in the items array to the end of the value array.

Spec
```
append(value: <array>, items: <array>) :: <array>
```
- required
  value - The initial array
- required
  items - The items to append
- return - a <array>
Examples
```
append([1, 2], [3, 4])
```
```
[
  1,
  2,
  3,
  4
]
```
Try it yourself with the `vector vrl` subcommand.

push

Adds the item to the end of the value array.

Spec
```
push(value: <array>, item: <any>) :: <array>
```
- required
  value - The target array.
- required
  item - The item to push.
- return - a <array>
  - Returns a new array. The value is not modified in place.
Examples
```
push([1, 2], 3)
```
```
[
  1,
  2,
  3
]
```
Try it yourself with the `vector vrl` subcommand.

Codec functions

decode_base64

Decodes the value (a Base64 string) into its original string.

Spec
```
decode_base64(value: <string>, [charset: <string>]) :: <string>, <error>
```
- required
  value - The Base64 data to decode.
- optional
  charset - The character set to use when decoding the data. Must be one of the following values:
  - standard - Standard Base64 format.
  - url_safe - Modified Base64 for URL variants.
- return - a <string>
Errors
This function is fallible, error handling is required.
- value isn't a valid encoded Base64 string.
Examples
Decode Base64 data (default)
```
decode_base64!("eW91IGhhdmUgc3VjY2Vzc2Z1bGx5IGRlY29kZWQgbWU=")
```
```
"you have successfully decoded me"
```
Try it yourself with the `vector vrl` subcommand.

encode_base64

Encodes the value to Base64.

Spec
```
encode_base64(value: <string>, [padding: <boolean>], [charset: <string>]) :: <string>
```
- required
  value - The string to encode.
- optional
  padding - Whether the Base64 output is padded.
- optional
  charset - The character set to use when encoding the data. Must be one of the following values:
  - standard - Standard Base64 format.
  - url_safe - Modified Base64 for URL variants.
- return - a <string>
Examples
Encode to Base64 (default)
```
encode_base64("please encode me")
```
```
"cGxlYXNlIGVuY29kZSBtZQ=="
```
Try it yourself with the `vector vrl` subcommand.

encode_json

Encodes the value to JSON.

Spec
```
encode_json(value: <any>) :: <string>
```
- required
  value - The value to convert to a JSON string.
- return - a <string>

Examples

.payload = encode_json({"hello": "world"})

"{\"hello\":\"world\"}"

Try it yourself with the `vector vrl` subcommand.

Coerce functions

to_bool

Coerces the value into a boolean.

Spec
```
to_bool(value: <boolean | integer | float | null | string>) :: <boolean>, <error>
```
- required
  value - The value to convert to a Boolean.
- return - a <boolean>
  - If value is "true", "t", "yes", or "y", true is returned.
  - If value is "false", "f", "no", "n", or "0", false is returned.
  - If value is 0.0, false is returned, otherwise true is returned.
  - If value is 0, false is returned, otherwise true is returned.
  - If value is null, false is returned.
  - If value is a Boolean, it's returned unchanged.
Errors
This function is fallible, error handling is required.
- value isn't a supported boolean representation
Examples
Coerce to a Boolean (string)
```
to_bool!("yes")
```
```
true
```
Try it yourself with the `vector vrl` subcommand.

to_float

Coerces the value into a float.

Spec
```
to_float(value: <float | integer | boolean | string>) :: <float>, <error>
```
- required
  value - The value to convert to a float. Must be convertible to a float, otherwise an error is raised.
- return - a <float>
  - If value is a string, it must be the string representation of an float or else an error is raised.
  - If value is a boolean, 0.0 is returned for false and 1.0 is returned for true.
Errors
This function is fallible, error handling is required.
- value isn't a supported float representation
Examples
```
to_float!("3.145")
```
```
3.145
```
Try it yourself with the `vector vrl` subcommand.

to_int

Coerces the value into an integer.

Spec
```
to_int(value: <integer | float | boolean | string | timestamp>) :: <integer>, <error>
```
- required
  value - The value to convert to an integer.
- return - a <integer>
  - If value is a string, it must be the string representation of an integer or else an error is raised.
  - If value is a boolean, 0 is returned for false and 1 is returned for true.
  - If value is a timestamp, a Unix timestamp (in seconds) is returned.
Errors
This function is fallible, error handling is required.
- value is a string but the text is not an integer
- value is not a string, int, or timestamp
Examples
Coerce to an int (string)
```
to_int!("2")
```
```
2
```
Try it yourself with the `vector vrl` subcommand.

to_regex

Coerces the value into a regex.

Spec
```
to_regex(value: <string>) :: <regex>, <error>
```
- required
  value - The value to convert to a regex.
- return - a <regex>
  - If value is a string that contains a valid regex, returns the regex constructed with this string.
Notices
This function has special behavior you should be aware of.
- Compiling a regular expression is an expensive operation and can limit Vector throughput. Don't use this function unless you are absolutely sure there is no other way!
Errors
This function is fallible, error handling is required.
- value is not a string.
Examples
```
to_regex("^foo$") ?? r''
```
```
"^foo$"
```
Try it yourself with the `vector vrl` subcommand.

to_string

Coerces the value into a string.

Spec
```
to_string(value: <integer | float | boolean | string | timestamp | null>) :: <string>, <error>
```
- required
  value - The value to convert to a string.
- return - a <string>
  - If value is an integer or float, returns the string representation.
  - If value is a boolean, returns "true" or "false".
  - If value is a timestamp, returns an RFC 3339) representation.
  - If value is a null, returns "".
Errors
This function is fallible, error handling is required.
- value is not an integer, float, boolean, string, timestamp, or null
Examples
Coerce to a string (Boolean)
```
to_string(true)
```
```
"true"
```
Try it yourself with the `vector vrl` subcommand.

to_timestamp

Coerces the value into a timestamp.

Spec
```
to_timestamp(value: <string | integer | timestamp>) :: <timestamp>, <error>
```
- required
  value - The value that is to be converted to a timestamp. If a string, must be a valid representation of a timestamp, and no default exists, an ArgumentError will be raised.
- return - a <timestamp>
  - If value is a string, the timestamp is parsed in these formats.
  - If value is an integer, it assumed to be a Unix representation of the timestamp (the number of seconds after January 1st, 1970).
Errors
This function is fallible, error handling is required.
- When value is a string, it is not a valid timestamp format
- When value is an int, it is not within the Unix timestamp range
Examples
```
to_timestamp!("2020-10-21T16:00:00Z")
```
```
"2020-10-21T16:00:00Z"
```
Try it yourself with the `vector vrl` subcommand.

Convert functions

to_syslog_facility

Converts the value, a Syslog facility code, into its corresponding Syslog keyword. i.e. 0 into "kern", 1 into "user", etc.

Spec
```
to_syslog_facility(value: <integer>) :: <string>, <error>
```
- required
  value - The facility code.
- return - a <string>
Errors
This function is fallible, error handling is required.
- value isn't a valid Syslog facility code.
Examples
```
to_syslog_facility!(4)
```
```
"auth"
```
Try it yourself with the `vector vrl` subcommand.

to_syslog_level

Converts the value, a Syslog severity level, into its corresponding keyword, i.e. 0 into "emerg", 1 into `"alert", etc.

Spec
```
to_syslog_level(value: <integer>) :: <string>, <error>
```
- required
  value - The severity level.
- return - a <string>
Errors
This function is fallible, error handling is required.
- value isn't a valid Syslog severity level.
Examples
```
to_syslog_level!(5)
```
```
"notice"
```
Try it yourself with the `vector vrl` subcommand.

to_syslog_severity

Converts the value, a Syslog log level keyword, into a Syslog integer severity level (0 to 7).

Spec
```
to_syslog_severity(value: <string>) :: <integer>, <error>
```
- required
  value - The Syslog level keyword to convert.
- return - a <integer>
  - The now-deprecated keywords panic, error, and warn are converted to 0, 3, and 4 respectively.
Errors
This function is fallible, error handling is required.
- value isn't a valid Syslog level keyword
Examples
```
to_syslog_severity!("alert")
```
```
1
```
Try it yourself with the `vector vrl` subcommand.

to_unix_timestamp

Converts the value timestamp into a Unix timestamp.

Returns the number of seconds since the Unix epoch by default, but milliseconds or nanoseconds can also be specified by unit.

Spec
```
to_unix_timestamp(value: <timestamp>, [unit: <string>]) :: <integer>
```
- required
  value - The timestamp to convert to Unix.
- optional
  unit - The time unit. Must be one of the following values:
  - seconds - Express Unix time in seconds
  - milliseconds - Express Unix time in milliseconds
  - nanoseconds - Express Unix time in nanoseconds
- return - a <integer>
Examples
Convert to a Unix timestamp (seconds)
```
to_unix_timestamp(t'2021-01-01T00:00:00+00:00')
```
```
1609459200
```
Try it yourself with the `vector vrl` subcommand.

Debug functions

assert

Asserts the condition, which must be a Boolean expression. The program is aborted with the message if the condition evaluates to false.

Spec
```
assert(condition: <boolean>, message: <string>) :: <null>, <error>
```
- required
  condition - The condition to check.
- required
  message - The failure message that's reported if condition evalues to false.
- return - a <null>
Notices
This function has special behavior you should be aware of.
- The assert function should be used in a standalone fashion and only when you want to abort the program. You should avoid it in logical expressions and other situations in which you want the program to continue if the condition evalues to false.
Errors
This function is fallible, error handling is required.
- condition evaluates to false
Examples
Assertion (true)
```
ok, err = assert("foo" == "foo", message: "Foo must be foo!")
```
```
true
```
Try it yourself with the `vector vrl` subcommand.

log

Logs the value to Vector's stdout at the specified level.

Spec
```
log(value: <any>, [level: <string>], [rate_limit_secs: <integer>]) :: <null>
```
- required
  value - The value to log.
- optional
  level - The log level. Must be one of the following values:
  - trace - Log at the trace level.
  - debug - Log at the debug level.
  - info - Log at the info level.
  - warn - Log at the warn level.
  - error - Log at the error level.
- optional
  rate_limit_secs - Specifies that the log message is output no more than once per the given number of seconds. Use a value of 0 to turn rate limiting off.
- return - a <null>
Examples
Log a message
```
log("Hello, World!", level: "info", rate_limit_secs: 60)
```
```
null
```
Try it yourself with the `vector vrl` subcommand.

Enumerate functions

compact

Compacts the value by removing "empty" values, where emptiness is defined using the available parameters.

Spec
```
compact(value: <array | object>, [recursive: <boolean>], [null: <boolean>], [string: <boolean>], [object: <boolean>], [array: <boolean>], [nullish: <boolean>]) :: <array | object>
```
- required
  value - The object or array to compact.
- optional
  recursive - Whether the compaction be recursive.
- optional
  null - Whether null should be treated as an empty value.
- optional
  string - Whether an empty string should be treated as an empty value.
- optional
  object - Whether an empty object should be treated as an empty value.
- optional
  array - Whether an empty array should be treated as an empty value.
- optional
  nullish - Tests whether the value is "nullish" as defined by the is_nullish function.
- return - a <array | object>
  - The return type matches the value type.
Examples
Compact an array
```
compact(["foo", "bar", "", null, [], "buzz"], string: true, array: true, null: true)
```
```
[
  "foo",
  "bar",
  "buzz"
]
```
Try it yourself with the `vector vrl` subcommand.

flatten

Flattens the value into a single-level representation.

Spec
```
flatten(value: <array | object>) :: <array | object>
```
- required
  value - The array or object to flatten.
- return - a <array | object>
  - The return type matches the value type.
Examples
Flatten array
```
flatten([1, [2, 3, 4], [5, [6, 7], 8], 9])
```
```
[
  1,
  2,
  3,
  4,
  5,
  6,
  7,
  8,
  9
]
```
Try it yourself with the `vector vrl` subcommand.

includes

Determines whether the value array includes the specified item.

Spec
```
includes(value: <array>, item: <any>) :: <boolean>
```
- required
  value - The array.
- required
  item - The item to check.
- return - a <boolean>
Examples
```
includes(["apple", "orange", "banana"], "banana")
```
```
true
```
Try it yourself with the `vector vrl` subcommand.

length

Returns the length of the value.

Spec
```
length(value: <array | object | string>) :: <integer>
```
- required
  value - The array or object
- return - a <integer>
  - Returns the size of the array if value is an array.
  - Returns the size of the string if value is a string.
  - Returns the number of map keys if value is a map (nested keys are ignored)
Examples
Length (object)
```
length({
    "portland": "Trail Blazers",
    "seattle":  "Supersonics"
})
```
```
2
```
Try it yourself with the `vector vrl` subcommand.

Event functions

del

Removes the field specified by the path from the current event object.

Spec
```
del(path: <string>) :: <any>
```
- required
  path - The path of the field to delete.
- return - a <any>
  - Returns the value of the field being deleted. Returns null if the field doesn't exist.
Notices
This function has special behavior you should be aware of.
- The del function modifies the current event in place and returns the value of the deleted field.
Examples
Delete a field
Vector event (before)
```
{
  "field1": 1,
  "field2": 2
}
```
VRL program
```
del(.field1)
```
Vector event (after)
```
{
  "field2": 2
}
```

exists

Checks whether the path exists for the current event.

Spec
```
exists(path: <path>) :: <boolean>
```
- required
  path - The path of the field to check.
- return - a <boolean>
Examples
Exists (field)
Vector event
```
{
  "field": 1
}
```
VRL program
```
exists(.field)
```
```
true
```
Try it yourself with the `vector vrl` subcommand.

Hash functions

md5

Calculates an md5 hash of the value.

Spec
```
md5(value: <string>) :: <string>
```
- required
  value - The string to calculate the hash for.
- return - a <string>
Examples
```
md5("foo")
```
```
"acbd18db4cc2f85cedef654fccc4a4d8"
```
Try it yourself with the `vector vrl` subcommand.

sha1

Calculates a SHA-1 hash of the value.

Spec
```
sha1(value: <string>) :: <string>
```
- required
  value - The string to calculate the hash for.
- return - a <string>
Examples
```
sha1("foo")
```
```
"0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33"
```
Try it yourself with the `vector vrl` subcommand.

sha2

Calculates a SHA-2 hash of the value.

Spec
```
sha2(value: <string>, [variant: <string>]) :: <string>
```
- required
  value - The string to calculate the hash for.
- optional
  variant - The variant of the algorithm to use. Must be one of the following values:
  - SHA-224 - SHA-224 algorithm
  - SHA-256 - SHA-256 algorithm
  - SHA-384 - SHA-384 algorithm
  - SHA-512 - SHA-512 algorithm
  - SHA-512/224 - SHA-512/224 algorithm
  - SHA-512/256 - SHA-512/256 algorithm
- return - a <string>

Examples

sha2("foo", variant: "SHA-512/224")

"d68f258d37d670cfc1ec1001a0394784233f88f056994f9a7e5e99be"

Try it yourself with the `vector vrl` subcommand.

sha3

Calculates a SHA-3 hash of the value.

Spec
```
sha3(value: <string>, [variant: <string>]) :: <string>
```
- required
  value - The string to calculate the hash for.
- optional
  variant - The variant of the algorithm to use. Must be one of the following values:
  - SHA3-224 - SHA3-224 algorithm
  - SHA3-256 - SHA3-256 algorithm
  - SHA3-384 - SHA3-384 algorithm
  - SHA3-512 - SHA3-512 algorithm
- return - a <string>

Examples

sha3("foo", variant: "SHA3-224")

"f4f6779e153c391bbd29c95e72b0708e39d9166c7cea51d1f10ef58a"

Try it yourself with the `vector vrl` subcommand.

IP functions

ip_cidr_contains

Determines whether the ip is contained in the block referenced by the cidr.

Spec
```
ip_cidr_contains(cidr: <string>, ip: <string>) :: <boolean>, <error>
```
- required
  cidr - The CIDR mask (v4 or v6).
- required
  ip - The IP address (v4 or v6).
- return - a <boolean>
Errors
This function is fallible, error handling is required.
- cidr isn't a valid CIDR
- ip isn't a valid IP address
Examples
IPv4 contains CIDR
```
ip_cidr_contains!("192.168.0.0/16", "192.168.10.32")
```
```
true
```
Try it yourself with the `vector vrl` subcommand.

ip_subnet

Extracts the subnet address from the ip using the supplied subnet.

Spec
```
ip_subnet(ip: <string>, subnet: <string>) :: <string>, <error>
```
- required
  ip - The IP address (v4 or v6).
- required
  subnet - The subnet to extract from the IP address. This can be either a prefix length like /8 or a net mask like 255.255.0.0. The net mask can be either an IPv4 or IPv6 address.
- return - a <string>
Notices
This function has special behavior you should be aware of.
- Works with both IPv4 and IPv6 addresses. The IP version for the mask must be the same as the supplied address.
Errors
This function is fallible, error handling is required.
- ip isn't a valid IP address
- subnet isn't a valid subnet.
Examples
IPv4 subnet
```
ip_subnet!("192.168.10.32", "255.255.255.0")
```
```
"192.168.10.0"
```
Try it yourself with the `vector vrl` subcommand.

ip_to_ipv6

Converts the ip to an IPv6 address.

Spec
```
ip_to_ipv6(ip: <string>) :: <string>, <error>
```
- required
  ip - The IP address to convert to IPv6.
- return - a <string>
  - The ip is returned unchanged if it's already an IPv6 address.
  - The ip is converted to an IPv6 address if it's an IPv4 address.
Errors
This function is fallible, error handling is required.
- ip isn't a valid IP address
Examples
```
ip_to_ipv6!("192.168.10.32")
```
```
"::ffff:192.168.10.32"
```
Try it yourself with the `vector vrl` subcommand.

ipv6_to_ipv4

Converts the ip to an IPv4 address. ip is returned unchanged if it's already an IPv4 address. If ip is currently an IPv6 address then it needs to be IPv4 compatible, otherwise an error is thrown.

Spec
```
ipv6_to_ipv4(ip: <string>) :: <string>, <error>
```
- required
  ip - The IPv4-mapped IPv6 address to convert.
- return - a <string>
  - The ip is returned unchanged if it's already an IPv4 address. If it's an IPv6 address it must be IPv4 compatible, otherwise an error is thrown.
Errors
This function is fallible, error handling is required.
- ip isn't a valid IP address
- ip is an IPv6 address that isn't compatible with IPv4
Examples
```
ipv6_to_ipv4!("::ffff:192.168.0.1")
```
```
"192.168.0.1"
```
Try it yourself with the `vector vrl` subcommand.

Number functions

ceil

Rounds the value up to the specified precision.

Spec
```
ceil(value: <integer | float>, [precision: <integer>]) :: <integer | float>
```
- required
  value - The number to round up.
- optional
  precision - The number of decimal places to round to.
- return - a <integer | float>
  - Returns an integer if precision is 0 (this is the default). Returns a float otherwise.
Examples
Round a number up (without precision)
```
ceil(4.345)
```
```
5.0
```
Try it yourself with the `vector vrl` subcommand.

floor

Rounds the value down to the specified precision.

Spec
```
floor(value: <integer | float>, [precision: <integer>]) :: <integer | float>
```
- required
  value - The number to round down.
- optional
  precision - The number of decimal places to round to.
- return - a <integer | float>
  - Returns an integer if precision is 0 (this is the default). Returns a float otherwise.
Examples
Round a number down (without precision)
```
floor(4.345)
```
```
4.0
```
Try it yourself with the `vector vrl` subcommand.

format_number

Formats the value into a string representation of the number.

Spec
```
format_number(value: <integer | float>, [scale: <integer>], [decimal_separator: <string>], [grouping_separator: <string>]) :: <string>
```
- required
  value - The number to format as a string.
- optional
  scale - The number of decimal places to display.
- optional
  decimal_separator - The character to use between the whole and decimal parts of the number.
- optional
  grouping_separator - The character to use between each thousands part of the number.
- return - a <string>

Examples

format_number(1234567.89, 3, decimal_separator: ".", grouping_separator: ",")

"1,234,567.890"

Try it yourself with the `vector vrl` subcommand.

round

Rounds the value to the specified precision.

Spec
```
round(value: <integer | float>, [precision: <integer>]) :: <integer | float>
```
- required
  value - The number to round.
- optional
  precision - The number of decimal places to round to.
- return - a <integer | float>
  - If precision is 0, then an integer is returned, otherwise a float is returned.
Examples
Round a number (without precision)
```
round(4.345)
```
```
4.0
```
Try it yourself with the `vector vrl` subcommand.

Object functions

merge

Merges the from object into the to object.

Spec
```
merge(to: <string>, from: <object>, [deep: <boolean>]) :: <object>
```
- required
  to - The object to merge into.
- required
  from - The object to merge from.
- optional
  deep - A deep merge is performed if true, otherwise only top-level fields are merged.
- return - a <object>
  - The field from the from object is chosen if a key exists in both objects.
  - Objects are merged recursively if deep is specified, a key exists in both objects, and both of those fields are also objects.
Examples
Object merge (shallow)
```
merge(
    {
        "parent1": {
            "child1": 1,
            "child2": 2
        },
        "parent2": {
            "child3": 3
        }
    },
    {
        "parent1": {
            "child2": 4,
            "child5": 5
        }
    }
)
```
```
{
  "parent1": {
    "child2": 4,
    "child5": 5
  },
  "parent2": {
    "child3": 3
  }
}
```
Try it yourself with the `vector vrl` subcommand.

Parse functions

parse_apache_log

Parses Apache access and error log lines. Lines can be in common, combined, or default error format.

Spec
```
parse_apache_log(value: <string>, [timestamp_format: <string>], format: <string>) :: <object>, <error>
```
- required
  value - The string to parse.
- optional
  timestamp_format - The date/time format to use for encoding the timestamp. The time is parsed in local time if the timestamp doesn't specify a timezone.
- required
  format - The format to use for parsing the log. Must be one of the following values:
  - common - Common format
  - combined - Apache combined format
  - error - Default Apache error format
- return - a <object>
Notices
This function has special behavior you should be aware of.
- Missing information in the log message may be indicated by -. These fields are omitted in the result.
Errors
This function is fallible, error handling is required.
- value doesn't match the specified format
- timestamp_format isn't a valid format string
- The timestamp in value fails to parse using the provided timestamp_format
Examples
Parse via Apache log format (common)
```
parse_apache_log!("127.0.0.1 bob frank [10/Oct/2000:13:55:36 -0700] \"GET /apache_pb.gif HTTP/1.0\" 200 2326", format: "common")
```
```
{
  "host": "127.0.0.1",
  "identity": "bob",
  "user": "frank",
  "timestamp": "2000-10-10T20:55:36Z",
  "message": "GET /apache_pb.gif HTTP/1.0",
  "method": "GET",
  "path": "/apache_pb.gif",
  "protocol": "HTTP/1.0",
  "status": 200,
  "size": 2326
}
```
Try it yourself with the `vector vrl` subcommand.

parse_aws_alb_log

Parses value in the Elastic Load Balancer Access format.

Spec
```
parse_aws_alb_log(value: <string>) :: <object>, <error>
```
- required
  value - Access log of the Application Load Balancer.
- return - a <object>
Errors
This function is fallible, error handling is required.
- value isn't a properly formatted AWS ALB log

Examples

parse_aws_alb_log!(
    "http 2018-11-30T22:23:00.186641Z app/my-loadbalancer/50dc6c495c0c9188 192.168.131.39:2817 - 0.000 0.001 0.000 200 200 34 366 \"GET http://www.example.com:80/ HTTP/1.1\" \"curl/7.46.0\" - - arn:aws:elasticloadbalancing:us-east-2:123456789012:targetgroup/my-targets/73e2d6bc24d8a067 \"Root=1-58337364-23a8c76965a2ef7629b185e3\" \"-\" \"-\" 0 2018-11-30T22:22:48.364000Z \"forward\" \"-\" \"-\" \"-\" \"-\" \"-\" \"-\""
)

{
  "type": "http",
  "timestamp": "2018-11-30T22:23:00.186641Z",
  "elb": "app/my-loadbalancer/50dc6c495c0c9188",
  "client_host": "192.168.131.39:2817",
  "target_host": null,
  "request_processing_time": 0.0,
  "target_processing_time": 0.001,
  "response_processing_time": 0.0,
  "elb_status_code": "200",
  "target_status_code": "200",
  "received_bytes": 34,
  "sent_bytes": 366,
  "request_method": "GET",
  "request_url": "http://www.example.com:80/",
  "request_protocol": "HTTP/1.1",
  "user_agent": "curl/7.46.0",
  "ssl_cipher": null,
  "ssl_protocol": null,
  "target_group_arn": "arn:aws:elasticloadbalancing:us-east-2:123456789012:targetgroup/my-targets/73e2d6bc24d8a067",
  "trace_id": "Root=1-58337364-23a8c76965a2ef7629b185e3",
  "domain_name": null,
  "chosen_cert_arn": null,
  "matched_rule_priority": "0",
  "request_creation_time": "2018-11-30T22:22:48.364000Z",
  "actions_executed": "forward",
  "redirect_url": null,
  "error_reason": null,
  "target_port_list": [

  ],
  "target_status_code_list": [

  ],
  "classification": null,
  "classification_reason": null
}

Try it yourself with the `vector vrl` subcommand.

parse_aws_cloudwatch_log_subscription_message

Parses AWS CloudWatch Logs events (configured through AWS Cloudwatch subscriptions) from the aws_kinesis_firehose source.

Spec
```
parse_aws_cloudwatch_log_subscription_message(value: <string>) :: <object>, <error>
```
- required
  value - The string representation of the message to parse.
- return - a <object>
Errors
This function is fallible, error handling is required.
- value isn't a properly formatted AWS Cloudwatch Log subscription message

Examples

Vector event

{
  "message": "{\n  \"messageType\": \"DATA_MESSAGE\",\n  \"owner\": \"111111111111\",\n  \"logGroup\": \"test\",\n  \"logStream\": \"test\",\n  \"subscriptionFilters\": [\n\t\"Destination\"\n  ],\n  \"logEvents\": [\n\t{\n\t  \"id\": \"35683658089614582423604394983260738922885519999578275840\",\n\t  \"timestamp\": 1600110569039,\n\t  \"message\": \"{\\\"bytes\\\":26780,\\\"datetime\\\":\\\"14/Sep/2020:11:45:41 -0400\\\",\\\"host\\\":\\\"157.130.216.193\\\",\\\"method\\\":\\\"PUT\\\",\\\"protocol\\\":\\\"HTTP/1.0\\\",\\\"referer\\\":\\\"https://www.principalcross-platform.io/markets/ubiquitous\\\",\\\"request\\\":\\\"/expedite/convergence\\\",\\\"source_type\\\":\\\"stdin\\\",\\\"status\\\":301,\\\"user-identifier\\\":\\\"-\\\"}\"\n\t}\n  ]\n}"
}

VRL program

parse_aws_cloudwatch_log_subscription_message!(.message)

{
  "owner": "111111111111",
  "message_type": "DATA_MESSAGE",
  "log_group": "test",
  "log_stream": "test",
  "subscription_filters": [
    "Destination"
  ],
  "log_events": [
    {
      "id": "35683658089614582423604394983260738922885519999578275840",
      "message": "{\"bytes\":26780,\"datetime\":\"14/Sep/2020:11:45:41 -0400\",\"host\":\"157.130.216.193\",\"method\":\"PUT\",\"protocol\":\"HTTP/1.0\",\"referer\":\"https://www.principalcross-platform.io/markets/ubiquitous\",\"request\":\"/expedite/convergence\",\"source_type\":\"stdin\",\"status\":301,\"user-identifier\":\"-\"}",
      "timestamp": "2020-09-14T19:09:29.039Z"
    }
  ]
}

Try it yourself with the `vector vrl` subcommand.

parse_aws_vpc_flow_log

Parses value in the VPC Flow Logs format.

Spec
```
parse_aws_vpc_flow_log(value: <string>, [format: <string>]) :: <object>, <error>
```
- required
  value - VPC Flow Log.
- optional
  format - VPC Flow Log format.
- return - a <object>
Errors
This function is fallible, error handling is required.
- value isn't a properly formatted AWS VPC Flow log
Examples
Parse AWS VPC Flow log (default format)
```
parse_aws_vpc_flow_log!("2 123456789010 eni-1235b8ca123456789 - - - - - - - 1431280876 1431280934 - NODATA")
```
```
{
  "version": 2,
  "account_id": 123456789010,
  "interface_id": "eni-1235b8ca123456789",
  "srcaddr": null,
  "dstaddr": null,
  "srcport": null,
  "dstport": null,
  "protocol": null,
  "packets": null,
  "bytes": null,
  "start": 1431280876,
  "end": 1431280934,
  "action": null,
  "log_status": "NODATA"
}
```
Try it yourself with the `vector vrl` subcommand.

parse_common_log

Parses the value using the Common Log Format (CLF).

Spec
```
parse_common_log(value: <string>, [timestamp_format: <string>]) :: <object>, <error>
```
- required
  value - The string to parse.
- optional
  timestamp_format - The date/time format to use for encoding the timestamp.
- return - a <object>
Notices
This function has special behavior you should be aware of.
- Missing information in the log message may be indicated by -. These fields are omitted in the result.
Errors
This function is fallible, error handling is required.
- value doesn't match the Common Log Format
- timestamp_format isn't a valid format string
- The timestamp in value fails to parse using the provided timestamp_format
Examples
Parse via Common Log Format (with default timestamp format)
```
parse_common_log!("127.0.0.1 bob frank [10/Oct/2000:13:55:36 -0700] \"GET /apache_pb.gif HTTP/1.0\" 200 2326")
```
```
{
  "host": "127.0.0.1",
  "identity": "bob",
  "user": "frank",
  "timestamp": "2000-10-10T20:55:36Z",
  "message": "GET /apache_pb.gif HTTP/1.0",
  "method": "GET",
  "path": "/apache_pb.gif",
  "protocol": "HTTP/1.0",
  "status": 200,
  "size": 2326
}
```
Try it yourself with the `vector vrl` subcommand.

parse_csv

Parses a single CSV formatted row. Only the first row is parsed in case of multiline input value.

Spec
```
parse_csv(value: <string>, [delimiter: <string>]) :: <array>, <error>
```
- required
  value - The string to parse.
- optional
  delimiter - The field delimiter to use when parsing. Must be a single-byte utf8 character.
- return - a <array>
Notices
This function has special behavior you should be aware of.
- All values are returned as strings. We recommend manually coercing values to desired types as you see fit.
Errors
This function is fallible, error handling is required.
- delimiter must be a single-byte utf8 character
- value isn't a valid CSV string
Examples
Parse a single CSV formatted row
```
parse_csv!("foo,bar,\"foo \"\", bar\"")
```
```
[
  "foo",
  "bar",
  "foo \", bar"
]
```
Try it yourself with the `vector vrl` subcommand.

parse_duration

Parses the value into a human-readable duration format specified by unit.

Spec
```
parse_duration(value: <string>, unit: <string>) :: <float>, <error>
```
- required
  value - The string of the duration.
- required
  unit - The output units for the duration. Must be one of the following values:
  - ns - Nanoseconds (1 billion nanoseconds in a second)
  - us - Microseconds (1 million microseconds in a second)
  - µs - Microseconds (1 million microseconds in a second)
  - ms - Milliseconds (1 thousand microseconds in a second)
  - cs - Centiseconds (100 centiseconds in a second)
  - ds - Deciseconds (10 deciseconds in a second)
  - s - Seconds
  - m - Minutes (60 seconds in a minute)
  - h - Hours (60 minutes in an hour)
  - d - Days (24 hours in a day)
- return - a <float>
Errors
This function is fallible, error handling is required.
- value isn't a properly formatted duration
Examples
```
parse_duration!("1005ms", unit: "s")
```
```
1.005
```
Try it yourself with the `vector vrl` subcommand.

parse_glog

Parses the value using the glog (Google Logging Library) format.

Spec
```
parse_glog(value: <string>) :: <object>, <error>
```
- required
  value - The string to parse.
- return - a <object>
Errors
This function is fallible, error handling is required.
- value doesn't match the glog format

Examples

parse_glog!("I20210131 14:48:54.411655 15520 main.c++:9] Hello world!")

{
  "level": "info",
  "timestamp": "2021-01-31T14:48:54.411655Z",
  "id": 15520,
  "file": "main.c++",
  "line": 9,
  "message": "Hello world!"
}

Try it yourself with the `vector vrl` subcommand.

parse_grok

Parses the value using the grok format. All patterns listed here are supported.

Spec
```
parse_grok(value: <string>, pattern: <string>, [remove_empty: <boolean>]) :: <object>, <error>
```
- required
  value - The string to parse.
- required
  pattern - The Grok pattern.
- optional
  remove_empty - If set to true, any patterns that resolve to an empty value are removed from the result.
- return - a <object>
Notices
This function has special behavior you should be aware of.
- We recommend using community-maintained Grok patterns when possible, as they're more likely to be properly vetted and improved over time than bespoke patterns.
Errors
This function is fallible, error handling is required.
- value fails to parse using the provided pattern

Examples

parse_grok!(
    "2020-10-02T23:22:12.223222Z info Hello world",
    "%{TIMESTAMP_ISO8601:timestamp} %{LOGLEVEL:level} %{GREEDYDATA:message}"
)

{
  "timestamp": "2020-10-02T23:22:12.223222Z",
  "level": "info",
  "message": "Hello world"
}

Try it yourself with the `vector vrl` subcommand.

parse_json

Parses the value as JSON.

Spec
```
parse_json(value: <string>) :: <boolean | integer | float | string | object | array | null>, <error>
```
- required
  value - The string representation of the JSON to parse.
- return - a <boolean | integer | float | string | object | array | null>
Notices
This function has special behavior you should be aware of.
- Only JSON types are returned. If you need to convert a string into a timestamp, consider the parse_timestamp function.
Errors
This function is fallible, error handling is required.
- value isn't a valid JSON-formatted payload
Examples
```
parse_json!("{\"key\": \"val\"}")
```
```
{
  "key": "val"
}
```
Try it yourself with the `vector vrl` subcommand.

parse_key_value

Parses the value in key/value format. Also known as logfmt).

Keys and values can be wrapped with ".
" characters can be escaped using \.

Spec
```
parse_key_value(value: <string>, [key_value_delimiter: <string>], [field_delimiter: <string>]) :: <object>, <error>
```
- required
  value - The string to parse.
- optional
  key_value_delimiter - The string that separates the key from the value.
- optional
  field_delimiter - The string that separates each key/value pair.
- return - a <object>
Notices
This function has special behavior you should be aware of.
- All values are returned as strings. We recommend manually coercing values to desired types as you see fit.
Errors
This function is fallible, error handling is required.
- value isn't a properly formatted key/value string
Examples
Parse logfmt log
```
parse_key_value!(
    "@timestamp=\"Sun Jan 10 16:47:39 EST 2021\" level=info msg=\"Stopping all fetchers\" tag#production=stopping_fetchers id=ConsumerFetcherManager-1382721708341 module=kafka.consumer.ConsumerFetcherManager"
)
```
```
{
  "@timestamp": "Sun Jan 10 16:47:39 EST 2021",
  "level": "info",
  "msg": "Stopping all fetchers",
  "tag#production": "stopping_fetchers",
  "id": "ConsumerFetcherManager-1382721708341",
  "module": "kafka.consumer.ConsumerFetcherManager"
}
```
Try it yourself with the `vector vrl` subcommand.

parse_linux_authorization

Parses Linux authorization logs usually found under either /var/log/auth.log (for Debian based systems) or under /var/log/secure (for RedHat based system). according to Syslog format.

Spec
```
parse_linux_authorization(value: <string>) :: <object>, <error>
```
- required
  value - The text containing the message to parse.
- return - a <object>
Notices
This function has special behavior you should be aware of.
- The function resolves the year for messages that don't include it. If the current month is January, and the message is for December, it will take the previous year. Otherwise, take the current year.
Errors
This function is fallible, error handling is required.
- value isn't a properly formatted Syslog message

Examples

parse_linux_authorization!(
    s'Mar 23 01:49:58 localhost sshd[1111]: Accepted publickey for eng from 10.1.1.1 port 8888 ssh2: RSA SHA256:foobar'
)

{
  "appname": "sshd",
  "hostname": "localhost",
  "message": "Accepted publickey for eng from 10.1.1.1 port 8888 ssh2: RSA SHA256:foobar",
  "procid": 1111,
  "timestamp": "2021-03-23T01:49:58Z"
}

Try it yourself with the `vector vrl` subcommand.

parse_logfmt

Parses the value in logfmt.

Keys and values can be wrapped with ".
" characters can be escaped by \.

Spec
```
parse_logfmt(value: <string>) :: <object>, <error>
```
- required
  value - The string to parse.
- return - a <object>
Notices
This function has special behavior you should be aware of.
- All values are returned as strings, it is recommended to manually coerce values as you see fit.
Errors
This function is fallible, error handling is required.
- value is not a properly formatted key/value string

Examples

parse_logfmt!(
    "@timestamp=\"Sun Jan 10 16:47:39 EST 2021\" level=info msg=\"Stopping all fetchers\" tag#production=stopping_fetchers id=ConsumerFetcherManager-1382721708341 module=kafka.consumer.ConsumerFetcherManager"
)

{
  "@timestamp": "Sun Jan 10 16:47:39 EST 2021",
  "level": "info",
  "msg": "Stopping all fetchers",
  "tag#production": "stopping_fetchers",
  "id": "ConsumerFetcherManager-1382721708341",
  "module": "kafka.consumer.ConsumerFetcherManager"
}

Try it yourself with the `vector vrl` subcommand.

parse_nginx_log

Parses Nginx access and error log lines. Lines can be in combined, or error format.

Spec
```
parse_nginx_log(value: <string>, [timestamp_format: <string>], format: <string>) :: <object>, <error>
```
- required
  value - The string to parse.
- optional
  timestamp_format - The date/time format to use for encoding the timestamp. The time is parsed in local time if the timestamp doesn't specify a timezone. The default %d/%b/%Y:%T %z format for the combined logs and %Y/%m/%d %H:%M:%S for the error logs.
- required
  format - The format to use for parsing the log. Must be one of the following values:
  - combined - Nginx combined format
  - error - Default Nginx error format
- return - a <object>
Notices
This function has special behavior you should be aware of.
- Missing information in the log message may be indicated by -. These fields are omitted in the result.
Errors
This function is fallible, error handling is required.
- value doesn't match the specified format
- timestamp_format isn't a valid format string
- The timestamp in value fails to parse using the provided timestamp_format
Examples
Parse via Nginx log format (combined)
```
parse_nginx_log!(
    s'172.17.0.1 alice - [01/Apr/2021:12:02:31 +0000] "POST /not-found HTTP/1.1" 404 153 "http://localhost/somewhere" "Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36" "2.75"',
    "combined",
)
```
```
{
  "client": "172.17.0.1",
  "user": "alice",
  "timestamp": "2021-04-01T12:02:31Z",
  "request": "POST /not-found HTTP/1.1",
  "method": "POST",
  "path": "/not-found",
  "protocol": "HTTP/1.1",
  "status": 404,
  "size": 153,
  "referer": "http://localhost/somewhere",
  "agent": "Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
  "compression": "2.75"
}
```
Try it yourself with the `vector vrl` subcommand.

parse_query_string

Parses the value as a query string.

Spec
```
parse_query_string(value: <string>) :: <object>
```
- required
  value - The string to parse.
- return - a <object>
Notices
This function has special behavior you should be aware of.
- All values are returned as strings. We recommend manually coercing values to desired types as you see fit. Empty keys and values are allowed.
Examples
Parse query string
```
parse_query_string("foo=%2B1&bar=2&bar=3&xyz")
```
```
{
  "foo": "+1",
  "bar": [
    "2",
    "3"
  ],
  "xyz": ""
}
```
Try it yourself with the `vector vrl` subcommand.

parse_regex

Parses the value via the provided Regex pattern.

This function differs from the parse_regex_all function in that it returns only the first match.

Spec
```
parse_regex(value: <string>, pattern: <regex>, [numeric_groups: <regex>]) :: <object>, <error>
```
- required
  value - The string to search.
- required
  pattern - The regular expression pattern to search against.
- optional
  numeric_groups - If true, the index of each group in the regular expression is also captured. The 0th index will contain the whole match.
- return - a <object>
  - Matches return all capture groups corresponding to the leftmost matches in the text.
  - Raises an error if no match is found.
Notices
This function has special behavior you should be aware of.
- VRL aims to provide purpose-specific parsing functions for common log formats. Before reaching for the parse_regex function, see if a VRL parse_* function already exists for your format. If not, we recommend opening an issue to request support for the desired format.
- All values are returned as strings. We recommend manually coercing values to desired types as you see fit.
Errors
This function is fallible, error handling is required.
- value fails to parse using the provided pattern
Examples
Parse using Regex (with capture groups)
```
parse_regex!("first group and second group.", r'(?P<number>.*?) group')
```
```
{
  "number": "first"
}
```
Try it yourself with the `vector vrl` subcommand.

parse_regex_all

Parses the value via the provided Regex pattern.

This function differs from the parse_regex function in that it returns all matches, not just the first.

Spec
```
parse_regex_all(value: <string>, pattern: <regex>, [numeric_groups: <regex>]) :: <array>, <error>
```
- required
  value - The string to search.
- required
  pattern - The regular expression pattern to search against.
- optional
  numeric_groups - If true, the index of each group in the regular expression is also captured. The 0th index will contain the whole match.
- return - a <array>
  - Matches return all capture groups corresponding to the leftmost matches in the text.
  - Raises an error if no match is found.
Notices
This function has special behavior you should be aware of.
- VRL aims to provide purpose-specific parsing functions for common log formats. Before reaching for the parse_regex function, see if a VRL parse_* function already exists for your format. If not, we recommend opening an issue to request support for the desired format.
- All values are returned as strings. We recommend manually coercing values to desired types as you see fit.
Errors
This function is fallible, error handling is required.
- value fails to parse via the provided pattern

Examples

parse_regex_all!("first group and second group.", r'(?P<number>\w+) group', numeric_groups: true)

[
  {
    "number": "first",
    "0": "first group",
    "1": "first"
  },
  {
    "number": "second",
    "0": "second group",
    "1": "second"
  }
]

Try it yourself with the `vector vrl` subcommand.

parse_syslog

Parses the value in Syslog format.

Spec
```
parse_syslog(value: <string>) :: <object>, <error>
```
- required
  value - The text containing the Syslog message to parse.
- return - a <object>
Notices
This function has special behavior you should be aware of.
- The function makes a best effort to parse the various Syslog formats that exists out in the wild. This includes RFC 6587, RFC 5424, RFC 3164, and other common variations (such as the Nginx Syslog style).
- All values are returned as strings. We recommend manually coercing values to desired types as you see fit.
Errors
This function is fallible, error handling is required.
- value isn't a properly formatted Syslog message

Examples

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!'
)

{
  "severity": "notice",
  "facility": "user",
  "timestamp": "2020-03-13T20:45:38.119Z",
  "hostname": "dynamicwireless.name",
  "appname": "non",
  "procid": 2426,
  "msgid": "ID931",
  "message": "Try to override the THX port, maybe it will reboot the neural interface!",
  "exampleSDID@32473.eventID": "1011",
  "exampleSDID@32473.eventSource": "Application",
  "exampleSDID@32473.iut": "3",
  "version": 1
}

Try it yourself with the `vector vrl` subcommand.

parse_timestamp

Parses the value in strptime format.

Spec
```
parse_timestamp(value: <string>, format: <string>) :: <timestamp>, <error>
```
- required
  value - The text of the timestamp.
- required
  format - The strptime format.
- return - a <timestamp>
Errors
This function is fallible, error handling is required.
- value fails to parse using the provided format

Examples

parse_timestamp!("10-Oct-2020 16:00+00:00", format: "%v %R %:z")

"2020-10-10T16:00:00Z"

Try it yourself with the `vector vrl` subcommand.

parse_tokens

Parses the value in "token" format. A token is considered to be one of the following:

A word surrounded by whitespace.
Text delimited by double quotes: "..". Quotes can be included in the token if they are escaped by a backslash (\).
Text delimited by square brackets: [..]. Closing square brackets can be included in the token if they are escaped by a backslash (\).

Spec
```
parse_tokens(value: <string>) :: <array>, <error>
```
- required
  value - The string to tokenize.
- return - a <array>
Notices
This function has special behavior you should be aware of.
- All token values are returned as strings. We recommend manually coercing values to desired types as you see fit.
Errors
This function is fallible, error handling is required.
- value isn't a properly formatted tokenized string

Examples

parse_tokens(
    "A sentence \"with \\\"a\\\" sentence inside\" and [some brackets]"
)

[
  "A",
  "sentence",
  "with \\\"a\\\" sentence inside",
  "and",
  "some brackets"
]

Try it yourself with the `vector vrl` subcommand.

parse_url

Parses the value in URL format.

Spec
```
parse_url(value: <string>) :: <object>, <error>
```
- required
  value - The text of the URL.
- return - a <object>
Errors
This function is fallible, error handling is required.
- value isn't a properly formatted URL

Examples

parse_url!("ftp://foo:bar@vector.dev:4343/foobar?hello=world#123")

{
  "scheme": "ftp",
  "username": "foo",
  "password": "bar",
  "host": "vector.dev",
  "port": 4343,
  "path": "/foobar",
  "query": {
    "hello": "world"
  },
  "fragment": "123"
}

Try it yourself with the `vector vrl` subcommand.

Random functions

uuid_v4

Generates a random UUIDv4 string.

Spec
```
uuid_v4() :: <string>
```
- return - a <string>
Examples
```
uuid_v4()
```
```
"1d262f4f-199b-458d-879f-05fd0a5f0683"
```
Try it yourself with the `vector vrl` subcommand.

String functions

contains

Determines whether the value string contains the specified substring.

Spec
```
contains(value: <string>, substring: <string>, [case_sensitive: <boolean>]) :: <boolean>
```
- required
  value - The text to search.
- required
  substring - The substring to search for in value.
- optional
  case_sensitive - Whether the match should be case sensitive.
- return - a <boolean>
Examples
String contains (case sensitive)
```
contains("The Needle In The Haystack", "Needle")
```
```
true
```
Try it yourself with the `vector vrl` subcommand.

downcase

Downcases the value string, where "downcase" is defined according to the terms of the Unicode Derived Core Property Lowercase.

Spec
```
downcase(value: <string>) :: <string>
```
- required
  value - The string to convert to lowercase.
- return - a <string>
Examples
```
downcase("Hello, World!")
```
```
"hello, world!"
```
Try it yourself with the `vector vrl` subcommand.

ends_with

Determines whether the value string ends with the specified substring.

Spec
```
ends_with(value: <string>, substring: <string>, [case_sensitive: <boolean>]) :: <boolean>
```
- required
  value - The string to search.
- required
  substring - The substring with which value must end.
- optional
  case_sensitive - Whether the match should be case sensitive.
- return - a <boolean>
Examples
String ends with (case sensitive)
```
ends_with("The Needle In The Haystack", "The Haystack")
```
```
true
```
Try it yourself with the `vector vrl` subcommand.

join

Joins each string in the value array into a single string, with items optionally separated from one another by a separator.

Spec
```
join(value: <array>, [separator: <string>]) :: <string>
```
- required
  value - The array of strings to join together.
- optional
  separator - The string separating each original element when joined.
- return - a <string>
Examples
Join array (no separator)
```
join!(["bring", "us", "together"])
```
```
"bringustogether"
```
Try it yourself with the `vector vrl` subcommand.

match

Determines whether the value matches the pattern.

Spec
```
match(value: <string>, pattern: <regex>) :: <boolean>
```
- required
  value - The value to match.
- required
  pattern - The regular expression pattern to match against.
- return - a <boolean>
Examples
```
match("I'm a little teapot", r'teapot')
```
```
true
```
Try it yourself with the `vector vrl` subcommand.

replace

Replaces all matching instances of pattern in the value.

Spec
```
replace(value: <string>, pattern: <regex | string>, with: <string>, [count: <integer>]) :: <string>
```
- required
  value - The original string.
- required
  pattern - Replace all matches of this pattern. Can be a static string or a regular expression.
- required
  with - The string that the matches are replaced with.
- optional
  count - The maximum number of replacements to perform. -1 means replace all matches.
- return - a <string>
Examples
Replace literal text
```
replace("Apples and Bananas", "and", "not")
```
```
"Apples not Bananas"
```
Try it yourself with the `vector vrl` subcommand.

slice

Returns a slice of the value between the start and end positions.

If the start and end parameters are negative, they refer to positions counting from the right of the string or array. If end refers to a position that is greater than the length of the string or array a slice up to the end of the string or array is returned.

Spec
```
slice(value: <array | string>, start: <integer>, [end: <integer>]) :: <string>
```
- required
  value - The string or array to slice.
- required
  start - The inclusive start position. A zero-based index that can be negative.
- optional
  end - The inclusive end position. A zero-based index that can be negative.
- return - a <string>
Examples
Slice a string (positve index)
```
slice!("Supercalifragilisticexpialidocious", start: 5, end: 13)
```
```
"califrag"
```
Try it yourself with the `vector vrl` subcommand.

split

Splits the value string via the pattern.

Spec
```
split(value: <string>, pattern: <string | regex>, [limit: <integer>]) :: <string>
```
- required
  value - The string to split.
- required
  pattern - The string is split whenever this pattern is matched.
- optional
  limit - The maximum number of substrings to return.
- return - a <string>
  - If limit is specified, the remainder of the string is returned unsplit after limit has been reached.
Examples
Split a string (no limit)
```
split("apples and pears and bananas", " and ")
```
```
[
  "apples",
  "pears",
  "bananas"
]
```
Try it yourself with the `vector vrl` subcommand.

starts_with

Determines whether the value begins with the substring.

Spec
```
starts_with(value: <string>, substring: <string>, [case_sensitive: <boolean>]) :: <boolean>
```
- required
  value - The string to search.
- required
  substring - The substring that the value must start with.
- optional
  case_sensitive - Whether the match should be case sensitive.
- return - a <boolean>
Examples
String starts with (case sensitive)
```
starts_with("The Needle In The Haystack", "The Needle")
```
```
true
```
Try it yourself with the `vector vrl` subcommand.

strip_ansi_escape_codes

Strips ANSI escape codes from the value.

Spec
```
strip_ansi_escape_codes(value: <string>) :: <string>
```
- required
  value - The string to strip.
- return - a <string>
Examples
```
strip_ansi_escape_codes("\e[46mfoo\e[0m bar")
```
```
"foo bar"
```
Try it yourself with the `vector vrl` subcommand.

strip_whitespace

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

Spec
```
strip_whitespace(value: <string>) :: <string>
```
- required
  value - The string to trim.
- return - a <string>
Examples
```
strip_whitespace("  A sentence.  ")
```
```
"A sentence."
```
Try it yourself with the `vector vrl` subcommand.

truncate

Truncates the value string up to the limit number of characters.

Spec
```
truncate(value: <string>, limit: <integer | float>, ellipsis: <boolean>) :: <string>
```
- required
  value - The string to truncate.
- required
  limit - The number of characters to truncate the string after.
- required
  ellipsis - An ellipsis (...) is appended if this is set to true and the value string ends up being truncated because it's exceeded the limit.
- return - a <string>
  - The string is returned unchanged its length is less than limit.
  - If ellipsis is true, then an ellipsis (...) is appended to the string (beyond the specified limit).

Examples

truncate("A rather long sentence.", limit: 11, ellipsis: true)

"A rather lo..."

Try it yourself with the `vector vrl` subcommand.

upcase

Upcases the value, where "upcase" is defined according to the terms of the Unicode Derived Core Property Uppercase.

Spec
```
upcase(value: <string>) :: <string>
```
- required
  value - The string to convert to uppercase.
- return - a <string>
Examples
```
upcase("Hello, World!")
```
```
"HELLO, WORLD!"
```
Try it yourself with the `vector vrl` subcommand.

System functions

get_env_var

Returns the value of the environment variable specifed by name.

Spec
```
get_env_var(name: <string>) :: <string>, <error>
```
- required
  name - The name of the environment variable.
- return - a <string>
Errors
This function is fallible, error handling is required.
- Environment variable name doesn't exist
- Value of environment variable name isn't valid Unicode
Examples
```
get_env_var!("HOME")
```
```
"/root"
```
Try it yourself with the `vector vrl` subcommand.

get_hostname

Returns the local system's hostname.

Spec
```
get_hostname() :: <string>, <error>
```
- return - a <string>
Errors
This function is fallible, error handling is required.
- Internal hostname resolution failed.

Examples

Vector event (before)

{
}

VRL program

.hostname = get_hostname!()

Vector event (after)

{
  "hostname": "localhost.localdomain"
}

Timestamp functions

format_timestamp

Formats the value into a string representation of the timestamp.

Spec
```
format_timestamp(value: <timestamp>, format: <string>) :: <string>
```
- required
  value - The timestamp to format as text.
- required
  format - The format string as decribed by the Chrono library.
- return - a <string>
Examples
Format a timestamp (ISO8601/RFC 3339)
```
format_timestamp!(t'2020-10-21T16:00:00Z', format: "%+")
```
```
"2020-10-21T16:00:00+00:00"
```
Try it yourself with the `vector vrl` subcommand.

now

Returns the current timestamp in the UTC timezone with nanosecond precision.

Spec
```
now() :: <timestamp>
```
- return - a <timestamp>
Examples
```
now()
```
```
"2021-03-04T10:51:15.928937Z"
```
Try it yourself with the `vector vrl` subcommand.

Type functions

array

Returns the value if it's an array and errors otherwise. This enables the type checker to guarantee that the returned value is an array and can be used in any function that expects one.

Spec
```
array(value: <any>) :: <array>, <error>
```
- required
  value - The value that you need to ensure is an array.
- return - a <array>
  - Returns the value if it's an array.
  - Raises an error if not an array.
Errors
This function is fallible, error handling is required.
- value isn't an array.
Examples
Vector event
```
{
  "value": [
    1,
    2,
    3
  ]
}
```
VRL program
```
array!(.value)
```
```
[
  1,
  2,
  3
]
```
Try it yourself with the `vector vrl` subcommand.

bool

Returns the value if it's a Boolean and errors otherwise. This enables the type checker to guarantee that the returned value is a Boolean and can be used in any function that expects one.

Spec
```
bool(value: <any>) :: <boolean>, <error>
```
- required
  value - The value that you need to ensure is a Boolean.
- return - a <boolean>
  - Returns value if it's a Boolean.
  - Raises an error if not a Boolean.
Errors
This function is fallible, error handling is required.
- value isn't a Boolean.
Examples
Vector event
```
{
  "value": false
}
```
VRL program
```
bool!(.value)
```
```
false
```
Try it yourself with the `vector vrl` subcommand.

float

Returns the value if it's a float and errors otherwise. This enables the type checker to guarantee that the returned value is a float and can be used in any function that expects one.

Spec
```
float(value: <any>) :: <float>, <error>
```
- required
  value - The value that you need to ensure is a float.
- return - a <float>
  - Returns the value if it's a float.
  - Raises an error if not a float.
Errors
This function is fallible, error handling is required.
- value isn't a float.
Examples
Vector event
```
{
  "value": 42.0
}
```
VRL program
```
float!(.value)
```
```
42.0
```
Try it yourself with the `vector vrl` subcommand.

int

Returns the value if it's an integer and errors otherwise. This enables the type checker to guarantee that the returned value is an integer and can be used in any function that expects one.

Spec
```
int(value: <any>) :: <integer>, <error>
```
- required
  value - The value that you need to ensure is an integer.
- return - a <integer>
  - Returns the value if it's an integer.
  - Raises an error if not an integer.
Errors
This function is fallible, error handling is required.
- value is not an integer.
Examples
Vector event
```
{
  "value": 42
}
```
VRL program
```
int!(.value)
```
```
42
```
Try it yourself with the `vector vrl` subcommand.

is_array

Check if the type of a value is an array or not.

Spec
```
is_array(value: <any>) :: <boolean>
```
- required
  value - The value to check
- return - a <boolean>
  - Returns true if value is an array.
  - Returns false if value is anything else.
Examples
Valid array
```
is_array([1, 2, 3])
```
```
true
```
Try it yourself with the `vector vrl` subcommand.

is_boolean

Check if the type of a value is a boolean or not.

Spec
```
is_boolean(value: <any>) :: <boolean>
```
- required
  value - The value to check
- return - a <boolean>
  - Returns true if value is a boolean.
  - Returns false if value is anything else.
Examples
Valid boolean
```
is_boolean(false)
```
```
true
```
Try it yourself with the `vector vrl` subcommand.

is_float

Check if the type of a value is a float or not.

Spec
```
is_float(value: <any>) :: <boolean>
```
- required
  value - The value to check
- return - a <boolean>
  - Returns true if value is a float.
  - Returns false if value is anything else.
Examples
Valid float
```
is_float(0.577)
```
```
true
```
Try it yourself with the `vector vrl` subcommand.

is_integer

Check if the type of a value is an integer or not.

Spec
```
is_integer(value: <any>) :: <boolean>
```
- required
  value - The value to check
- return - a <boolean>
  - Returns true if value is an integer.
  - Returns false if value is anything else.
Examples
Valid integer
```
is_integer(1)
```
```
true
```
Try it yourself with the `vector vrl` subcommand.

is_null

Check if the type of a value is null or not. For a more relaxed function please check is_nullish.

Spec
```
is_null(value: <any>) :: <boolean>
```
- required
  value - The value to check
- return - a <boolean>
  - Returns true if value is null.
  - Returns false if value is anything else.
Examples
Null value
```
is_null(null)
```
```
true
```
Try it yourself with the `vector vrl` subcommand.

is_nullish

Determines whether the value is "nullish," where nullish denotes the absence of a meaningful value.

Spec
```
is_nullish(value: <any>) :: <boolean>
```
- required
  value - The value to check for "nullishness," i.e. a useless value.
- return - a <boolean>
  - Returns true if value is null.
  - Returns true if value is "-".
  - Returns true if value is whitespace as defined by Unicode White_Space property.
  - Returns false if value is anything else.
Examples
Null detection (blank string)
```
is_nullish("")
```
```
true
```
Try it yourself with the `vector vrl` subcommand.

is_object

Check if the type of a value is an object or not.

Spec
```
is_object(value: <any>) :: <boolean>
```
- required
  value - The value to check
- return - a <boolean>
  - Returns true if value is an object.
  - Returns false if value is anything else.
Examples
Valid object
```
is_object({"foo": "bar"})
```
```
true
```
Try it yourself with the `vector vrl` subcommand.

is_regex

Check if the type of a value is a regex or not.

Spec
```
is_regex(value: <any>) :: <boolean>
```
- required
  value - The value to check
- return - a <boolean>
  - Returns true if value is a regex.
  - Returns false if value is anything else.
Examples
Valid regex
```
is_regex(r'pattern')
```
```
true
```
Try it yourself with the `vector vrl` subcommand.

is_string

Check if the type of a value is a string or not.

Spec
```
is_string(value: <any>) :: <boolean>
```
- required
  value - The value to check
- return - a <boolean>
  - Returns true if value is a string.
  - Returns false if value is anything else.
Examples
Valid string
```
is_string("a string")
```
```
true
```
Try it yourself with the `vector vrl` subcommand.

is_timestamp

Check if the type of a value is a timestamp or not.

Spec
```
is_timestamp(value: <any>) :: <boolean>
```
- required
  value - The value to check
- return - a <boolean>
  - Returns true if value is a timestamp.
  - Returns false if value is anything else.
Examples
Valid timestamp
```
is_timestamp(t'2021-03-26T16:00:00Z')
```
```
true
```
Try it yourself with the `vector vrl` subcommand.

object

Returns the value if it's an object and errors otherwise. This enables the type checker to guarantee that the returned value is an object and can be used in any function that expects one.

Spec
```
object(value: <any>) :: <object>, <error>
```
- required
  value - The value that you need to ensure is an object.
- return - a <object>
  - Returns the value if it's an object.
  - Raises an error if not an object.
Errors
This function is fallible, error handling is required.
- value isn't an object.

Examples

Vector event

{
  "value": {
    "field1": "value1",
    "field2": "value2"
  }
}

VRL program

object!(.value)

{
  "field1": "value1",
  "field2": "value2"
}

Try it yourself with the `vector vrl` subcommand.

string

Returns the value if it's a string and errors otherwise. This enables the type checker to guarantee that the returned value is a string and can be used in any function that expects one.

Spec
```
string(value: <any>) :: <string>, <error>
```
- required
  value - The value that you need to ensure is a string.
- return - a <string>
  - Returns the value if it's a string.
  - Raises an error if not a string.
Errors
This function is fallible, error handling is required.
- value isn't a string.
Examples
Vector event
```
{
  "message": "{\"field\": \"value\"}"
}
```
VRL program
```
string!(.message)
```
```
"{\"field\": \"value\"}"
```
Try it yourself with the `vector vrl` subcommand.

tag_types_externally

Adds type information to all (nested) scalar values in the provided value.

The type information is added externally, meaning that value has the shape of "type": value after this transformation.

Spec
```
tag_types_externally(value: <any>) :: <object | array | null>
```
- required
  value - The value to tag with types.
- return - a <object | array | null>
Examples
Tag types externally (scalar)
```
tag_types_externally(123)
```
```
{
  "integer": 123
}
```
Try it yourself with the `vector vrl` subcommand.

timestamp

Returns the value if it's a timestamp and errors otherwise. This enables the type checker to guarantee that the returned value is a timestamp and can be used in any function that expects one.

Spec
```
timestamp(value: <any>) :: <timestamp>, <error>
```
- required
  value - The value that you need to ensure is a timestamp.
- return - a <timestamp>
  - Returns the value if it's a timestamp.
  - Raises an error if not a timestamp.
Errors
This function is fallible, error handling is required.
- value isn't a timestamp.

Examples

Vector event

{
  "timestamp": "2020-10-10T16:00:00Z"
}

VRL program

ok, err = timestamp(.timestamp)

"function call error for \"timestamp\" at (10:31): expected \"timestamp\", got \"string\""

Try it yourself with the `vector vrl` subcommand.

#Array functions

#append

#Spec

#Examples

#push

#Spec

#Examples

#Codec functions

#decode_base64

#Spec

#Errors

#Examples

#encode_base64

#Spec

#Examples

#encode_json

#Spec

#Examples

#Coerce functions

#to_bool

#Spec

#Errors

#Examples

#to_float

#Spec

#Errors

#Examples

#to_int

#Spec

#Errors

#Examples

#to_regex

#Spec

#Notices

#Errors

#Examples

#to_string

#Spec

#Errors

#Examples

#to_timestamp

#Spec

#Errors

#Examples

#Convert functions

#to_syslog_facility

#Spec

#Errors

#Examples

#to_syslog_level

#Spec

#Errors

#Examples

#to_syslog_severity

#Spec

#Errors

#Examples

#to_unix_timestamp

#Spec

#Examples

#Debug functions

#assert

#Spec

#Notices

#Errors

#Examples

#log

#Spec

#Examples

#Enumerate functions

#compact

#Spec

#Examples

#flatten

#Spec

#Examples

#includes

#Spec

#Examples

#length

Array functions

append

Spec

Examples

push

Spec

Examples

Codec functions

decode_base64

Spec

Errors

Examples

encode_base64

Spec

Examples

encode_json

Spec

Examples

Coerce functions

to_bool

Spec

Errors

Examples

to_float

Spec

Errors

Examples

to_int

Spec

Errors

Examples

to_regex

Spec

Notices

Errors

Examples

to_string

Spec

Errors

Examples

to_timestamp

Spec

Errors

Examples

Convert functions

to_syslog_facility

Spec

Errors

Examples

to_syslog_level

Spec

Errors

Examples

to_syslog_severity

Spec

Errors

Examples

to_unix_timestamp

Spec

Examples

Debug functions

assert

Spec

Notices

Errors

Examples

log

Spec

Examples

Enumerate functions

compact

Spec

Examples

flatten

Spec

Examples

includes

Spec

Examples

length