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 in Unity it becomes the parent span for other spans that start on the same thread. 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.

void Example()
{
    var span1 = BugsnagPerformance.StartSpan("span1");
    var span2 = BugsnagPerformance.StartSpan("span2");
    span2.End();
    span1.End();
    var 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", new SpanOptions { MakeCurrentContext = false });

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

void Example()
{
    var span1 = BugsnagPerformance.StartSpan("span1");
    var span2 = BugsnagPerformance.StartSpan("span2",
                                             new SpanOptions { MakeCurrentContext = false });
    var 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", new SpanOptions { 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", new SpanOptions { ParentContext = null });

Setting the context across threads

If you want operations on another thread to become child spans of the operation that spawns them (e.g. because an operation on the spawning thread is dependent on the spawned operations) then the current context must be passed to spawned threads when they are created so that spans inside the new thread become children of the parent operation.

In the example below, span2 would not be shown as a child of span1 without the additional span option:

private Span _span1;

void Example()
{
    _span1 = BugsnagPerformance.StartSpan("span1");
    new Thread(() => {
        var span2 = BugsnagPerformance.StartSpan("span2", new SpanOptions { ParentContext = _span1 });
    }).Start();
}

Without this, the spans in the thread are not connected to the context of the spawning operation.