Skip to content

Latest commit

 

History

History
224 lines (155 loc) · 8.03 KB

MIGRATING.md

File metadata and controls

224 lines (155 loc) · 8.03 KB
Raw

Migrating

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.

4.0 to 5.0

Node 16 is no longer supported

Node.js 16 has reached EOL in September 2023 and is no longer supported. Generally speaking, we highly recommend always keeping Node.js up to date regardless of our support policy.

Update trace<T> TypeScript declaration

The TypeScript declaration for trace<T> has been updated to enforce that calls to tracer.trace(name, fn) must receive a function which takes at least the span object. Previously the span was technically optional when it should not have been as the span must be handled.

3.0 to 4.0

Node 14 is no longer supported

Node.js 14 has reached EOL in April 2023 and is no longer supported. Generally speaking, we highly recommend always keeping Node.js up to date regardless of our support policy.

The orphanable option was removed

This option was only useful internally for a single integration that has since been removed. It was never useful for manual instrumentation since all that is needed to orphan a span on creation is to use tracer.trace('web.request', { childOf: null }).

Support for jest-jasmine2 has been removed

The default test runner for Jest was changed to jest-circus around 2 years ago and is no longer supported by our Jest integration for CI Visibility. We recommend switching to jest-circus to anyone still using jest-jasmine2.

Support for older Next.js versions was removed

We now support only Next.js 10.2 and up.

2.0 to 3.0

Node 12 is no longer supported

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 string reported by default

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.

HTTP operation name change

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.

gRPC operation name change

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.

Removal of fs integration

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.

Scope binding for promises and event emitters

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))

Removed APIs

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.

CI Visibility new entrypoints

Cypress

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.

Jest

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.

Mocha

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.

Cucumber

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.

1.0 to 2.0

Configuration

The following configuraton options are no longer available programmatically and must be configured using these environment variables:

  • enabled -> DD_TRACE_ENABLED=true|false
  • debug -> 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.

Removed APIs

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.

Nested objects as tags

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.c

Arrays are no longer supported and must be converted to string manually.

Outgoing request filtering

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.