Project: Vector (Observability and Analysis / Observability)
File: 2022-07-07-0-23-0-upgrade-guide.md

date: "2022-07-07" title: "0.23 Upgrade Guide" description: "An upgrade guide that addresses breaking changes in 0.23.0" authors: ["akx", "jszwedko", "spencergilbert", "fuchsnj", "pablosichert", "JeanMertz"] release: "0.23.0" hideonrelease_notes: false badges: type: breaking change Vector's 0.23.0 release includes breaking changes: and deprecations: We cover them below to help you upgrade quickly: The no longer automatically enables and starts the Vector systemd service. This is in line with how the RPM package behaves. To enable and start the service (after configuring it to your requirements), you can use `systemctl enable --now`: ```shell systemctl enable --now vector ``` To just start the service without enabling it to run at system startup, ```shell systemctl start vector ``` There were many situations where VRL didn't calculate the correct type definition. These are now fixed. In some cases this can cause compilation errors when upgrading if the code relied on the previous (incorrect) behavior. This affects the following: the "merge" operator (`|` or `|=`) on objects that share keys with different types if statements nullability checking for most expressions (usually related to if statements) expressions that contain the `abort` expression the `del` function closure arguments The best way to fix these issues is to let the compiler guide you through the problems, it will usually provide suggestions on how to fix the issue. Please give us feedback if you think any error diagnostics could be improved, we are continually trying to improve them. The most common error you will probably see is the fallibility of a function changed because the type of one of the parameters changed. For example, if you are trying to "split" a string, but the input could now be null, the error would look like this ```text error[E110]: invalid argument type :1:7 1 split(msg, " ") ^^^ this expression resolves to one of string or null but the parameter "value" expects the exact type string = try: ensuring an appropriate type at runtime = = msg = string!(msg) = split(msg, " ") = = try: coercing to an appropriate type and specifying a default value as a fallback in case coercion fails = = msg = to_string(msg) ?? "default" = split(msg, " ") = = 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 ``` As suggested, you have a few options to solve errors like this. Abort if the arguments aren't the right type by appending the function name with `!`, such as `to_string!(msg)` Force the type to be a string, using the `string` function. This function will error at runtime if the value isn't the expected type. You can call it as `string!` to abort if it's not the right type. Provide a default value if the function fails using the "error coalescing" operator (`??`), such as `to_string(msg) ?? "default"` Handle the error manually by capturing both the return value and possible error, such as `result, err = to_string(msg)` The "removeempty" argument has been dropped from both the `parsegrok` and the `parse_groks` functions. Previously, these functions would return empty strings for non-matching pattern names, but now they are not

To preserve the old behavior, you can do something like the following to merge in empty strings for each unmatched group: ```coffee parsed = parsegrok!(.message, "%{TIMESTAMPISO8601:timestamp} %{LOGLEVEL:level} %{GREEDYDATA:message}") expected = { "timestamp": "", "level": "", "message": ""} parsed = merge(expected, parsed) ``` VRL conditions, for example those used in the `filter` transform, are not supposed to mutate the event. Previously the mutations would be silently ignored after a condition ran. Now the compiler has support for read-only values, and will give a compile-time error if you try to mutate the event in a condition. Example filter transform config ```toml [transforms.filter] type = "filter" inputs = [ "input" ] condition.type = "vrl" condition.source = """ .foo = "bar" true """ ``` New error ```text error[E315]: mutation of read-only value :1:1 1 .foo = "bar" ^^^^^^ mutation of read-only value = see language documentation at https://vrl.dev ``` Previously, the `parse_syslog` VRL function and the `syslog` source handled parsing the structured data section of syslog messages differently: The `syslog` source inserted a field with the name of the structured data element, with the fields as keys in that map. It would create further nested maps if the structured data key names had `.`s in them. The `parse_syslog` function would instead prefix the structured data keys with the name of the structured data element they appeared in, but would insert this as a flat key/value structure rather than nesting (so that referencing keys would require quoting to escape the `.`s). With this release the behavior of both is now to parse the structured data section as a flat map of string key / string value, and insert it into the target under a field with the name of the structured data element. That is: ```text <1>1 2022-04-25T23:21:45.715740Z Gregorys-MacBook-Pro.local 2d4d9490-794a-4e60-814c-5597bd5b7b7d 79978 - [exampleSDID@32473 foo.baz="bar"] test message ``` Now returns (for both the `syslog` source and the `parse_syslog` function): ```json { "appname": "2d4d9490-794a-4e60-814c-5597bd5b7b7d", "exampleSDID@32473": { "foo.baz": "bar" }, "facility": "kern", "hostname": "Gregorys-MacBook-Pro.local", "message": "test message", "procid": 79978, "severity": "alert", "timestamp": "2022-04-25T23:21:45.715740Z", "version": 1 } ``` Where previously VRL's `parse_syslog` function returned: ```json { "appname": "2d4d9490-794a-4e60-814c-5597bd5b7b7d", "exampleSDID@32473.foo.baz": "bar", "facility": "kern", "hostname": "Gregorys-MacBook-Pro.local", "message": "test message", "procid": 79978, "severity": "alert", "timestamp": "2022-04-25T23:21:45.715740Z", "version": 1 } ``` And the `syslog` source returned: ```json { "appname": "2d4d9490-794a-4e60-814c-5597bd5b7b7d", "exampleSDID@32473": { "foo": { "baz": "bar" } }, "facility": "kern", "hostname": "Gregorys-MacBook-Pro.local", "message": "test message", "procid": 79978, "severity": "alert", "timestamp": "2022-04-25T23:21:45.715740Z", "version": 1 } ``` The previous `parse_syslog` behavior can be achieved by running the result through the `flatten` function like: ```coffeescript flatten(parse_syslog!(s'<1>1 2022-04-25T23:21:45.715740Z Gregorys-MacBook-Pro.local 2d4d9490-794a-4e60-814c-5597bd5b7b7d 79978 - [exampleSDID@32473 foo.baz="bar"] test message')) ``` The experimental VM runtime for VRL-based components has been removed. The stable AST runtime remains in place, and is now nearly identical in performance to the VM runtime. If you have `runtime = "vm"` configured in your config, you need to remove it to avoid Vector from erroring on startup. The `gcp_pubsub` sink now supports a variety of codecs. To encode your logs as JSON before publishing them to Cloud Pub/Sub, add the following encoding option ```toml encoding.codec = "json" ``` to the config of your `gcp_pubsub` sink. The `humio_metrics` sink configuration no longer expects an `encoding` option. If you previously used the encoding option ```toml encoding.codec = "json" ``` you need to remove the line from your `humio_metrics` config. Metrics are now always sent to Humio using the JSON

We streamlined the encoding configuration for our sinks, enabling all applicable sinks to select from a variety of codecs: `json`, `text`, `raw`, `logfmt`, `avro`, `native` or `native_json`, e.g. by setting ```toml encoding.codec = "json" ``` in your sink configuration. Additionally, some sinks now support configuring how encoded events should be separated within a stream or batch: `bytes`, `characterdelimited`, `lengthdelimited` or `newline_delimited`, e.g. by setting ```toml framing.method = "newline_delimited" ``` in your sink configuration. The following sinks support setting an encoding codec: `awscloudwatchlogs`, `awskinesisfirehose`, `awskinesisstreams`, `awss3`, `awssqs`, `azure_blob`, `console`, `file`, `gcpcloudstorage`, `gcppubsub`, `http`, `humiologs`, `kafka`, `loki`, `nats`, `papertrail`, `pulsar`, `redis`, `socket`, `splunkheclogs` and `websocket`. Additionally, the following sinks support setting a framing method: `awss3`, `azureblob`, `console`, `file`, `gcpcloudstorage`, `http` and `socket`. Due to changes to the , support for operating systems with old versions of `libc` and `libstdc++` were dropped for the `x86-unknown_linux-gnu` target. Vector now requires that the host system has `libc` >= 2.18 and `libstdc++` >= 3.4.21 with support for ABI version 1.3.8. Known OSes that this affects: Amazon Linux 1 Ubuntu 14.04 CentOS 7 We will be looking at options to [re-add support for these OSes](http://github.com/vectordotdev/vector/issues/13183) in the future. Logs from Kubernetes pods are now annotated with a node's labels on which a pod is running. For official helm-chart users, upgrade the chart to the version >= before upgrading the vector version in your cluster. For custom vector installations, modify the cluster role assigned to the vector service account to include nodes. The result should look like the following snippet: ```yaml apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: vector rules: apiGroups: "" resources: namespaces nodes pods verbs: list watch ``` Incoming events from the `datadogagent` source contain a name that is `.` (period) delimited where the first element is the namespace eg "system.fs.inodes.total". Before this release, the metric event outputted by the `datadogagent` source contained an empty namespace, and the name contained the full unparsed name from the Datadog Agent. In this release, the namespace is parsed out of the name. Taking the prior example, the event name becomes "fs.inodes.total" and the namespace is "system". This was introduced in order to better handle metrics sent from the `datadogagent` source to the `datadogmetrics` sink, where previously they would be lacking a namespace and so would have one added by the sink if `default_namespace` was set. The result is that configurations with VRL expressions that expect the namespace to be in the name will need to be adapted to either remove the namespace from the name, or join the namespace and the name, for example: ```toml fullmetricname = """ join([.namespace, .name], ".") """ ``` We are deprecating setting encoding options by a shorthand string. E.g. when your sink encoding used ```toml encoding = "json" ``` it should now be replaced by explicitly setting the `codec` ```toml encoding.codec = "json" ``` The `ndjson` encoding value will be phased out since the `newline_delimited` behavior may be either set by default or can be set explicitly via a dedicated `framing` option. This affects all sink configurations that previously used ```toml encoding.codec = "ndjson" ``` The `http`, `awss3`, `gcpcloudstorage` and `azureblob` sinks should be configured to use a combination of `json` encoding and `newline_delimited` framing instead ```toml framing.method = "newline_delimited" encoding.codec = "json" ``` For all other sinks, simply set the codec to `json` to maintain the current behavior ```toml encoding.codec = "json" ```