Skip to main content
The Scope manager enables manual context propagation. It tracks which span is currently active and allows you to activate spans across async boundaries. In most cases you do not need to interact with the scope manager directly — tracer.trace() and tracer.wrap() handle scope management automatically. Use the scope manager directly only for edge cases such as internal queues or timer-based callbacks where the async context is lost. 
const tracer = require('dd-trace').init()
const scope = tracer.scope()

​
Methods

​
active()

Returns the currently active span, or null if there is no active span. 
active(): Span | null
​
returns
Span | null
The active Span in the current async context, or null if none.
const span = tracer.scope().active()
if (span) {
  span.setTag('user.id', userId)
}

​
activate(span, fn)

Activates the provided span in the scope of a function. Any asynchronous context created from within the function will also have the same scope. 
activate<T>(span: Span, fn: (...args: any[]) => T): T
​
span
Span
required
The span to activate.
​
fn
Function
required
The function to execute with the span activated on its scope.
​
returns
T
The return value of fn.
const tracer = require('dd-trace').init()
const scope = tracer.scope()

const requestSpan = tracer.startSpan('web.request')

scope.activate(requestSpan, () => {
  console.log(scope.active()) // requestSpan

  // Any async operations here inherit the scope
  setTimeout(() => {
    console.log(scope.active()) // requestSpan
  })

  Promise.resolve().then(() => {
    console.log(scope.active()) // requestSpan
  })
})

console.log(scope.active()) // null — outside the activate() call

​
bind(target, span?)

Binds a function or Promise to the provided span. When the bound target is called or resolved, the given span will be the active span in that context. 
bind<T extends (...args: any[]) => void>(fn: T, span?: Span | null): T
bind<V, T extends (...args: any[]) => V>(fn: T, span?: Span | null): T
bind<T>(fn: Promise<T>, span?: Span | null): Promise<T>
​
target
Function | Promise
required
The function or Promise to bind.
​
span
Span | null
The span to bind to. If omitted, the currently active span at the time bind() is called is used. Explicitly passing null binds to no span.
​
returns
Function | Promise
The bound target, with the same type as the input.
const tracer = require('dd-trace').init()
const scope = tracer.scope()

const outerSpan = tracer.startSpan('web.request')

scope.activate(outerSpan, () => {
  const innerSpan = tracer.startSpan('web.middleware')

  // Explicitly bound to innerSpan
  const boundToInner = scope.bind(() => {
    console.log(scope.active()) // innerSpan
  }, innerSpan)

  // Implicitly bound to outerSpan (current active at bind time)
  const boundToOuter = scope.bind(() => {
    console.log(scope.active()) // outerSpan
  })

  boundToInner()
  boundToOuter()
})
Explicitly passing null as the span binds to no span. The bound function will see scope.active() return null when called.

Build docs developers (and LLMs) love

Get started for freeTalk to us