Upgrade to version 5.x
editUpgrade to version 5.x
editUpgrading 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
editAgent 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:
-
apm.addTags()
removed in favor ofapm.addLabels()
. -
span.addTags()
removed in favor ofspan.addLabels()
. -
transaction.addTags()
removed in favor oftransaction.addLabels()
.
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 to80
.
Upgrade steps
editUpgrade APM Server
editVersion 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
editAll 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 |
>= |
Java Agent |
>= |
.NET Agent |
>= |
Node.js Agent |
>= |
Python Agent |
>= |
Ruby Agent |
>= |
Upgrade the RUM agent
editUpdate 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:
-
errorThrottleLimit
removed in favor ofeventsLimit
. -
errorThrottleInterval
removed in favor ofeventsLimit
. -
transactionThrottleLimit
removed in favor ofeventsLimit
. -
transactionThrottleInterval
removed in favor ofeventsLimit
. -
apm.addTags()
removed in favor ofapm.addLabels()
. -
span.addTags()
removed in favor ofspan.addLabels()
. -
transaction.addTags()
removed in favor oftransaction.addLabels()
.