feat(node): Add addLink(s) to span

s1gr1d · s1gr1d · commit aa1ab44f1cd3 · 2025-02-12T14:27:16.000+01:00
diff --git a/dev-packages/node-integration-tests/suites/tracing/linking/scenario-addLink.ts b/dev-packages/node-integration-tests/suites/tracing/linking/scenario-addLink.ts
@@ -0,0 +1,33 @@
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+import * as Sentry from '@sentry/node';
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  release: '1.0',
+  tracesSampleRate: 1.0,
+  integrations: [],
+  transport: loggingTransport,
+});
+
+// eslint-disable-next-line @typescript-eslint/no-floating-promises
+Sentry.startSpan({ name: 'parent1' }, async parentSpan1 => {
+  // eslint-disable-next-line @typescript-eslint/no-floating-promises
+  Sentry.startSpan({ name: 'child1.1' }, async childSpan1 => {
+    childSpan1.addLink({
+      context: parentSpan1.spanContext(),
+      attributes: { 'sentry.link.type': 'previous_trace' },
+    });
+
+    childSpan1.end();
+  });
+
+  // eslint-disable-next-line @typescript-eslint/no-floating-promises
+  Sentry.startSpan({ name: 'child1.2' }, async childSpan2 => {
+    childSpan2.addLink({
+      context: parentSpan1.spanContext(),
+      attributes: { 'sentry.link.type': 'previous_trace' },
+    });
+
+    childSpan2.end();
+  });
+});
diff --git a/dev-packages/node-integration-tests/suites/tracing/linking/scenario-addLinks.ts b/dev-packages/node-integration-tests/suites/tracing/linking/scenario-addLinks.ts
@@ -0,0 +1,31 @@
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+import * as Sentry from '@sentry/node';
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  release: '1.0',
+  tracesSampleRate: 1.0,
+  integrations: [],
+  transport: loggingTransport,
+});
+
+// eslint-disable-next-line @typescript-eslint/no-floating-promises
+Sentry.startSpan({ name: 'parent1' }, async parentSpan1 => {
+  // eslint-disable-next-line @typescript-eslint/no-floating-promises
+  Sentry.startSpan({ name: 'child1.1' }, async childSpan1 => {
+    // eslint-disable-next-line @typescript-eslint/no-floating-promises
+    Sentry.startSpan({ name: 'child2.1' }, async childSpan2 => {
+      childSpan2.addLinks([
+        { context: parentSpan1.spanContext() },
+        {
+          context: childSpan1.spanContext(),
+          attributes: { 'sentry.link.type': 'previous_trace' },
+        },
+      ]);
+
+      childSpan2.end();
+    });
+
+    childSpan1.end();
+  });
+});
diff --git a/dev-packages/node-integration-tests/suites/tracing/linking/test.ts b/dev-packages/node-integration-tests/suites/tracing/linking/test.ts
@@ -0,0 +1,75 @@
+import { createRunner } from '../../../utils/runner';
+
+// A general note regarding this test:
+// The fact that the trace_id and span_id are correctly linked is tested in a unit test
+
+describe('span links', () => {
+  test('should link spans with addLink()', done => {
+    createRunner(__dirname, 'scenario-addLink.ts')
+      .expect({
+        transaction: {
+          transaction: 'parent1',
+          spans: [
+            expect.objectContaining({
+              description: 'child1.1',
+              links: [
+                expect.objectContaining({
+                  trace_id: expect.any(String),
+                  span_id: expect.any(String),
+                  attributes: expect.objectContaining({
+                    'sentry.link.type': 'previous_trace',
+                  }),
+                }),
+              ],
+            }),
+            expect.objectContaining({
+              description: 'child1.2',
+              links: [
+                expect.objectContaining({
+                  trace_id: expect.any(String),
+                  span_id: expect.any(String),
+                  attributes: expect.objectContaining({
+                    'sentry.link.type': 'previous_trace',
+                  }),
+                }),
+              ],
+            }),
+          ],
+        },
+      })
+      .start(done);
+  });
+
+  test('should link spans with addLinks()', done => {
+    createRunner(__dirname, 'scenario-addLinks.ts')
+      .expect({
+        transaction: {
+          transaction: 'parent1',
+          spans: [
+            expect.objectContaining({
+              description: 'child1.1',
+              links: [],
+            }),
+            expect.objectContaining({
+              description: 'child2.1',
+              links: [
+                expect.not.objectContaining({ attributes: expect.anything() }) &&
+                  expect.objectContaining({
+                    trace_id: expect.any(String),
+                    span_id: expect.any(String),
+                  }),
+                expect.objectContaining({
+                  trace_id: expect.any(String),
+                  span_id: expect.any(String),
+                  attributes: expect.objectContaining({
+                    'sentry.link.type': 'previous_trace',
+                  }),
+                }),
+              ],
+            }),
+          ],
+        },
+      })
+      .start(done);
+  });
+});
diff --git a/packages/core/src/utils/spanUtils.ts b/packages/core/src/utils/spanUtils.ts
@@ -139,7 +139,7 @@ export function spanToJSON(span: Span): SpanJSON {
 
   // Handle a span from @opentelemetry/sdk-base-trace's `Span` class
   if (spanIsOpenTelemetrySdkTraceBaseSpan(span)) {
-    const { attributes, startTime, name, endTime, parentSpanId, status } = span;
+    const { attributes, startTime, name, endTime, parentSpanId, status, links } = span;
 
     return dropUndefinedKeys({
       span_id,
@@ -153,6 +153,7 @@ export function spanToJSON(span: Span): SpanJSON {
       status: getStatusMessage(status),
       op: attributes[SEMANTIC_ATTRIBUTE_SENTRY_OP],
       origin: attributes[SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN] as SpanOrigin | undefined,
+      links: links ? convertSpanLinksForEnvelope(links) : undefined,
     });
   }
 
@@ -179,6 +180,7 @@ export interface OpenTelemetrySdkTraceBaseSpan extends Span {
   status: SpanStatus;
   endTime: SpanTimeInput;
   parentSpanId?: string;
+  links?: SpanLink[];
 }
 
 /**
diff --git a/packages/core/test/lib/tracing/trace.test.ts b/packages/core/test/lib/tracing/trace.test.ts
@@ -1,3 +1,4 @@
+import type { SpanLink } from '@sentry/core';
 import {
   SEMANTIC_ATTRIBUTE_SENTRY_OP,
   SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
@@ -399,6 +400,40 @@ describe('startSpan', () => {
     });
   });
 
+  it('allows to pass span links', () => {
+    const rawSpan1 = startInactiveSpan({ name: 'pageload_span' });
+
+    // @ts-expect-error links exists on span
+    expect(rawSpan1?.links).toEqual([]);
+
+    const span1JSON = spanToJSON(rawSpan1);
+
+    startSpan({ name: '/users/:id' }, rawSpan2 => {
+      rawSpan2.addLink({
+        context: rawSpan1.spanContext(),
+        attributes: {
+          'sentry.link.type': 'previous_trace',
+        },
+      });
+
+      const span2LinkJSON = spanToJSON(rawSpan2).links?.[0];
+
+      expect(span2LinkJSON?.attributes?.['sentry.link.type']).toBe('previous_trace');
+
+      // @ts-expect-error links and _spanContext exist on span
+      expect((rawSpan2?.links as SpanLink[])?.[0].context.traceId).toEqual(rawSpan1._spanContext.traceId);
+      // @ts-expect-error links and _spanContext exist on span
+      expect((rawSpan2?.links as SpanLink[])?.[0].context.traceId).toEqual(span1JSON.trace_id);
+      expect(span2LinkJSON?.trace_id).toBe(span1JSON.trace_id);
+
+      // @ts-expect-error links and _spanContext exist on span
+      expect((rawSpan2?.links as SpanLink[])?.[0].context.spanId).toEqual(rawSpan1?._spanContext.spanId);
+      // @ts-expect-error links and _spanContext exist on span
+      expect((rawSpan2?.links as SpanLink[])?.[0].context.spanId).toEqual(span1JSON.span_id);
+      expect(span2LinkJSON?.span_id).toBe(span1JSON.span_id);
+    });
+  });
+
   it('allows to force a transaction with forceTransaction=true', async () => {
     const options = getDefaultTestClientOptions({ tracesSampleRate: 1.0 });
     client = new TestClient(options);
@@ -900,6 +935,40 @@ describe('startSpanManual', () => {
     });
   });
 
+  it('allows to pass span links', () => {
+    const rawSpan1 = startInactiveSpan({ name: 'pageload_span' });
+
+    // @ts-expect-error links exists on span
+    expect(rawSpan1?.links).toEqual([]);
+
+    const span1JSON = spanToJSON(rawSpan1);
+
+    startSpanManual({ name: '/users/:id' }, rawSpan2 => {
+      rawSpan2.addLink({
+        context: rawSpan1.spanContext(),
+        attributes: {
+          'sentry.link.type': 'previous_trace',
+        },
+      });
+
+      const span2LinkJSON = spanToJSON(rawSpan2).links?.[0];
+
+      expect(span2LinkJSON?.attributes?.['sentry.link.type']).toBe('previous_trace');
+
+      // @ts-expect-error links and _spanContext exist on span
+      expect((rawSpan2?.links as SpanLink[])?.[0].context.traceId).toEqual(rawSpan1._spanContext.traceId);
+      // @ts-expect-error links and _spanContext exist on span
+      expect((rawSpan2?.links as SpanLink[])?.[0].context.traceId).toEqual(span1JSON.trace_id);
+      expect(span2LinkJSON?.trace_id).toBe(span1JSON.trace_id);
+
+      // @ts-expect-error links and _spanContext exist on span
+      expect((rawSpan2?.links as SpanLink[])?.[0].context.spanId).toEqual(rawSpan1?._spanContext.spanId);
+      // @ts-expect-error links and _spanContext exist on span
+      expect((rawSpan2?.links as SpanLink[])?.[0].context.spanId).toEqual(span1JSON.span_id);
+      expect(span2LinkJSON?.span_id).toBe(span1JSON.span_id);
+    });
+  });
+
   it('allows to force a transaction with forceTransaction=true', async () => {
     const options = getDefaultTestClientOptions({ tracesSampleRate: 1.0 });
     client = new TestClient(options);
diff --git a/packages/opentelemetry/src/spanExporter.ts b/packages/opentelemetry/src/spanExporter.ts
@@ -11,6 +11,7 @@ import type {
   TransactionEvent,
   TransactionSource,
 } from '@sentry/core';
+import { convertSpanLinksForEnvelope } from '@sentry/core';
 import {
   SEMANTIC_ATTRIBUTE_SENTRY_CUSTOM_SPAN_NAME,
   SEMANTIC_ATTRIBUTE_SENTRY_OP,
@@ -322,7 +323,7 @@ function createAndFinishSpanForOtelSpan(node: SpanNode, spans: SpanJSON[], sentS
   const span_id = span.spanContext().spanId;
   const trace_id = span.spanContext().traceId;
 
-  const { attributes, startTime, endTime, parentSpanId } = span;
+  const { attributes, startTime, endTime, parentSpanId, links } = span;
 
   const { op, description, data, origin = 'manual' } = getSpanData(span);
   const allData = dropUndefinedKeys({
@@ -347,6 +348,7 @@ function createAndFinishSpanForOtelSpan(node: SpanNode, spans: SpanJSON[], sentS
     op,
     origin,
     measurements: timedEventsToMeasurements(span.events),
+    links: links ? convertSpanLinksForEnvelope(links) : undefined,
   });
 
   spans.push(spanJSON);
diff --git a/packages/opentelemetry/test/trace.test.ts b/packages/opentelemetry/test/trace.test.ts
@@ -20,7 +20,7 @@ import {
   suppressTracing,
   withScope,
 } from '@sentry/core';
-import type { Event, Scope } from '@sentry/core';
+import type { Event, Scope, SpanLink } from '@sentry/core';
 
 import { SEMATTRS_HTTP_METHOD } from '@opentelemetry/semantic-conventions';
 import { continueTrace, startInactiveSpan, startSpan, startSpanManual } from '../src/trace';
@@ -356,6 +356,40 @@ describe('trace', () => {
       });
     });
 
+    it('allows to pass span links', () => {
+      const rawSpan1 = startInactiveSpan({ name: 'pageload_span' });
+
+      // @ts-expect-error links exists on span
+      expect(rawSpan1?.links).toEqual([]);
+
+      const span1JSON = spanToJSON(rawSpan1);
+
+      startSpan({ name: '/users/:id' }, rawSpan2 => {
+        rawSpan2.addLink({
+          context: rawSpan1.spanContext(),
+          attributes: {
+            'sentry.link.type': 'previous_trace',
+          },
+        });
+
+        const span2LinkJSON = spanToJSON(rawSpan2).links?.[0];
+
+        expect(span2LinkJSON?.attributes?.['sentry.link.type']).toBe('previous_trace');
+
+        // @ts-expect-error links and _spanContext exist on span
+        expect((rawSpan2?.links as SpanLink[])?.[0].context.traceId).toEqual(rawSpan1._spanContext.traceId);
+        // @ts-expect-error links and _spanContext exist on span
+        expect((rawSpan2?.links as SpanLink[])?.[0].context.traceId).toEqual(span1JSON.trace_id);
+        expect(span2LinkJSON?.trace_id).toBe(span1JSON.trace_id);
+
+        // @ts-expect-error links and _spanContext exist on span
+        expect((rawSpan2?.links as SpanLink[])?.[0].context.spanId).toEqual(rawSpan1?._spanContext.spanId);
+        // @ts-expect-error links and _spanContext exist on span
+        expect((rawSpan2?.links as SpanLink[])?.[0].context.spanId).toEqual(span1JSON.span_id);
+        expect(span2LinkJSON?.span_id).toBe(span1JSON.span_id);
+      });
+    });
+
     it('allows to force a transaction with forceTransaction=true', async () => {
       const client = getClient()!;
       const transactionEvents: Event[] = [];
@@ -906,6 +940,40 @@ describe('trace', () => {
       });
     });
 
+    it('allows to pass span links', () => {
+      const rawSpan1 = startInactiveSpan({ name: 'pageload_span' });
+
+      // @ts-expect-error links exists on span
+      expect(rawSpan1?.links).toEqual([]);
+
+      const span1JSON = spanToJSON(rawSpan1);
+
+      startSpanManual({ name: '/users/:id' }, rawSpan2 => {
+        rawSpan2.addLink({
+          context: rawSpan1.spanContext(),
+          attributes: {
+            'sentry.link.type': 'previous_trace',
+          },
+        });
+
+        const span2LinkJSON = spanToJSON(rawSpan2).links?.[0];
+
+        expect(span2LinkJSON?.attributes?.['sentry.link.type']).toBe('previous_trace');
+
+        // @ts-expect-error links and _spanContext exist on span
+        expect((rawSpan2?.links as SpanLink[])?.[0].context.traceId).toEqual(rawSpan1._spanContext.traceId);
+        // @ts-expect-error links and _spanContext exist on span
+        expect((rawSpan2?.links as SpanLink[])?.[0].context.traceId).toEqual(span1JSON.trace_id);
+        expect(span2LinkJSON?.trace_id).toBe(span1JSON.trace_id);
+
+        // @ts-expect-error links and _spanContext exist on span
+        expect((rawSpan2?.links as SpanLink[])?.[0].context.spanId).toEqual(rawSpan1?._spanContext.spanId);
+        // @ts-expect-error links and _spanContext exist on span
+        expect((rawSpan2?.links as SpanLink[])?.[0].context.spanId).toEqual(span1JSON.span_id);
+        expect(span2LinkJSON?.span_id).toBe(span1JSON.span_id);
+      });
+    });
+
     it('allows to force a transaction with forceTransaction=true', async () => {
       const client = getClient()!;
       const transactionEvents: Event[] = [];
