feat(sdk-trace-base)!: Add parentSpanContext and remove parentSpanId

CHANGELOG.md

@@ -11,6 +11,8 @@ For semantic convention package changes, see the [semconv CHANGELOG](packages/se
 
 ### :boom: Breaking Change
 
+* feat(sdk-trace-base)!: Add `parentSpanContext` and remove `parentSpanId` from `Span` and `ReadableSpan` [#5450](/~https://github.com/open-telemetry/opentelemetry-js/pull/5450) @JacksonWeber
+  * (user-facing): the SDK's `Span`s `parentSpanId` was replaced by `parentSpanContext`, to migrate to the new property, please replace `span.parentSpanId` -> `span.parentSpanContext?.spanId`
 * feat(sdk-metrics)!: drop deprecated `type` field on `MetricDescriptor` [#5291](/~https://github.com/open-telemetry/opentelemetry-js/pull/5291) @chancancode
 * feat(sdk-metrics)!: drop deprecated `InstrumentDescriptor` type; use `MetricDescriptor` instead [#5277](/~https://github.com/open-telemetry/opentelemetry-js/pull/5266) @chancancode
 * feat(sdk-metrics)!: bump minimum version of `@opentelemetry/api` peer dependency to 1.9.0 [#5254](/~https://github.com/open-telemetry/opentelemetry-js/pull/5254) @chancancode

experimental/packages/opentelemetry-instrumentation-fetch/test/fetch.test.ts

@@ -400,7 +400,7 @@ describe('fetch', () => {
           const span: tracing.ReadableSpan = exportedSpans[0];
 
           assert.strictEqual(
-            span.parentSpanId,
+            span.parentSpanContext?.spanId,
             rootSpan!.spanContext().spanId,
             'parent span is not root span'
           );
@@ -775,7 +775,7 @@ describe('fetch', () => {
           const span: tracing.ReadableSpan = exportedSpans[0];
 
           assert.strictEqual(
-            span.parentSpanId,
+            span.parentSpanContext?.spanId,
             rootSpan!.spanContext().spanId,
             'parent span is not root span'
           );
@@ -1492,7 +1492,7 @@ describe('fetch', () => {
           const span: tracing.ReadableSpan = exportedSpans[0];
 
           assert.strictEqual(
-            span.parentSpanId,
+            span.parentSpanContext?.spanId,
             rootSpan!.spanContext().spanId,
             'parent span is not root span'
           );
@@ -1542,7 +1542,7 @@ describe('fetch', () => {
           const span: tracing.ReadableSpan = exportedSpans[0];
 
           assert.strictEqual(
-            span.parentSpanId,
+            span.parentSpanContext?.spanId,
             rootSpan!.spanContext().spanId,
             'parent span is not root span'
           );
@@ -1624,7 +1624,7 @@ describe('fetch', () => {
           const span: tracing.ReadableSpan = exportedSpans[0];
 
           assert.strictEqual(
-            span.parentSpanId,
+            span.parentSpanContext?.spanId,
             rootSpan!.spanContext().spanId,
             'parent span is not root span'
           );
@@ -1723,7 +1723,7 @@ describe('fetch', () => {
             const span: tracing.ReadableSpan = exportedSpans[0];
 
             assert.strictEqual(
-              span.parentSpanId,
+              span.parentSpanContext?.spanId,
               rootSpan!.spanContext().spanId,
               'parent span is not root span'
             );
@@ -1781,7 +1781,7 @@ describe('fetch', () => {
             const span: tracing.ReadableSpan = exportedSpans[0];
 
             assert.strictEqual(
-              span.parentSpanId,
+              span.parentSpanContext?.spanId,
               rootSpan!.spanContext().spanId,
               'parent span is not root span'
             );

experimental/packages/opentelemetry-instrumentation-grpc/test/helper.ts

@@ -622,7 +622,7 @@ export const runTests = (
                 );
                 assert.strictEqual(
                   rootSpan.spanContext().spanId,
-                  clientSpan.parentSpanId
+                  clientSpan.parentSpanContext?.spanId
                 );
               }
             })
@@ -740,7 +740,7 @@ export const runTests = (
               );
               assert.strictEqual(
                 rootSpan.spanContext().spanId,
-                clientSpan.parentSpanId
+                clientSpan.parentSpanContext?.spanId
               );
             });
         });

experimental/packages/opentelemetry-instrumentation-grpc/test/protobuf-ts-utils.ts

@@ -103,6 +103,9 @@ export function assertExportedSpans(
       rootSpan?.spanContext().traceId,
       serverSpan.spanContext().traceId
     );
-    assert.strictEqual(rootSpan?.spanContext().spanId, clientSpan.parentSpanId);
+    assert.strictEqual(
+      rootSpan?.spanContext().spanId,
+      clientSpan.parentSpanContext?.spanId
+    );
   }
 }

experimental/packages/opentelemetry-instrumentation-grpc/test/utils/assertionUtils.ts

@@ -99,7 +99,10 @@ export const assertPropagation = (
   const targetSpanContext = incomingSpan.spanContext();
   const sourceSpanContext = outgoingSpan.spanContext();
   assert.strictEqual(targetSpanContext.traceId, sourceSpanContext.traceId);
-  assert.strictEqual(incomingSpan.parentSpanId, sourceSpanContext.spanId);
+  assert.strictEqual(
+    incomingSpan.parentSpanContext?.spanId,
+    sourceSpanContext.spanId
+  );
   assert.strictEqual(
     targetSpanContext.traceFlags,
     sourceSpanContext.traceFlags

experimental/packages/opentelemetry-instrumentation-http/test/utils/assertSpan.ts

@@ -185,8 +185,8 @@ export const assertSpan = (
       validations.component,
       ' must have http.scheme attribute'
     );
-    assert.ok(typeof span.parentSpanId === 'string');
-    assert.ok(isValidSpanId(span.parentSpanId));
+    assert.ok(typeof span.parentSpanContext?.spanId === 'string');
+    assert.ok(isValidSpanId(span.parentSpanContext.spanId));
   } else if (validations.reqHeaders) {
     assert.ok(validations.reqHeaders[DummyPropagation.TRACE_CONTEXT_KEY]);
     assert.ok(validations.reqHeaders[DummyPropagation.SPAN_CONTEXT_KEY]);

experimental/packages/opentelemetry-instrumentation-xml-http-request/test/xhr.test.ts

@@ -388,7 +388,7 @@ describe('xhr', () => {
         it('should create a span with correct root span', () => {
           const span: tracing.ReadableSpan = exportSpy.args[1][0][0];
           assert.strictEqual(
-            span.parentSpanId,
+            span.parentSpanContext?.spanId,
             rootSpan.spanContext().spanId,
             'parent span is not root span'
           );
@@ -492,7 +492,7 @@ describe('xhr', () => {
           const span: tracing.ReadableSpan = exportSpy.args[0][0][0];
           const parentSpan: tracing.ReadableSpan = exportSpy.args[1][0][0];
           assert.strictEqual(
-            span.parentSpanId,
+            span.parentSpanContext?.spanId,
             parentSpan.spanContext().spanId,
             'parent span is not root span'
           );
@@ -1586,7 +1586,7 @@ describe('xhr', () => {
         it('should create a span with correct root span', () => {
           const span: tracing.ReadableSpan = exportSpy.args[1][0][0];
           assert.strictEqual(
-            span.parentSpanId,
+            span.parentSpanContext?.spanId,
             rootSpan.spanContext().spanId,
             'parent span is not root span'
           );
@@ -1690,7 +1690,7 @@ describe('xhr', () => {
           const span: tracing.ReadableSpan = exportSpy.args[0][0][0];
           const parentSpan: tracing.ReadableSpan = exportSpy.args[1][0][0];
           assert.strictEqual(
-            span.parentSpanId,
+            span.parentSpanContext?.spanId,
             parentSpan.spanContext().spanId,
             'parent span is not root span'
           );

experimental/packages/otlp-transformer/src/trace/internal.ts

@@ -37,10 +37,13 @@ import { getOtlpEncoder } from '../common/utils';
 export function sdkSpanToOtlpSpan(span: ReadableSpan, encoder: Encoder): ISpan {
   const ctx = span.spanContext();
   const status = span.status;
+  const parentSpanId = span.parentSpanContext?.spanId
+    ? encoder.encodeSpanContext(span.parentSpanContext?.spanId)
+    : undefined;
   return {
     traceId: encoder.encodeSpanContext(ctx.traceId),
     spanId: encoder.encodeSpanContext(ctx.spanId),
-    parentSpanId: encoder.encodeOptionalSpanContext(span.parentSpanId),
+    parentSpanId: parentSpanId,
     traceState: ctx.traceState?.serialize(),
     name: span.name,
     // Span kind is offset by 1 because the API does not define a value for unset

experimental/packages/otlp-transformer/test/trace.test.ts

@@ -26,6 +26,7 @@ import { createExportTraceServiceRequest } from '../src/trace/internal';
 import { ProtobufTraceSerializer } from '../src/trace/protobuf';
 import { JsonTraceSerializer } from '../src/trace/json';
 import { hexToBinary } from '../src/common/hex-to-binary';
+import { ISpan } from '../src/trace/internal-types';
 
 function createExpectedSpanJson(options: OtlpEncodingOptions) {
   const useHex = options.useHex ?? false;
@@ -245,7 +246,11 @@ describe('Trace', () => {
         isRemote: false,
         traceState: new TraceState('span=bar'),
       }),
-      parentSpanId: '0000000000000001',
+      parentSpanContext: {
+        spanId: '0000000000000001',
+        traceId: '00000000000000000000000000000001',
+        traceFlags: TraceFlags.SAMPLED,
+      },
       attributes: { 'string-attribute': 'some attribute value' },
       duration: [1, 300000000],
       endTime: [1640715558, 642725388],
@@ -331,25 +336,27 @@ describe('Trace', () => {
     });
 
     it('serializes a span without a parent with useHex = true', () => {
-      (span as any).parentSpanId = undefined;
+      (span as any).parentSpanContext.spanId = undefined;
       const exportRequest = createExportTraceServiceRequest([span], {
         useHex: true,
       });
       assert.ok(exportRequest);
       assert.strictEqual(
-        exportRequest.resourceSpans?.[0].scopeSpans[0].spans?.[0].parentSpanId,
+        (exportRequest.resourceSpans?.[0].scopeSpans[0].spans?.[0] as ISpan)
+          .parentSpanId,
         undefined
       );
     });
 
     it('serializes a span without a parent with useHex = false', () => {
-      (span as any).parentSpanId = undefined;
+      (span as any).parentSpanContext.spanId = undefined;
       const exportRequest = createExportTraceServiceRequest([span], {
         useHex: false,
       });
       assert.ok(exportRequest);
       assert.strictEqual(
-        exportRequest.resourceSpans?.[0].scopeSpans[0].spans?.[0].parentSpanId,
+        (exportRequest.resourceSpans?.[0].scopeSpans[0].spans?.[0] as ISpan)
+          .parentSpanId,
         undefined
       );
     });
@@ -448,7 +455,6 @@ describe('Trace', () => {
         root.opentelemetry.proto.collector.trace.v1.ExportTraceServiceRequest.decode(
           serialized
         );
-
       const expected = createExpectedSpanProtobuf();
       const decodedObj =
         root.opentelemetry.proto.collector.trace.v1.ExportTraceServiceRequest.toObject(
@@ -463,7 +469,6 @@ describe('Trace', () => {
             bytes: String,
           }
         );
-
       assert.deepStrictEqual(decodedObj, expected);
     });
 

experimental/packages/shim-opencensus/test/ShimSpan.test.ts

@@ -107,7 +107,7 @@ describe('ShimSpan', () => {
 
       assert.strictEqual(childSpan.name, 'span');
       assert.deepStrictEqual(
-        childSpan.parentSpanId,
+        childSpan.parentSpanContext?.spanId,
         parentSpan.spanContext().spanId
       );
     });
@@ -120,7 +120,7 @@ describe('ShimSpan', () => {
 
       assert.strictEqual(childSpan.name, 'child');
       assert.deepStrictEqual(
-        childSpan.parentSpanId,
+        childSpan.parentSpanContext?.spanId,
         parentSpan.spanContext().spanId
       );
     });

experimental/packages/shim-opencensus/test/ShimTracer.test.ts

@@ -92,7 +92,10 @@ describe('ShimTracer', () => {
         otelSpans[0].spanContext().traceId,
         '9e7ecdc193765065fee1efe757fdd874'
       );
-      assert.strictEqual(otelSpans[0].parentSpanId, '4bf6239d37d8b0f0');
+      assert.strictEqual(
+        otelSpans[0].parentSpanContext?.spanId,
+        '4bf6239d37d8b0f0'
+      );
     });
 
     it('should set the span as root span in context', async () => {
@@ -154,7 +157,7 @@ describe('ShimTracer', () => {
         parent.end();
       });
       assert.strictEqual(
-        childSpan.parentSpanId,
+        childSpan.parentSpanContext?.spanId,
         parentSpan.spanContext().spanId
       );
     });
@@ -171,7 +174,10 @@ describe('ShimTracer', () => {
           }
         );
       });
-      assert.strictEqual(childSpan.parentSpanId, rootSpan.spanContext().spanId);
+      assert.strictEqual(
+        childSpan.parentSpanContext?.spanId,
+        rootSpan.spanContext().spanId
+      );
     });
   });
 

experimental/packages/shim-opencensus/test/otel-sandwich.test.ts

@@ -38,7 +38,10 @@ describe('OpenTelemetry sandwich', () => {
       childSpan.spanContext().traceId,
       parentSpan.spanContext().traceId
     );
-    assert.strictEqual(childSpan.parentSpanId, parentSpan.spanContext().spanId);
+    assert.strictEqual(
+      childSpan.parentSpanContext?.spanId,
+      parentSpan.spanContext().spanId
+    );
   });
 
   it('should maintain parent-child relationship for OC -> OTel', async () => {
@@ -55,7 +58,10 @@ describe('OpenTelemetry sandwich', () => {
       childSpan.spanContext().traceId,
       parentSpan.spanContext().traceId
     );
-    assert.strictEqual(childSpan.parentSpanId, parentSpan.spanContext().spanId);
+    assert.strictEqual(
+      childSpan.parentSpanContext?.spanId,
+      parentSpan.spanContext().spanId
+    );
   });
 
   it('should maintain structure for OTel -> OC -> OTel', async () => {
@@ -80,9 +86,12 @@ describe('OpenTelemetry sandwich', () => {
       parentSpan.spanContext().traceId
     );
     assert.strictEqual(
-      middleSpan.parentSpanId,
+      middleSpan.parentSpanContext?.spanId,
       parentSpan.spanContext().spanId
     );
-    assert.strictEqual(childSpan.parentSpanId, middleSpan.spanContext().spanId);
+    assert.strictEqual(
+      childSpan.parentSpanContext?.spanId,
+      middleSpan.spanContext().spanId
+    );
   });
 });

packages/opentelemetry-exporter-jaeger/src/transform.ts

@@ -43,8 +43,8 @@ export function spanToThrift(span: ReadableSpan): ThriftSpan {
   const traceId = span.spanContext().traceId.padStart(32, '0');
   const traceIdHigh = traceId.slice(0, 16);
   const traceIdLow = traceId.slice(16);
-  const parentSpan = span.parentSpanId
-    ? Utils.encodeInt64(span.parentSpanId)
+  const parentSpan = span.parentSpanContext?.spanId
+    ? Utils.encodeInt64(span.parentSpanContext.spanId)
     : ThriftUtils.emptyBuffer;
 
   const tags = Object.keys(span.attributes).map(

packages/opentelemetry-exporter-jaeger/test/transform.test.ts

@@ -237,7 +237,11 @@ describe('transform', () => {
           code: api.SpanStatusCode.OK,
         },
         attributes: {},
-        parentSpanId: '3e0c63257de34c92',
+        parentSpanContext: {
+          traceId: 'a4cda95b652f4a1592b449d5929fda1b',
+          spanId: '3e0c63257de34c92',
+          traceFlags: TraceFlags.SAMPLED,
+        },
         links: [
           {
             context: {

packages/opentelemetry-exporter-zipkin/src/transform.ts

@@ -43,7 +43,7 @@ export function toZipkinSpan(
 ): zipkinTypes.Span {
   const zipkinSpan: zipkinTypes.Span = {
     traceId: span.spanContext().traceId,
-    parentId: span.parentSpanId,
+    parentId: span.parentSpanContext?.spanId,
     name: span.name,
     id: span.spanContext().spanId,
     kind: ZIPKIN_SPAN_KIND_MAPPING[span.kind],