Project: Vector (Observability and Analysis / Observability)
File: 2022-02-08-0-20-0-upgrade-guide.md

date: "2022-02-08" title: "0.20 Upgrade Guide" description: "An upgrade guide that addresses breaking changes in 0.20.0" authors: ["tobz","spencergilbert"] pr_numbers: [] release: "0.20.0" hideonrelease_notes: false badges: type: breaking change Vector's 0.20.0 release includes breaking changes: And deprecations: We cover them below to help you upgrade quickly: As part of work to better control memory growth in the `prometheus_exporter` sink, we've done some work to ensure that metric expiration behavior is consistent for all metrics. Instead of reporting a count of zero when they expire, sets will now stop reporting entirely when they expire and are flushed. Due to how the `prometheus_exporter` sink works, Vector must store a snapshot of the state of all metrics: the latest value of a counter or a gauge, and so on. Sets represent a list of unique values, and these values can be anything from integer to strings, which over time, can grow quite large. To combat memory growth, we "expire" metrics from the sink if they have not been updated within the time window configured by `flushperiodsecs`. For all metrics besides sets, we would delete the metric from the internal state and stop reporting it. For sets, however, we would simply clear their values and thus report a set size of zero. This behavior was not consistent with how we expired other metric types, and additionally, could still lead to a growth of unique series in a scrape, over time, as we would clear the set but not stop reporting it. Previously, a `route` transform was internally expanded into a separate transform for each defined route. Each of these expanded transforms then emitted its own metrics. Now, with improved internal support for components with multiple outputs, this expansion mechanism has been removed. A single `route` transform will now emit one set of metrics. For the following metrics, specific route information will be recorded as a metric tag `output`. `componentsentevents_total` `componentsenteventbytestotal` `eventsdiscardedtotal` For example, for a `route` transform `foo` with a route `first` configured, the `eventsdiscardedtotal` metric will now look like the following: ```diff {"counter":{"value":10.0},"name":"eventsdiscardedtotal"... "tags":{"componentid":"foo.first","componentkind":"transform","componentname":"foo.first","componenttype":"route"}} {"counter":{"value":10.0},"name":"eventsdiscardedtotal"... "tags":{"componentid":"foo","componentkind":"transform","componentname":"foo","componenttype":"route","output":"first"}} ``` The `loki` sink can be configured to either drop or rewrite the timestamp of events that are out-of-order. With this release we've updated the logs and metrics related to both options for

`drop`: Associated log now emitted at DEBUG, rather than WARN `processingerrorstotal` metric deprecated, will be removed next release `eventsdiscardedtotal` metric `componentdiscardedevents_total` added to align the sink with new component spec `rewrite_timestamp`: Associated log now emitted at DEBUG, rather than WARN `processingerrorstotal` metric deprecated, will be removed next release `rewrittentimestampevents_total` metric added Previously, predicates in an `if` statement were not checked at compile time to ensure they could not error. The result of this was that if an error did occur at run time whilst evaluating the predicate Vector would panic. This is now caught at compile time. Any unhandled errors in a predicate will result in a compilation error and Vector will not start. For example, the following `VRL` used to compile: ```coffeescript if contains(.message, "true") { log("true") } ``` If the message was not a string an error would be raised, resulting in a panic. To make this run now, the error needs to be handled: ```coffeescript if contains(.message, "true") ?? false { log("true") } ``` Previously, all division in `VRL` was considered a fallible operation, to handle any division by zero errors. This was even the case when you were dividing by a literal number which could obviously never be zero. This has now been fixed so dividing by a non-zero literal does not require the error to be handled. Previously you were required to handle the error like: ```coffeescript .zorp = .spog / 43 ?? "this error can never happen" ``` Now, you will not be required to handle the error. In fact handling this error will now result in a compilation error. To fix remove the error coalesce. ```coffeescript .zorp = .spog / 43 ``` Previously if the `syslog` codec was used on a source and the incoming message could not be parsed as a syslog message it would not raise an error - instead the whole message would be received in the `.message` field. This has now been changed to raise an error instead. Previously, including nonexistent targets in `extract_from` or `nooutputsfrom` in a unit test configuration was allowed. However, these nonexistent targets had no outputs and could result in misleading test results. Now, errors will be raised at unit test build time if nonexistent targets are included. Note in `v0.20.0`, a panic occurs while in `v0.20.1` informative error messages are output. With this release, we've deprecated version 1 of the Vector protocol used by the `vector` sink to write data to a remote `vector` source. The `vector` source and sink now default the `version` field to `"2"` (in 0.19.0 the default of "v1" was removed). Support for version 1 of the protocol will be removed in a future release. See the for additional details about why we introduced this new gRPC-based protocol.