This guide describes the steps to upgrade dd-trace from a major version to the next. If you are having any issues related to migrating, please feel free to open an issue or contact our support team.
Node.js 12 has been EOL since April 2022 and is no longer supported. Generally speaking, we highly recommend always keeping Node.js up to date regardless of our support policy.
HTTP query strings are now reported by default as part of the http.url tag.
This change is considered breaking only because there might be sensitive data
in the query string. A default regular expression based obfuscator is provided
for common use cases like API keys, but if your use case is not covered, the
DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP
environment variable can be used to control what is obfuscated, and a value of
.* would redact the query string entirely.
The HTTP integration now uses web.request for incoming requests and continues
to use http.request for outgoing requests. When using a supported web
framework like Express, this change will have no effect because the root span
would already have an operation name override like express.request.
Any monitor
on http.request for incoming requests should be updated to web.request.
With this change, both operation names also appear under the main service name
and are no longer split between the server service name and a separate client
service name suffixed with -http-client.
The gRPC integration now uses grpc.server for incoming requests and
grpc.client for outgoing requests. Any
monitor
on grpc.request should be updated to one of these.
With this change, both operation names also appear under the main service name
and are no longer split between the server service name and a separate client
service name suffixed with -http-client.
The fs integration was removed as it was originally added without an actual
use case, and it's been problematic ever since. It's noisy, the output is
confusing when using streams, errors that are handled higher in the stack end up
being captured, etc.
If you had any use for file system instrumentation, please let us know so we can provide an alternative.
It's no longer possible to bind promises using tracer.scope().bind(promise) or
event emitters using tracer.scope().bind(emitter). These were historically
added mostly for internal use, and changes to context propagation over the years
made them unnecessary, both internally and externaly. If one of these is used
anywhere, the call will simply be ignored and no binding will occur.
To bind the then handler of a promise, bind the function directly directly:
promise.then(tracer.scope().bind(handler))To bind all listeners for an event, wrap the call to emit directly instead:
tracer.scope().activate(span, () => {
emitter.emit('event')
})To bind individual listeners, bind the listener function directly instead:
emitter.on('event', tracer.scope().bind(listener, span))The following APIs have been deprecated for a long time and have now been completely removed:
tracer.currentSpan()tracer.bindEmitter()
Since these have not been recommended nor publicly documented for years at this point, there should be no impact as no application is expected to be using them.
dd-trace/cypress/plugin and dd-trace/cypress/support are removed, so you won't
be able to use them for your cypress instrumentation. Use dd-trace/ci/cypress/plugin
and dd-trace/ci/cypress/support instead for your plugin and support configuration
respectively.
The use of 'dd-trace/ci/jest/env' in testEnvironment
is no longer supported.
To instrument jest tests now, add '-r dd-trace/ci/init' to the NODE_OPTIONS environment
variable passed to the process running the tests, for example, NODE_OPTIONS='-r dd-trace/ci/init' yarn test.
The use of --require dd-trace/ci/init as a mocha flag is no longer supported.
To instrument mocha tests now, add '-r dd-trace/ci/init' to the NODE_OPTIONS environment
variable passed to the process running the tests, for example, NODE_OPTIONS='-r dd-trace/ci/init' yarn test.
The use of --require-module dd-trace/ci/init as a cucumber-js flag is no longer supported.
To instrument cucumber-js tests now, add '-r dd-trace/ci/init' to the NODE_OPTIONS environment
variable passed to the process running the tests, for example, NODE_OPTIONS='-r dd-trace/ci/init' yarn test.
The following configuraton options are no longer available programmatically and must be configured using these environment variables:
enabled->DD_TRACE_ENABLED=true|falsedebug->DD_TRACE_DEBUG=true|false
If environment variables were already used for these options, no action is needed.
The following configuration options were completely removed and will no longer have any effect:
scope
Startup logs are now disabled by default and can be enabled if needed with
DD_TRACE_STARTUP_LOGS=true.
The original scope manager has been replaced several years ago and has now been
removed. Any code referencing tracer.scopeManager() should be removed or
replaced with tracer.scope() which is documented
here.
Support for nested objects as tags as been removed. When adding an object as a tag value, only properties that exist on that object directly will be added as tags. If nested properties are also needed, these should be added by hand.
For example:
const obj = {
a: 'foo',
b: {
c: 'bar'
}
}
// 1.0
span.setTag('test', obj) // add test.a and test.b.c
// 2.0
span.setTag('test', obj) // add test.a
span.setTag('test.b', obj.b) // add test.b.cArrays are no longer supported and must be converted to string manually.
Outgoing request filtering is no longer supported and is now only available for
incoming requests. This means that the blocklist and allowlist options on
the http integration no longer have any effect.