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

date: "2021-12-28" title: "0.19 Upgrade Guide" description: "An upgrade guide that addresses breaking changes in 0.19.0" authors: ["001wwang"] pr_numbers: [] release: "0.19.0" hideonrelease_notes: false badges: type: breaking change Vector's 0.19.0 release includes breaking changes: And deprecations: And behavioral changes: We cover them below to help you upgrade quickly: We've removed a long deprecated configuration field from the Splunk HEC Logs sink: `host`. You can migrate your configuration by switching to `endpoint` instead. ```diff [sinks.splunk] type = "splunkheclogs" host = "http://splunk-endpoint" endpoint = "http://splunk-endpoint" ... ``` As part of moving towards more consistent Vector component instrumentation, we've updated the following internal metrics in the Splunk HEC sinks. For any removed metric, we've added an equivalent alternative. Removed `encodeerrorstotal` Instead, use `componenterrorstotal` with the tag `errortype = encodefailed`. Removed `processingerrorstotal` with tag `errortype = invalidmetric_kind` Instead, use `componenterrorstotal` with the tag `errortype = invalidmetric`. Removed `processedbytestotal` Instead, use `componentreceivedeventbytestotal` and `componentsenteventbytestotal`. Added `componentsdiscardedevents_total` Previously, no metric was emitted when an encoding error occurred and an event was dropped. | Deprecated Field | New Field | | -- | -- | | `mode = normal` | `mode = bulk` | | `host` | `endpoint` | | `bulk_action` | `bulk.action` | | `index` | `bulk.index` | | `headers` | `request.headers` | In the v0.16.0 release, we have that the `vector` source and sink use to communicate. This new protocol offers a number of advantages over our initial `v1` protocol implementation including load balancing and better back-pressure handling. Up until this release, the `vector` source and sink continued defaulting to the `v1` protocol for compatibility. In this release, we remove this default and require you to specify the `version` field in the `vector` source and sink configuration. The intent of this change is to prompt users to migrate. If you do not specify a version number, you will see an error like: ```text Configuration error. error=data did not match any variant of untagged enum VectorConfig for key

at line 8 column 1 ``` To continue using the `v1` protocol, simply add `version = "1"` to your configuration like: ```diff [sinks.vector] type = "vector" version = "1" [sources.vector] type = "vector" version = "1" ``` However, we recommend that you transition to the `v2` protocol by setting `version = "2"`: ```diff [sinks.vector] type = "vector" version = "2" [sources.vector] type = "vector" version = "2" ``` There are some configuration options that are no longer valid with version 2 of the source and sink: `vector` source: `keepalive` and `receivebufferbytes` `vector` sink: `keepalive` and `sendbufferbytes` As these were specific to the TCP-based version 1 of the protocol. See the for a guide on how to transition without downtime. In a subsequent release we will begin defaulting to the `v2` protocol and eventually remove support for the `v1` protocol. The `token` configuration option on the `splunkheclogs` and `splunkhecmetrics` sink has been deprecated in-lieu of the new `default_token` option which was added as part of support for Splunk HEC token pass-through. You can migrate your configuration by renaming `token` to `default_token`: ```diff [sinks.splunk] type = "splunkheclogs" endpoint = "http://splunk-endpoint" token = "MY-TOKEN" default_token = "MY-TOKEN" ... ``` As part of our work to support Splunk HEC indexer acknowledgements, `splunk_hec` sinks will generate a random UUID to use as the `X-Splunk-Request-Channel` header value. Splunk accepts this header regardless of whether indexer acknowledgements is enabled, so the `splunk_hec` sinks always attach the header. In other words, disabling indexer acknowledgements for the sink will not disable this header value. You can read more about channels in the [official Splunk docs](https://docs.splunk.com/Documentation/Splunk/8.2.4/Data/FormateventsforHTTPEventCollector#Channelidentifierheader). If your setup involves a `splunkhec` sink sending into a separate `splunkhec` source, you will now see a `splunk_channel` field in events output from the `splunkhec` source. This is because `splunkhec` sources have always parsed and included channel information from requests in their events. If you want to remove this field, you can simply drop it with a `remap` transform like follows: ```toml [transforms.foo] type = "remap" inputs = ["bar"] # where bar is the splunk_hec source source = ''' del(.splunk_channel) ''' ```