Upgrade to version 5.x

edit

Upgrading from version 4.x to 5.x of the RUM Agent introduces some breaking changes. This guide outlines the changes and the steps required to upgrade.

5.0 Breaking changes

edit

Agent name changed to rum-js

The Agent name has been changed to rum-js. Because older versions of the APM app in Kibana don’t recognize this new name, you may need to upgrade your Elastic stack version.

Official W3C tracecontext support

The RUM Agent supports the official W3C tracecontext traceparent header, instead of the previously used elastic-apm-traceparent header. If you’re using Elastic backend agents, you must upgrade them to a version that also supports the official W3C tracecontext headers.

addTags replaced with `addLabels

addTags, which was deprecated in version 4.1, has been removed and replaced with addLabels, which supports strings, booleans, and numbers:

Single queue processing

A single queue is now used to process all events (transactions, errors, etc.). This change allows the consolidation of four configuration options into one:

Removed options:

  • errorThrottleLimit
  • errorThrottleInterval
  • transactionThrottleLimit
  • transactionThrottleInterval

Added option:

  • eventsLimit — Configure the number of events sent to APM Server per minute. Defaults to 80.

Upgrade steps

edit

Upgrade APM Server

edit

Version 5.x of the RUM Agent requires APM Server version >= 7.0. The APM Server 7.0 upgrade guide can help with the upgrade process.

APM Server version >= 7.0 requires Elasticsearch and Kibana versions >= 7.0 as well.

Upgrade backend agents

edit

All Elastic APM agents have been upgraded to support the changes in the RUM Agent. You must upgrade your backend agents to the minimum versions listed below for all features to work:

Agent name Agent Version

Go Agent

>= 1.6

Java Agent

>= 1.14

.NET Agent

>= 1.3

Node.js Agent

>= 3.4

Python Agent

>= 5.4

Ruby Agent

>= 3.5

Upgrade the RUM agent

edit

Update or download the latest version of the RUM Agent using your preferred installation method.

If your old configuration used one of the removed config options (listed below), update your configuration to use the new config options instead.

Removed configurations: