dd-trace 0.4.0

on Node.js NPM

Features

• core: replace CLS with a new scope manager for context propagation (#184)

Breaking Changes

The new scope manager introduced in this release is incompatible with the current API. This change was done to increase the flexibility of the API and ensure better compatibility with OpenTracing going forward.

While we made an effort to keep as much of the current API as possible, the following might break:

• tracer.bind() and tracer.bindEmitter() are deprecated. We kept them so calls to them don't break but they are now NOOPs.
• tracer.trace() is deprecated. It should still work mostly as before for now.
• tracer.currentSpan() is deprecated. It should still work mostly as before for now.
• Promise handlers are now scoped to where then() is called instead of where resolve() is called.

Also keep in mind that the deprecated APIs will eventually be removed, so make sure to update your code to use the new scope manager as soon as possible.

Migration

In order to migrate to the new scope manager, there are 3 things to consider:

• Changing any calls to tracer.trace() to tracer.startSpan(). Since the latter doesn't propagate context automatically, make sure to use the childOf option of any child spans.
• Use the new scope manager to handle context propagation.
• There is no direct replacement for tracer.bind() and tracer.bindEmitter(), but they should no longer be needed in most cases. Please let us know if you were using them for anything that doesn't seem to be possible anymore and we'll work with you to find a solution with the new API.

For example:

Before

function handleRequest () {
  tracer.trace('web.request', parent => {
    getUsers(users => {
      parent.finish()
    })
  })
}

function getUsers (cb) {
  tracer.trace('sql.query', child => {
    child.finish()
    cb([])
  })
}

After

function handleRequest () {
  const parent = tracer.startSpan('web.request')

  tracer.scopeManager().activate(parent)

  getUsers(users => {
    parent.finish()
  })
}


function getUsers (cb) {
  const parent = tracer.scopeManager().active().span()
  const child = tracer.startSpan('sql.query', { childOf: parent })

  child.finish()
  cb([])
}