Maintaining span context

When viewing a single instance of a span in the BugSnag dashboard, a waterfall diagram will show you that instance’s children and their children, and so on, where the children are spans started from within the context of their parent. This page describes the tools available in the SDK to control these parent-child relationships.

Automatic context creation

By default, when a span is created it becomes the parent span for other spans that start after it. We call this parent span the “current span context” and it remains until it is ended or another span becomes the current context.

For example, in the following snippet span1 becomes the current span context and span2 automatically becomes a child of span1. span3 then becomes the new current context, but with no parent span because span1 and span2 have already ended.

let span1 = BugsnagPerformance.startSpan("span1");
let span2 = BugsnagPerformance.startSpan("span2");
span2.end();
span1.end();
let span3 = BugsnagPerformance.startSpan("span3");
span3.end();

Preventing new contexts

To prevent a span becoming the new current context when it is created, and so being the parent of future spans, set the makeCurrentContext span option:

BugsnagPerformance.startSpan("childless", { makeCurrentContext: false });

For example, in the following snippet span1 becomes the parent of both span2 and span3:

let span1 = BugsnagPerformance.startSpan("span1");
let span2 = BugsnagPerformance.startSpan("span2", { makeCurrentContext: false });
let span3 = BugsnagPerformance.startSpan("span3");
span3.end();
span2.end();
span1.end();

Setting contexts manually

You can set a parent of a span manually using the parentContext span option:

BugsnagPerformance.startSpan("child-span", { parentContext: manualParentSpan });

If a span is known to be independent of any other open spans, you can also set the parentContext span option to null, which will prevent it becoming a child:

BugsnagPerformance.startSpan("top-level", { parentContext: null });

Setting the context in async methods and promises

The current span context is stored globally, therefore when starting spans in async methods and promises it is important to set the makeCurrentContext span option to false to prevent spans from automatically becoming the current context outside of the async operation.

We also recommend using the parentContext span option to ensure that async spans become children of the parent operation, as it may not be the current context by the time the task is executed.

For example in the following snippet, without the additional options the spans in each task would become children of each other based on order of execution:

const parentSpan = BugsnagPerformance.startSpan('parent-span');

const task = async (value) => {
  const taskSpan = BugsnagPerformance.startSpan('task-span', {
    makeCurrentContext: false,
    parentContext: parentSpan
  });
  // do some work
  taskSpan.end();
}

const tasks = collection.map(value => task(value))
Promise.all(tasks).finally(() => {
  // close the parent span when all tasks are complete
  parentSpan.end()
});