ContextQMD
Back to Vector

0.28 Upgrade Guide

website/content/en/highlights/2023-02-28-0-28-0-upgrade-guide.md

0.55.06.2 KB
Original Source

Vector's 0.28.0 release includes breaking changes:

  1. The journald source's units option removed
  2. Removal of metadata functions
  3. Removal of the apex sink
  4. Removal of the disk_v1 buffer type
  5. Renaming of host to hostname in datadog_logs

and deprecations:

  1. The redis sink's url argument changed to endpoint
  2. The aws_s3 source's strategy option has been hidden
  3. The axiom sink now hardcodes the timestamp-field header
  4. The datadog_logs and datadog_metrics sinks' api_key option will be removed in 0.29

and potentially impactful changes:

  1. AWS components now use OpenSSL as the TLS implementation
  2. The azure_monitor_logs sink now hardcodes the timestamp field

We cover them below to help you upgrade quickly:

Upgrade guide

Breaking changes

The journald source's units option removed {#journald-units}

The units option had been replaced by include_units in the 0.10 release. This release marks the final removal of this option, please update your configurations to use the include_units option instead.

Removal metadata functions {#metadata-functions-removal}

Vector 0.25.0 introduced new metadata path syntax available in VRL which points directly to event metadata. That meant the metadata functions were no longer necessary and were deprecated. They are now being removed. The table below shows you how to convert VRL code from the method calls to the new path syntax. If you are running Vector 0.25.0 or later, you will also receive warnings which will provide you with the correct syntax to use to migrate.

beforeafter
getget_metadata_field(.foo.bar)%foo.bar
setset_metadata_field(.foo.bar, "value")%foo.bar = "value"
deleteremove_metadata_field(.foo.bar)del(%foo.bar)

Removal of the apex sink {#apex-removal}

The apex sink has been removed from Vector. This follows the EOL of the Apex service that took effect in December 2022.

Removal of the disk_v1 buffer type {#disk_v1-removal}

The deprecated disk_v1 buffer type was removed. Users using this buffer type should use Vector v0.27.1 to migrate their buffers to the new disk buffer implementation by switching to the disk buffer type before upgrading to v0.28.0 which had the migration behavior removed.

diff
-type = "disk_v1"
+type = "disk"

The change should be transparent. See the blog post about the promotion of the new disk buffers to the default for type = "disk" for details about this migration. Also see the blog post about the introduction of the new disk buffer implementation for the reasons the new disk buffer implementation was introduced.

Renaming of host to hostname in datadog_logs {#host-rename-dd-logs}

In the datadog_logs sink, if an event contained the host key from either the global log schema, or the host path of the event, it was renamed to host. This was changed to rename it to hostname, to match the Datadog Agent intake API.

Deprecation notices

The redis sink's url argument changed to endpoint {#redis-endpoint}

To maintain consistent naming with other Vector sinks, the url option in the redis sink has been renamed to endpoint. url will still work, but has been deprecated and will be removed in due course.

The aws_s3 source's strategy option has been hidden {#aws_s3-strategy}

The strategy option has been hidden on the documentation for the aws_s3 source. sqs is currently the only value for this option, and is currently the default. If additional strategies are added for this source, we will expose this option again. No changes need to be made by users of this source, it is a documentation only change.

The axiom sink now hardcodes the timestamp-field header {#axiom-header}

Previously this sink used the global log_schema to provide the value for this header, however the actual implementation always ensured an event's timestamp was stored at @timestamp. In this release we've hardcoded this header to match the underlying implementation.

The datadog_logs and datadog_metrics sinks' api_key option will be removed in 0.29 {#dd-sinks-api-key}

The api_key option has been hidden on the documentation for the datadog_logs and datadog_metrics sinks for a few releases now, with the documented name for that setting being default_api_key. The api_key is now formally deprecated and will be removed in the 0.29.0 release.

Potentially impactful changes

AWS components now use OpenSSL as the TLS implementation {#aws-openssl}

In this release, Vector's AWS integrations had their TLS implementation swapped from rustls to OpenSSL. We don't expect any user visible impact, but please let us know if this change causes you any issues.

We made this change primarily since most of Vector's dependencies use OpenSSL and so it reduces our maintenance burden caused by any variances in the implementation. We may re-evaluate in the future as more of the Rust ecosystem supports rustls.

The azure_monitor_logs sink now encodes the timestamp at a configurable path {#azure-timestamp}

Previously this sink would include a properly formatted timestamp at a path determined by the log_schema as well as setting a time-generated-field header with a value of that path. Azure Monitor will use the contained value to populate the TimeGenerated standard column. In this release we've added a time_generated_key option that determines where this field is encoded, this field defaults to the value set in log_schema if unset.