feat: start a root span with spanOptions.parent = null (open-telemetry#889)

* feat: start a root span with spanOptions.parent = null

* chore: lint

* chore: add return type for readability

Author: dyladan

packages/opentelemetry-api/src/trace/SpanOptions.ts

@@ -44,6 +44,9 @@ export interface SpanOptions {
    * A parent `SpanContext` (or `Span`, for convenience) that the newly-started
    * span will be the child of. This overrides the parent span extracted from
    * the currently active context.
+   *
+   * A null value here should prevent the SDK from extracting a parent from
+   * the current context, forcing the new span to be a root span.
    */
   parent?: Span | SpanContext | null;
 

packages/opentelemetry-tracing/src/Tracer.ts

@@ -66,9 +66,7 @@ export class Tracer implements api.Tracer {
     options: api.SpanOptions = {},
     context = api.context.active()
   ): api.Span {
-    const parentContext = options.parent
-      ? getContext(options.parent)
-      : getParentSpanContext(context);
+    const parentContext = getParent(options, context);
     // make sampling decision
     const samplingDecision = this._sampler.shouldSample(parentContext);
     const spanId = randomSpanId();
@@ -149,6 +147,22 @@ export class Tracer implements api.Tracer {
   }
 }
 
+/**
+ * Get the parent to assign to a started span. If options.parent is null,
+ * do not assign a parent.
+ *
+ * @param options span options
+ * @param context context to check for parent
+ */
+function getParent(
+  options: api.SpanOptions,
+  context: api.Context
+): api.SpanContext | undefined {
+  if (options.parent === null) return undefined;
+  if (options.parent) return getContext(options.parent);
+  return getParentSpanContext(context);
+}
+
 function getContext(span: api.Span | api.SpanContext) {
   return isSpan(span) ? span.context() : span;
 }

packages/opentelemetry-tracing/test/BasicTracerProvider.test.ts

@@ -239,6 +239,21 @@ describe('BasicTracerProvider', () => {
       childSpan.end();
     });
 
+    it('should create a root span when parent is null', () => {
+      const tracer = new BasicTracerProvider().getTracer('default');
+      const span = tracer.startSpan('my-span');
+      const overrideParent = tracer.startSpan('my-parent-override-span');
+      const rootSpan = tracer.startSpan(
+        'root-span',
+        { parent: null },
+        setActiveSpan(Context.ROOT_CONTEXT, span)
+      );
+      const context = rootSpan.context();
+      assert.notStrictEqual(context.traceId, overrideParent.context().traceId);
+      span.end();
+      rootSpan.end();
+    });
+
     it('should start a span with name and with invalid parent span', () => {
       const tracer = new BasicTracerProvider().getTracer('default');
       const span = tracer.startSpan(