Project: Vector (Observability and Analysis / Observability)
File: 2021-02-16-0-12-upgrade-guide.md

date: "2021-02-16" title: "0.12 Upgrade Guide" description: "An upgrade guide that addresses breaking changes in 0.12.0" authors: ["binarylogic"] pr_numbers: [5281, 5978] release: "0.12.0" hideonrelease_notes: false badges: type: breaking change 0.12 includes minimal breaking changes but significant deprecations. This guide will upgrade you quickly and painlessly. If you have questions, and we'll help you upgrade. removed the default values for the sink-level `encoding.codec` option. Therefore, you are now required to provide a value for this option, ensuring that you are not surprised by opinionated encoding defaults. Affected sinks include: `aws_s3` (previously defaulted to `text`) `file` (previously defaulted to `text`) `humio` (previously defaulted to `json`) `kafka` (previously defaulted to `text`) `nats` (previously defaulted to `text`) `newreliclogs` (previously defaulted to `json`) `pulsar` (previously defaulted to `text`) `splunk_hec` (previously defaulted to `text`) Upgrading is easy, just add the `encoding.codec` to your sinks with your preferred format (`json` or `text`): ```diff [sinks.backup] type = "aws_s3" inputs = ["..."] bucket = "my-bucket" compression = "gzip" region = "us-east-1" +encoding.codec = "json" ``` For clarity, the `text` option strips away all structured data and passes only the value of the `message` field. It is intended for use cases where Vector acts as a proxy and should not alter data. For most use cases we recommend `json` since it includes all structured data. With the of the (VRL), deprecated the `check_fields` conditions in favor of using . The old `check_fields` conditions were limiting and suffered from many of the outlined in the VRL announcement. Configuration languages, like TOML, are bad at expressing boolean conditions and severely limited how users could , , and data. While `check_fields` is deprecated and still supported, you will need to explicitly opt-into the feature by adding the `type` option: ```diff [transforms.route] type = "route" +lanes.errors.type = "check_field" lanes.errors."level.eq" = "error" ``` Alteratively, we recommend migrating to the new VRL syntax: ```diff [transforms.route] type = "route" -lanes.errors."level.eq" = "error" +lanes.errors = '.level = "error"' ``` Refer to the for the many ways you can specify conditions. The [`generator` source], commonly used for testing, has been updated with a new `format` option that emits logs in the specified format. You will not be required to provide this option. Upgrading is easy: ```diff [sources.generator] type = "generator" +format = "apachecommon" # or "apacheerror" or "syslog" ``` The following transforms have been deprecated in favor of the new : Deprecation notices have been placed on each of these transforms with example VRL programs that demonstrate how to migrate to the new `remap` transform. For example, migrating from the `json_parser` transform is as simple as: ```toml [transforms.remap] type = "remap" source = ''' . = merge(., parse_json!(.message)) ''' ``` You do not need to upgrade immediately. These transforms will not be removed until Vector hits 1.0, a milestone that we hope to achieve in late 2022. But, if possible, we recommend using this opportunity to upgrade and significantly simplify your Vector configuration. As always, if you need assistance . We're eager to help and receive feedback on the language. As noted in the , we've removed the `startatbeginning` option and replaced it with new and options. Migrating is easy: ```diff [sources.file] type = "file" -startatbeginning = true +ignore_checkpoints = false # default +read_from = "beginning" # default ``` Adjust as necessary. The above values are the defaults and are not required to be specified.