feat(core): Create types and utilities for span links

packages/core/src/index.ts

@@ -76,6 +76,7 @@ export { handleCallbackErrors } from './utils/handleCallbackErrors';
 export { parameterize } from './utils/parameterize';
 export { addAutoIpAddressToSession, addAutoIpAddressToUser } from './utils/ipAddress';
 export {
+ convertSpanLinksForEnvelope,
  spanToTraceHeader,
  spanToJSON,
  spanIsSampled,

packages/core/src/tracing/sentryNonRecordingSpan.ts

@@ -69,24 +69,12 @@ export class SentryNonRecordingSpan implements Span {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but we need it for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLink(_link: unknown): this {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but we need it for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLinks(_links: unknown[]): this {
  return this;
  }

packages/core/src/tracing/sentrySpan.ts

@@ -109,24 +109,12 @@ export class SentrySpan implements Span {
  }
  }
 
- /**
- * This should generally not be used,
- * but it is needed for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLink(_link: unknown): this {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but it is needed for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLinks(_links: unknown[]): this {
  return this;
  }

packages/core/src/types-hoist/link.ts

@@ -0,0 +1,30 @@
+import type { SpanAttributeValue, SpanContextData } from './span';
+
+type SpanLinkAttributes = {
+ /**
+ * Setting the link type to 'previous_trace' helps the Sentry product linking to the previous trace
+ */
+ 'sentry.link.type'?: string | 'previous_trace';
+} & Record<string, SpanAttributeValue | undefined>;
+
+export interface SpanLink {
+ /**
+ * Contains the SpanContext of the span to link to
+ */
+ context: SpanContextData;
+ /**
+ * A key-value pair with primitive values or an array of primitive values
+ */
+ attributes?: SpanLinkAttributes;
+}
+
+/**
+ * Link interface for the event envelope item. It's a flattened representation of `SpanLink`.
+ * Can include additional fields defined by OTel.
+ */
+export interface SpanLinkJSON extends Record<string, unknown> {
+ span_id: string;
+ trace_id: string;
+ sampled?: boolean;
+ attributes?: SpanLinkAttributes;
+}

packages/core/src/types-hoist/span.ts

@@ -1,3 +1,4 @@
+import type { SpanLink, SpanLinkJSON } from './link';
 import type { Measurements } from './measurement';
 import type { HrTime } from './opentelemetry';
 import type { SpanStatus } from './spanStatus';
@@ -50,6 +51,7 @@ export interface SpanJSON {
  measurements?: Measurements;
  is_segment?: boolean;
  segment_id?: string;
+ links?: SpanLinkJSON[];
 }
 
 // These are aligned with OpenTelemetry trace flags
@@ -249,14 +251,21 @@ export interface Span {
  addEvent(name: string, attributesOrStartTime?: SpanAttributes | SpanTimeInput, startTime?: SpanTimeInput): this;
 
  /**
- * NOT USED IN SENTRY, only added for compliance with OTEL Span interface
+ * Associates this span with a related span. Links can reference spans from the same or different trace
+ * and are typically used for batch operations, cross-trace scenarios, or scatter/gather patterns.
+ *
+ * Prefer setting links directly when starting a span (e.g. `Sentry.startSpan()`) as some context information is only available during span creation.
+ * @param link - The link containing the context of the span to link to and optional attributes
  */
- addLink(link: unknown): this;
+ addLink(link: SpanLink): this;
 
  /**
- * NOT USED IN SENTRY, only added for compliance with OTEL Span interface
+ * Associates this span with multiple related spans. See {@link addLink} for more details.
+ *
+ * Prefer setting links directly when starting a span (e.g. `Sentry.startSpan()`) as some context information is only available during span creation.
+ * @param links - Array of links to associate with this span
  */
- addLinks(links: unknown): this;
+ addLinks(links: SpanLink[]): this;
 
  /**
  * NOT USED IN SENTRY, only added for compliance with OTEL Span interface

packages/core/src/utils/spanUtils.ts

@@ -19,6 +19,7 @@ import type {
  SpanTimeInput,
  TraceContext,
 } from '../types-hoist';
+import type { SpanLink, SpanLinkJSON } from '../types-hoist/link';
 import { consoleSandbox } from '../utils-hoist/logger';
 import { addNonEnumerableProperty, dropUndefinedKeys } from '../utils-hoist/object';
 import { generateSpanId } from '../utils-hoist/propagationContext';
@@ -81,6 +82,25 @@ export function spanToTraceHeader(span: Span): string {
  return generateSentryTraceHeader(traceId, spanId, sampled);
 }
 
+/**
+ * Converts the span links array to a flattened version to be sent within an envelope.
+ *
+ * If the links array is empty, it returns `undefined` so the empty value can be dropped before it's sent.
+ */
+export function convertSpanLinksForEnvelope(links?: SpanLink[]): SpanLinkJSON[] | undefined {
+ if (links && links.length > 0) {
+ return links.map(({ context: { spanId, traceId, traceFlags, ...restContext }, attributes }) => ({
+ span_id: spanId,
+ trace_id: traceId,
+ sampled: traceFlags === TRACE_FLAG_SAMPLED,
+ attributes,
+ ...restContext,
+ }));
+ } else {
+ return undefined;
+ }
+}
+
 /**
  * Convert a span time input into a timestamp in seconds.
  */

packages/core/test/lib/utils/spanUtils.test.ts

@@ -7,14 +7,17 @@ import {
  SPAN_STATUS_UNSET,
  SentrySpan,
  TRACEPARENT_REGEXP,
+ convertSpanLinksForEnvelope,
  setCurrentClient,
  spanToTraceHeader,
  startInactiveSpan,
  startSpan,
  timestampInSeconds,
 } from '../../../src';
 import type { Span, SpanAttributes, SpanStatus, SpanTimeInput } from '../../../src/types-hoist';
+import type { SpanLink } from '../../../src/types-hoist/link';
 import type { OpenTelemetrySdkTraceBaseSpan } from '../../../src/utils/spanUtils';
+import { TRACE_FLAG_NONE, TRACE_FLAG_SAMPLED } from '../../../src/utils/spanUtils';
 import {
  getRootSpan,
  spanIsSampled,
@@ -156,6 +159,115 @@ describe('spanToTraceContext', () => {
  });
 });
 
+describe('convertSpanLinksForEnvelope', () => {
+ it('returns undefined for undefined input', () => {
+ expect(convertSpanLinksForEnvelope(undefined)).toBeUndefined();
+ });
+
+ it('returns undefined for empty array input', () => {
+ expect(convertSpanLinksForEnvelope([])).toBeUndefined();
+ });
+
+ it('converts a single span link to a flattened envelope item', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ ]);
+ });
+
+ it('converts multiple span links to a flattened envelope item', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ {
+ context: {
+ spanId: 'span2',
+ traceId: 'trace2',
+ traceFlags: TRACE_FLAG_NONE,
+ },
+ attributes: {
+ 'sentry.link.type': 'another_trace',
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ {
+ span_id: 'span2',
+ trace_id: 'trace2',
+ sampled: false,
+ attributes: {
+ 'sentry.link.type': 'another_trace',
+ },
+ },
+ ]);
+ });
+
+ it('handles span links without attributes', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ },
+ ]);
+ });
+});
+
 describe('spanTimeInputToSeconds', () => {
  it('works with undefined', () => {
  const now = timestampInSeconds();

packages/core/src/index.ts

@@ -76,6 +76,7 @@ export { handleCallbackErrors } from './utils/handleCallbackErrors';
 export { parameterize } from './utils/parameterize';
 export { addAutoIpAddressToSession, addAutoIpAddressToUser } from './utils/ipAddress';
 export {
+ convertSpanLinksForEnvelope,
  spanToTraceHeader,
  spanToJSON,
  spanIsSampled,

packages/core/src/tracing/sentryNonRecordingSpan.ts

@@ -69,24 +69,12 @@ export class SentryNonRecordingSpan implements Span {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but we need it for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLink(_link: unknown): this {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but we need it for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLinks(_links: unknown[]): this {
  return this;
  }

packages/core/src/tracing/sentrySpan.ts

@@ -109,24 +109,12 @@ export class SentrySpan implements Span {
  }
  }
 
- /**
- * This should generally not be used,
- * but it is needed for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLink(_link: unknown): this {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but it is needed for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLinks(_links: unknown[]): this {
  return this;
  }

packages/core/src/types-hoist/link.ts

@@ -0,0 +1,30 @@
+import type { SpanAttributeValue, SpanContextData } from './span';
+
+type SpanLinkAttributes = {
+ /**
+ * Setting the link type to 'previous_trace' helps the Sentry product linking to the previous trace
+ */
+ 'sentry.link.type'?: string | 'previous_trace';
+} & Record<string, SpanAttributeValue | undefined>;
+
+export interface SpanLink {
+ /**
+ * Contains the SpanContext of the span to link to
+ */
+ context: SpanContextData;
+ /**
+ * A key-value pair with primitive values or an array of primitive values
+ */
+ attributes?: SpanLinkAttributes;
+}
+
+/**
+ * Link interface for the event envelope item. It's a flattened representation of `SpanLink`.
+ * Can include additional fields defined by OTel.
+ */
+export interface SpanLinkJSON extends Record<string, unknown> {
+ span_id: string;
+ trace_id: string;
+ sampled?: boolean;
+ attributes?: SpanLinkAttributes;
+}

packages/core/src/types-hoist/span.ts

@@ -1,3 +1,4 @@
+import type { SpanLink, SpanLinkJSON } from './link';
 import type { Measurements } from './measurement';
 import type { HrTime } from './opentelemetry';
 import type { SpanStatus } from './spanStatus';
@@ -50,6 +51,7 @@ export interface SpanJSON {
  measurements?: Measurements;
  is_segment?: boolean;
  segment_id?: string;
+ links?: SpanLinkJSON[];
 }
 
 // These are aligned with OpenTelemetry trace flags
@@ -249,14 +251,21 @@ export interface Span {
  addEvent(name: string, attributesOrStartTime?: SpanAttributes | SpanTimeInput, startTime?: SpanTimeInput): this;
 
  /**
- * NOT USED IN SENTRY, only added for compliance with OTEL Span interface
+ * Associates this span with a related span. Links can reference spans from the same or different trace
+ * and are typically used for batch operations, cross-trace scenarios, or scatter/gather patterns.
+ *
+ * Prefer setting links directly when starting a span (e.g. `Sentry.startSpan()`) as some context information is only available during span creation.
+ * @param link - The link containing the context of the span to link to and optional attributes
  */
- addLink(link: unknown): this;
+ addLink(link: SpanLink): this;
 
  /**
- * NOT USED IN SENTRY, only added for compliance with OTEL Span interface
+ * Associates this span with multiple related spans. See {@link addLink} for more details.
+ *
+ * Prefer setting links directly when starting a span (e.g. `Sentry.startSpan()`) as some context information is only available during span creation.
+ * @param links - Array of links to associate with this span
  */
- addLinks(links: unknown): this;
+ addLinks(links: SpanLink[]): this;
 
  /**
  * NOT USED IN SENTRY, only added for compliance with OTEL Span interface

packages/core/src/utils/spanUtils.ts

@@ -19,6 +19,7 @@ import type {
  SpanTimeInput,
  TraceContext,
 } from '../types-hoist';
+import type { SpanLink, SpanLinkJSON } from '../types-hoist/link';
 import { consoleSandbox } from '../utils-hoist/logger';
 import { addNonEnumerableProperty, dropUndefinedKeys } from '../utils-hoist/object';
 import { generateSpanId } from '../utils-hoist/propagationContext';
@@ -81,6 +82,25 @@ export function spanToTraceHeader(span: Span): string {
  return generateSentryTraceHeader(traceId, spanId, sampled);
 }
 
+/**
+ * Converts the span links array to a flattened version to be sent within an envelope.
+ *
+ * If the links array is empty, it returns `undefined` so the empty value can be dropped before it's sent.
+ */
+export function convertSpanLinksForEnvelope(links?: SpanLink[]): SpanLinkJSON[] | undefined {
+ if (links && links.length > 0) {
+ return links.map(({ context: { spanId, traceId, traceFlags, ...restContext }, attributes }) => ({
+ span_id: spanId,
+ trace_id: traceId,
+ sampled: traceFlags === TRACE_FLAG_SAMPLED,
+ attributes,
+ ...restContext,
+ }));
+ } else {
+ return undefined;
+ }
+}
+
 /**
  * Convert a span time input into a timestamp in seconds.
  */

packages/core/test/lib/utils/spanUtils.test.ts

@@ -7,14 +7,17 @@ import {
  SPAN_STATUS_UNSET,
  SentrySpan,
  TRACEPARENT_REGEXP,
+ convertSpanLinksForEnvelope,
  setCurrentClient,
  spanToTraceHeader,
  startInactiveSpan,
  startSpan,
  timestampInSeconds,
 } from '../../../src';
 import type { Span, SpanAttributes, SpanStatus, SpanTimeInput } from '../../../src/types-hoist';
+import type { SpanLink } from '../../../src/types-hoist/link';
 import type { OpenTelemetrySdkTraceBaseSpan } from '../../../src/utils/spanUtils';
+import { TRACE_FLAG_NONE, TRACE_FLAG_SAMPLED } from '../../../src/utils/spanUtils';
 import {
  getRootSpan,
  spanIsSampled,
@@ -156,6 +159,115 @@ describe('spanToTraceContext', () => {
  });
 });
 
+describe('convertSpanLinksForEnvelope', () => {
+ it('returns undefined for undefined input', () => {
+ expect(convertSpanLinksForEnvelope(undefined)).toBeUndefined();
+ });
+
+ it('returns undefined for empty array input', () => {
+ expect(convertSpanLinksForEnvelope([])).toBeUndefined();
+ });
+
+ it('converts a single span link to a flattened envelope item', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ ]);
+ });
+
+ it('converts multiple span links to a flattened envelope item', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ {
+ context: {
+ spanId: 'span2',
+ traceId: 'trace2',
+ traceFlags: TRACE_FLAG_NONE,
+ },
+ attributes: {
+ 'sentry.link.type': 'another_trace',
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ {
+ span_id: 'span2',
+ trace_id: 'trace2',
+ sampled: false,
+ attributes: {
+ 'sentry.link.type': 'another_trace',
+ },
+ },
+ ]);
+ });
+
+ it('handles span links without attributes', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ },
+ ]);
+ });
+});
+
 describe('spanTimeInputToSeconds', () => {
  it('works with undefined', () => {
  const now = timestampInSeconds();

packages/core/src/index.ts

@@ -76,6 +76,7 @@ export { handleCallbackErrors } from './utils/handleCallbackErrors';
 export { parameterize } from './utils/parameterize';
 export { addAutoIpAddressToSession, addAutoIpAddressToUser } from './utils/ipAddress';
 export {
+ convertSpanLinksForEnvelope,
  spanToTraceHeader,
  spanToJSON,
  spanIsSampled,

packages/core/src/tracing/sentryNonRecordingSpan.ts

@@ -69,24 +69,12 @@ export class SentryNonRecordingSpan implements Span {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but we need it for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLink(_link: unknown): this {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but we need it for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLinks(_links: unknown[]): this {
  return this;
  }

packages/core/src/tracing/sentrySpan.ts

@@ -109,24 +109,12 @@ export class SentrySpan implements Span {
  }
  }
 
- /**
- * This should generally not be used,
- * but it is needed for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLink(_link: unknown): this {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but it is needed for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLinks(_links: unknown[]): this {
  return this;
  }

packages/core/src/types-hoist/link.ts

@@ -0,0 +1,30 @@
+import type { SpanAttributeValue, SpanContextData } from './span';
+
+type SpanLinkAttributes = {
+ /**
+ * Setting the link type to 'previous_trace' helps the Sentry product linking to the previous trace
+ */
+ 'sentry.link.type'?: string | 'previous_trace';
+} & Record<string, SpanAttributeValue | undefined>;
+
+export interface SpanLink {
+ /**
+ * Contains the SpanContext of the span to link to
+ */
+ context: SpanContextData;
+ /**
+ * A key-value pair with primitive values or an array of primitive values
+ */
+ attributes?: SpanLinkAttributes;
+}
+
+/**
+ * Link interface for the event envelope item. It's a flattened representation of `SpanLink`.
+ * Can include additional fields defined by OTel.
+ */
+export interface SpanLinkJSON extends Record<string, unknown> {
+ span_id: string;
+ trace_id: string;
+ sampled?: boolean;
+ attributes?: SpanLinkAttributes;
+}

packages/core/src/types-hoist/span.ts

@@ -1,3 +1,4 @@
+import type { SpanLink, SpanLinkJSON } from './link';
 import type { Measurements } from './measurement';
 import type { HrTime } from './opentelemetry';
 import type { SpanStatus } from './spanStatus';
@@ -50,6 +51,7 @@ export interface SpanJSON {
  measurements?: Measurements;
  is_segment?: boolean;
  segment_id?: string;
+ links?: SpanLinkJSON[];
 }
 
 // These are aligned with OpenTelemetry trace flags
@@ -249,14 +251,21 @@ export interface Span {
  addEvent(name: string, attributesOrStartTime?: SpanAttributes | SpanTimeInput, startTime?: SpanTimeInput): this;
 
  /**
- * NOT USED IN SENTRY, only added for compliance with OTEL Span interface
+ * Associates this span with a related span. Links can reference spans from the same or different trace
+ * and are typically used for batch operations, cross-trace scenarios, or scatter/gather patterns.
+ *
+ * Prefer setting links directly when starting a span (e.g. `Sentry.startSpan()`) as some context information is only available during span creation.
+ * @param link - The link containing the context of the span to link to and optional attributes
  */
- addLink(link: unknown): this;
+ addLink(link: SpanLink): this;
 
  /**
- * NOT USED IN SENTRY, only added for compliance with OTEL Span interface
+ * Associates this span with multiple related spans. See {@link addLink} for more details.
+ *
+ * Prefer setting links directly when starting a span (e.g. `Sentry.startSpan()`) as some context information is only available during span creation.
+ * @param links - Array of links to associate with this span
  */
- addLinks(links: unknown): this;
+ addLinks(links: SpanLink[]): this;
 
  /**
  * NOT USED IN SENTRY, only added for compliance with OTEL Span interface

packages/core/src/utils/spanUtils.ts

@@ -19,6 +19,7 @@ import type {
  SpanTimeInput,
  TraceContext,
 } from '../types-hoist';
+import type { SpanLink, SpanLinkJSON } from '../types-hoist/link';
 import { consoleSandbox } from '../utils-hoist/logger';
 import { addNonEnumerableProperty, dropUndefinedKeys } from '../utils-hoist/object';
 import { generateSpanId } from '../utils-hoist/propagationContext';
@@ -81,6 +82,25 @@ export function spanToTraceHeader(span: Span): string {
  return generateSentryTraceHeader(traceId, spanId, sampled);
 }
 
+/**
+ * Converts the span links array to a flattened version to be sent within an envelope.
+ *
+ * If the links array is empty, it returns `undefined` so the empty value can be dropped before it's sent.
+ */
+export function convertSpanLinksForEnvelope(links?: SpanLink[]): SpanLinkJSON[] | undefined {
+ if (links && links.length > 0) {
+ return links.map(({ context: { spanId, traceId, traceFlags, ...restContext }, attributes }) => ({
+ span_id: spanId,
+ trace_id: traceId,
+ sampled: traceFlags === TRACE_FLAG_SAMPLED,
+ attributes,
+ ...restContext,
+ }));
+ } else {
+ return undefined;
+ }
+}
+
 /**
  * Convert a span time input into a timestamp in seconds.
  */

packages/core/test/lib/utils/spanUtils.test.ts

@@ -7,14 +7,17 @@ import {
  SPAN_STATUS_UNSET,
  SentrySpan,
  TRACEPARENT_REGEXP,
+ convertSpanLinksForEnvelope,
  setCurrentClient,
  spanToTraceHeader,
  startInactiveSpan,
  startSpan,
  timestampInSeconds,
 } from '../../../src';
 import type { Span, SpanAttributes, SpanStatus, SpanTimeInput } from '../../../src/types-hoist';
+import type { SpanLink } from '../../../src/types-hoist/link';
 import type { OpenTelemetrySdkTraceBaseSpan } from '../../../src/utils/spanUtils';
+import { TRACE_FLAG_NONE, TRACE_FLAG_SAMPLED } from '../../../src/utils/spanUtils';
 import {
  getRootSpan,
  spanIsSampled,
@@ -156,6 +159,115 @@ describe('spanToTraceContext', () => {
  });
 });
 
+describe('convertSpanLinksForEnvelope', () => {
+ it('returns undefined for undefined input', () => {
+ expect(convertSpanLinksForEnvelope(undefined)).toBeUndefined();
+ });
+
+ it('returns undefined for empty array input', () => {
+ expect(convertSpanLinksForEnvelope([])).toBeUndefined();
+ });
+
+ it('converts a single span link to a flattened envelope item', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ ]);
+ });
+
+ it('converts multiple span links to a flattened envelope item', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ {
+ context: {
+ spanId: 'span2',
+ traceId: 'trace2',
+ traceFlags: TRACE_FLAG_NONE,
+ },
+ attributes: {
+ 'sentry.link.type': 'another_trace',
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ {
+ span_id: 'span2',
+ trace_id: 'trace2',
+ sampled: false,
+ attributes: {
+ 'sentry.link.type': 'another_trace',
+ },
+ },
+ ]);
+ });
+
+ it('handles span links without attributes', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ },
+ ]);
+ });
+});
+
 describe('spanTimeInputToSeconds', () => {
  it('works with undefined', () => {
  const now = timestampInSeconds();

packages/core/src/index.ts

@@ -76,6 +76,7 @@ export { handleCallbackErrors } from './utils/handleCallbackErrors';
 export { parameterize } from './utils/parameterize';
 export { addAutoIpAddressToSession, addAutoIpAddressToUser } from './utils/ipAddress';
 export {
+ convertSpanLinksForEnvelope,
  spanToTraceHeader,
  spanToJSON,
  spanIsSampled,

packages/core/src/tracing/sentryNonRecordingSpan.ts

@@ -69,24 +69,12 @@ export class SentryNonRecordingSpan implements Span {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but we need it for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLink(_link: unknown): this {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but we need it for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLinks(_links: unknown[]): this {
  return this;
  }

packages/core/src/tracing/sentrySpan.ts

@@ -109,24 +109,12 @@ export class SentrySpan implements Span {
  }
  }
 
- /**
- * This should generally not be used,
- * but it is needed for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLink(_link: unknown): this {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but it is needed for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLinks(_links: unknown[]): this {
  return this;
  }

packages/core/src/types-hoist/link.ts

@@ -0,0 +1,30 @@
+import type { SpanAttributeValue, SpanContextData } from './span';
+
+type SpanLinkAttributes = {
+ /**
+ * Setting the link type to 'previous_trace' helps the Sentry product linking to the previous trace
+ */
+ 'sentry.link.type'?: string | 'previous_trace';
+} & Record<string, SpanAttributeValue | undefined>;
+
+export interface SpanLink {
+ /**
+ * Contains the SpanContext of the span to link to
+ */
+ context: SpanContextData;
+ /**
+ * A key-value pair with primitive values or an array of primitive values
+ */
+ attributes?: SpanLinkAttributes;
+}
+
+/**
+ * Link interface for the event envelope item. It's a flattened representation of `SpanLink`.
+ * Can include additional fields defined by OTel.
+ */
+export interface SpanLinkJSON extends Record<string, unknown> {
+ span_id: string;
+ trace_id: string;
+ sampled?: boolean;
+ attributes?: SpanLinkAttributes;
+}

packages/core/src/types-hoist/span.ts

@@ -1,3 +1,4 @@
+import type { SpanLink, SpanLinkJSON } from './link';
 import type { Measurements } from './measurement';
 import type { HrTime } from './opentelemetry';
 import type { SpanStatus } from './spanStatus';
@@ -50,6 +51,7 @@ export interface SpanJSON {
  measurements?: Measurements;
  is_segment?: boolean;
  segment_id?: string;
+ links?: SpanLinkJSON[];
 }
 
 // These are aligned with OpenTelemetry trace flags
@@ -249,14 +251,21 @@ export interface Span {
  addEvent(name: string, attributesOrStartTime?: SpanAttributes | SpanTimeInput, startTime?: SpanTimeInput): this;
 
  /**
- * NOT USED IN SENTRY, only added for compliance with OTEL Span interface
+ * Associates this span with a related span. Links can reference spans from the same or different trace
+ * and are typically used for batch operations, cross-trace scenarios, or scatter/gather patterns.
+ *
+ * Prefer setting links directly when starting a span (e.g. `Sentry.startSpan()`) as some context information is only available during span creation.
+ * @param link - The link containing the context of the span to link to and optional attributes
  */
- addLink(link: unknown): this;
+ addLink(link: SpanLink): this;
 
  /**
- * NOT USED IN SENTRY, only added for compliance with OTEL Span interface
+ * Associates this span with multiple related spans. See {@link addLink} for more details.
+ *
+ * Prefer setting links directly when starting a span (e.g. `Sentry.startSpan()`) as some context information is only available during span creation.
+ * @param links - Array of links to associate with this span
  */
- addLinks(links: unknown): this;
+ addLinks(links: SpanLink[]): this;
 
  /**
  * NOT USED IN SENTRY, only added for compliance with OTEL Span interface

packages/core/src/utils/spanUtils.ts

@@ -19,6 +19,7 @@ import type {
  SpanTimeInput,
  TraceContext,
 } from '../types-hoist';
+import type { SpanLink, SpanLinkJSON } from '../types-hoist/link';
 import { consoleSandbox } from '../utils-hoist/logger';
 import { addNonEnumerableProperty, dropUndefinedKeys } from '../utils-hoist/object';
 import { generateSpanId } from '../utils-hoist/propagationContext';
@@ -81,6 +82,25 @@ export function spanToTraceHeader(span: Span): string {
  return generateSentryTraceHeader(traceId, spanId, sampled);
 }
 
+/**
+ * Converts the span links array to a flattened version to be sent within an envelope.
+ *
+ * If the links array is empty, it returns `undefined` so the empty value can be dropped before it's sent.
+ */
+export function convertSpanLinksForEnvelope(links?: SpanLink[]): SpanLinkJSON[] | undefined {
+ if (links && links.length > 0) {
+ return links.map(({ context: { spanId, traceId, traceFlags, ...restContext }, attributes }) => ({
+ span_id: spanId,
+ trace_id: traceId,
+ sampled: traceFlags === TRACE_FLAG_SAMPLED,
+ attributes,
+ ...restContext,
+ }));
+ } else {
+ return undefined;
+ }
+}
+
 /**
  * Convert a span time input into a timestamp in seconds.
  */

packages/core/test/lib/utils/spanUtils.test.ts

@@ -7,14 +7,17 @@ import {
  SPAN_STATUS_UNSET,
  SentrySpan,
  TRACEPARENT_REGEXP,
+ convertSpanLinksForEnvelope,
  setCurrentClient,
  spanToTraceHeader,
  startInactiveSpan,
  startSpan,
  timestampInSeconds,
 } from '../../../src';
 import type { Span, SpanAttributes, SpanStatus, SpanTimeInput } from '../../../src/types-hoist';
+import type { SpanLink } from '../../../src/types-hoist/link';
 import type { OpenTelemetrySdkTraceBaseSpan } from '../../../src/utils/spanUtils';
+import { TRACE_FLAG_NONE, TRACE_FLAG_SAMPLED } from '../../../src/utils/spanUtils';
 import {
  getRootSpan,
  spanIsSampled,
@@ -156,6 +159,115 @@ describe('spanToTraceContext', () => {
  });
 });
 
+describe('convertSpanLinksForEnvelope', () => {
+ it('returns undefined for undefined input', () => {
+ expect(convertSpanLinksForEnvelope(undefined)).toBeUndefined();
+ });
+
+ it('returns undefined for empty array input', () => {
+ expect(convertSpanLinksForEnvelope([])).toBeUndefined();
+ });
+
+ it('converts a single span link to a flattened envelope item', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ ]);
+ });
+
+ it('converts multiple span links to a flattened envelope item', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ {
+ context: {
+ spanId: 'span2',
+ traceId: 'trace2',
+ traceFlags: TRACE_FLAG_NONE,
+ },
+ attributes: {
+ 'sentry.link.type': 'another_trace',
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ {
+ span_id: 'span2',
+ trace_id: 'trace2',
+ sampled: false,
+ attributes: {
+ 'sentry.link.type': 'another_trace',
+ },
+ },
+ ]);
+ });
+
+ it('handles span links without attributes', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ },
+ ]);
+ });
+});
+
 describe('spanTimeInputToSeconds', () => {
  it('works with undefined', () => {
  const now = timestampInSeconds();

packages/core/src/index.ts

@@ -76,6 +76,7 @@ export { handleCallbackErrors } from './utils/handleCallbackErrors';
 export { parameterize } from './utils/parameterize';
 export { addAutoIpAddressToSession, addAutoIpAddressToUser } from './utils/ipAddress';
 export {
+ convertSpanLinksForEnvelope,
  spanToTraceHeader,
  spanToJSON,
  spanIsSampled,

packages/core/src/tracing/sentryNonRecordingSpan.ts

@@ -69,24 +69,12 @@ export class SentryNonRecordingSpan implements Span {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but we need it for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLink(_link: unknown): this {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but we need it for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLinks(_links: unknown[]): this {
  return this;
  }

packages/core/src/tracing/sentrySpan.ts

@@ -109,24 +109,12 @@ export class SentrySpan implements Span {
  }
  }
 
- /**
- * This should generally not be used,
- * but it is needed for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLink(_link: unknown): this {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but it is needed for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLinks(_links: unknown[]): this {
  return this;
  }

packages/core/src/types-hoist/link.ts

@@ -0,0 +1,30 @@
+import type { SpanAttributeValue, SpanContextData } from './span';
+
+type SpanLinkAttributes = {
+ /**
+ * Setting the link type to 'previous_trace' helps the Sentry product linking to the previous trace
+ */
+ 'sentry.link.type'?: string | 'previous_trace';
+} & Record<string, SpanAttributeValue | undefined>;
+
+export interface SpanLink {
+ /**
+ * Contains the SpanContext of the span to link to
+ */
+ context: SpanContextData;
+ /**
+ * A key-value pair with primitive values or an array of primitive values
+ */
+ attributes?: SpanLinkAttributes;
+}
+
+/**
+ * Link interface for the event envelope item. It's a flattened representation of `SpanLink`.
+ * Can include additional fields defined by OTel.
+ */
+export interface SpanLinkJSON extends Record<string, unknown> {
+ span_id: string;
+ trace_id: string;
+ sampled?: boolean;
+ attributes?: SpanLinkAttributes;
+}

packages/core/src/types-hoist/span.ts

@@ -1,3 +1,4 @@
+import type { SpanLink, SpanLinkJSON } from './link';
 import type { Measurements } from './measurement';
 import type { HrTime } from './opentelemetry';
 import type { SpanStatus } from './spanStatus';
@@ -50,6 +51,7 @@ export interface SpanJSON {
  measurements?: Measurements;
  is_segment?: boolean;
  segment_id?: string;
+ links?: SpanLinkJSON[];
 }
 
 // These are aligned with OpenTelemetry trace flags
@@ -249,14 +251,21 @@ export interface Span {
  addEvent(name: string, attributesOrStartTime?: SpanAttributes | SpanTimeInput, startTime?: SpanTimeInput): this;
 
  /**
- * NOT USED IN SENTRY, only added for compliance with OTEL Span interface
+ * Associates this span with a related span. Links can reference spans from the same or different trace
+ * and are typically used for batch operations, cross-trace scenarios, or scatter/gather patterns.
+ *
+ * Prefer setting links directly when starting a span (e.g. `Sentry.startSpan()`) as some context information is only available during span creation.
+ * @param link - The link containing the context of the span to link to and optional attributes
  */
- addLink(link: unknown): this;
+ addLink(link: SpanLink): this;
 
  /**
- * NOT USED IN SENTRY, only added for compliance with OTEL Span interface
+ * Associates this span with multiple related spans. See {@link addLink} for more details.
+ *
+ * Prefer setting links directly when starting a span (e.g. `Sentry.startSpan()`) as some context information is only available during span creation.
+ * @param links - Array of links to associate with this span
  */
- addLinks(links: unknown): this;
+ addLinks(links: SpanLink[]): this;
 
  /**
  * NOT USED IN SENTRY, only added for compliance with OTEL Span interface

packages/core/src/utils/spanUtils.ts

@@ -19,6 +19,7 @@ import type {
  SpanTimeInput,
  TraceContext,
 } from '../types-hoist';
+import type { SpanLink, SpanLinkJSON } from '../types-hoist/link';
 import { consoleSandbox } from '../utils-hoist/logger';
 import { addNonEnumerableProperty, dropUndefinedKeys } from '../utils-hoist/object';
 import { generateSpanId } from '../utils-hoist/propagationContext';
@@ -81,6 +82,25 @@ export function spanToTraceHeader(span: Span): string {
  return generateSentryTraceHeader(traceId, spanId, sampled);
 }
 
+/**
+ * Converts the span links array to a flattened version to be sent within an envelope.
+ *
+ * If the links array is empty, it returns `undefined` so the empty value can be dropped before it's sent.
+ */
+export function convertSpanLinksForEnvelope(links?: SpanLink[]): SpanLinkJSON[] | undefined {
+ if (links && links.length > 0) {
+ return links.map(({ context: { spanId, traceId, traceFlags, ...restContext }, attributes }) => ({
+ span_id: spanId,
+ trace_id: traceId,
+ sampled: traceFlags === TRACE_FLAG_SAMPLED,
+ attributes,
+ ...restContext,
+ }));
+ } else {
+ return undefined;
+ }
+}
+
 /**
  * Convert a span time input into a timestamp in seconds.
  */

packages/core/test/lib/utils/spanUtils.test.ts

@@ -7,14 +7,17 @@ import {
  SPAN_STATUS_UNSET,
  SentrySpan,
  TRACEPARENT_REGEXP,
+ convertSpanLinksForEnvelope,
  setCurrentClient,
  spanToTraceHeader,
  startInactiveSpan,
  startSpan,
  timestampInSeconds,
 } from '../../../src';
 import type { Span, SpanAttributes, SpanStatus, SpanTimeInput } from '../../../src/types-hoist';
+import type { SpanLink } from '../../../src/types-hoist/link';
 import type { OpenTelemetrySdkTraceBaseSpan } from '../../../src/utils/spanUtils';
+import { TRACE_FLAG_NONE, TRACE_FLAG_SAMPLED } from '../../../src/utils/spanUtils';
 import {
  getRootSpan,
  spanIsSampled,
@@ -156,6 +159,115 @@ describe('spanToTraceContext', () => {
  });
 });
 
+describe('convertSpanLinksForEnvelope', () => {
+ it('returns undefined for undefined input', () => {
+ expect(convertSpanLinksForEnvelope(undefined)).toBeUndefined();
+ });
+
+ it('returns undefined for empty array input', () => {
+ expect(convertSpanLinksForEnvelope([])).toBeUndefined();
+ });
+
+ it('converts a single span link to a flattened envelope item', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ ]);
+ });
+
+ it('converts multiple span links to a flattened envelope item', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ {
+ context: {
+ spanId: 'span2',
+ traceId: 'trace2',
+ traceFlags: TRACE_FLAG_NONE,
+ },
+ attributes: {
+ 'sentry.link.type': 'another_trace',
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ {
+ span_id: 'span2',
+ trace_id: 'trace2',
+ sampled: false,
+ attributes: {
+ 'sentry.link.type': 'another_trace',
+ },
+ },
+ ]);
+ });
+
+ it('handles span links without attributes', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ },
+ ]);
+ });
+});
+
 describe('spanTimeInputToSeconds', () => {
  it('works with undefined', () => {
  const now = timestampInSeconds();

packages/core/src/index.ts

@@ -76,6 +76,7 @@ export { handleCallbackErrors } from './utils/handleCallbackErrors';
 export { parameterize } from './utils/parameterize';
 export { addAutoIpAddressToSession, addAutoIpAddressToUser } from './utils/ipAddress';
 export {
+ convertSpanLinksForEnvelope,
  spanToTraceHeader,
  spanToJSON,
  spanIsSampled,

packages/core/src/tracing/sentryNonRecordingSpan.ts

@@ -69,24 +69,12 @@ export class SentryNonRecordingSpan implements Span {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but we need it for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLink(_link: unknown): this {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but we need it for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLinks(_links: unknown[]): this {
  return this;
  }

packages/core/src/tracing/sentrySpan.ts

@@ -109,24 +109,12 @@ export class SentrySpan implements Span {
  }
  }
 
- /**
- * This should generally not be used,
- * but it is needed for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLink(_link: unknown): this {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but it is needed for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLinks(_links: unknown[]): this {
  return this;
  }

packages/core/src/types-hoist/link.ts

@@ -0,0 +1,30 @@
+import type { SpanAttributeValue, SpanContextData } from './span';
+
+type SpanLinkAttributes = {
+ /**
+ * Setting the link type to 'previous_trace' helps the Sentry product linking to the previous trace
+ */
+ 'sentry.link.type'?: string | 'previous_trace';
+} & Record<string, SpanAttributeValue | undefined>;
+
+export interface SpanLink {
+ /**
+ * Contains the SpanContext of the span to link to
+ */
+ context: SpanContextData;
+ /**
+ * A key-value pair with primitive values or an array of primitive values
+ */
+ attributes?: SpanLinkAttributes;
+}
+
+/**
+ * Link interface for the event envelope item. It's a flattened representation of `SpanLink`.
+ * Can include additional fields defined by OTel.
+ */
+export interface SpanLinkJSON extends Record<string, unknown> {
+ span_id: string;
+ trace_id: string;
+ sampled?: boolean;
+ attributes?: SpanLinkAttributes;
+}

packages/core/src/types-hoist/span.ts

@@ -1,3 +1,4 @@
+import type { SpanLink, SpanLinkJSON } from './link';
 import type { Measurements } from './measurement';
 import type { HrTime } from './opentelemetry';
 import type { SpanStatus } from './spanStatus';
@@ -50,6 +51,7 @@ export interface SpanJSON {
  measurements?: Measurements;
  is_segment?: boolean;
  segment_id?: string;
+ links?: SpanLinkJSON[];
 }
 
 // These are aligned with OpenTelemetry trace flags
@@ -249,14 +251,21 @@ export interface Span {
  addEvent(name: string, attributesOrStartTime?: SpanAttributes | SpanTimeInput, startTime?: SpanTimeInput): this;
 
  /**
- * NOT USED IN SENTRY, only added for compliance with OTEL Span interface
+ * Associates this span with a related span. Links can reference spans from the same or different trace
+ * and are typically used for batch operations, cross-trace scenarios, or scatter/gather patterns.
+ *
+ * Prefer setting links directly when starting a span (e.g. `Sentry.startSpan()`) as some context information is only available during span creation.
+ * @param link - The link containing the context of the span to link to and optional attributes
  */
- addLink(link: unknown): this;
+ addLink(link: SpanLink): this;
 
  /**
- * NOT USED IN SENTRY, only added for compliance with OTEL Span interface
+ * Associates this span with multiple related spans. See {@link addLink} for more details.
+ *
+ * Prefer setting links directly when starting a span (e.g. `Sentry.startSpan()`) as some context information is only available during span creation.
+ * @param links - Array of links to associate with this span
  */
- addLinks(links: unknown): this;
+ addLinks(links: SpanLink[]): this;
 
  /**
  * NOT USED IN SENTRY, only added for compliance with OTEL Span interface

packages/core/src/utils/spanUtils.ts

@@ -19,6 +19,7 @@ import type {
  SpanTimeInput,
  TraceContext,
 } from '../types-hoist';
+import type { SpanLink, SpanLinkJSON } from '../types-hoist/link';
 import { consoleSandbox } from '../utils-hoist/logger';
 import { addNonEnumerableProperty, dropUndefinedKeys } from '../utils-hoist/object';
 import { generateSpanId } from '../utils-hoist/propagationContext';
@@ -81,6 +82,25 @@ export function spanToTraceHeader(span: Span): string {
  return generateSentryTraceHeader(traceId, spanId, sampled);
 }
 
+/**
+ * Converts the span links array to a flattened version to be sent within an envelope.
+ *
+ * If the links array is empty, it returns `undefined` so the empty value can be dropped before it's sent.
+ */
+export function convertSpanLinksForEnvelope(links?: SpanLink[]): SpanLinkJSON[] | undefined {
+ if (links && links.length > 0) {
+ return links.map(({ context: { spanId, traceId, traceFlags, ...restContext }, attributes }) => ({
+ span_id: spanId,
+ trace_id: traceId,
+ sampled: traceFlags === TRACE_FLAG_SAMPLED,
+ attributes,
+ ...restContext,
+ }));
+ } else {
+ return undefined;
+ }
+}
+
 /**
  * Convert a span time input into a timestamp in seconds.
  */

packages/core/test/lib/utils/spanUtils.test.ts

@@ -7,14 +7,17 @@ import {
  SPAN_STATUS_UNSET,
  SentrySpan,
  TRACEPARENT_REGEXP,
+ convertSpanLinksForEnvelope,
  setCurrentClient,
  spanToTraceHeader,
  startInactiveSpan,
  startSpan,
  timestampInSeconds,
 } from '../../../src';
 import type { Span, SpanAttributes, SpanStatus, SpanTimeInput } from '../../../src/types-hoist';
+import type { SpanLink } from '../../../src/types-hoist/link';
 import type { OpenTelemetrySdkTraceBaseSpan } from '../../../src/utils/spanUtils';
+import { TRACE_FLAG_NONE, TRACE_FLAG_SAMPLED } from '../../../src/utils/spanUtils';
 import {
  getRootSpan,
  spanIsSampled,
@@ -156,6 +159,115 @@ describe('spanToTraceContext', () => {
  });
 });
 
+describe('convertSpanLinksForEnvelope', () => {
+ it('returns undefined for undefined input', () => {
+ expect(convertSpanLinksForEnvelope(undefined)).toBeUndefined();
+ });
+
+ it('returns undefined for empty array input', () => {
+ expect(convertSpanLinksForEnvelope([])).toBeUndefined();
+ });
+
+ it('converts a single span link to a flattened envelope item', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ ]);
+ });
+
+ it('converts multiple span links to a flattened envelope item', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ {
+ context: {
+ spanId: 'span2',
+ traceId: 'trace2',
+ traceFlags: TRACE_FLAG_NONE,
+ },
+ attributes: {
+ 'sentry.link.type': 'another_trace',
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ {
+ span_id: 'span2',
+ trace_id: 'trace2',
+ sampled: false,
+ attributes: {
+ 'sentry.link.type': 'another_trace',
+ },
+ },
+ ]);
+ });
+
+ it('handles span links without attributes', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ },
+ ]);
+ });
+});
+
 describe('spanTimeInputToSeconds', () => {
  it('works with undefined', () => {
  const now = timestampInSeconds();

packages/core/src/index.ts

@@ -76,6 +76,7 @@ export { handleCallbackErrors } from './utils/handleCallbackErrors';
 export { parameterize } from './utils/parameterize';
 export { addAutoIpAddressToSession, addAutoIpAddressToUser } from './utils/ipAddress';
 export {
+ convertSpanLinksForEnvelope,
  spanToTraceHeader,
  spanToJSON,
  spanIsSampled,

packages/core/src/tracing/sentryNonRecordingSpan.ts

@@ -69,24 +69,12 @@ export class SentryNonRecordingSpan implements Span {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but we need it for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLink(_link: unknown): this {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but we need it for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLinks(_links: unknown[]): this {
  return this;
  }

packages/core/src/tracing/sentrySpan.ts

@@ -109,24 +109,12 @@ export class SentrySpan implements Span {
  }
  }
 
- /**
- * This should generally not be used,
- * but it is needed for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLink(_link: unknown): this {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but it is needed for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLinks(_links: unknown[]): this {
  return this;
  }

packages/core/src/types-hoist/link.ts

@@ -0,0 +1,30 @@
+import type { SpanAttributeValue, SpanContextData } from './span';
+
+type SpanLinkAttributes = {
+ /**
+ * Setting the link type to 'previous_trace' helps the Sentry product linking to the previous trace
+ */
+ 'sentry.link.type'?: string | 'previous_trace';
+} & Record<string, SpanAttributeValue | undefined>;
+
+export interface SpanLink {
+ /**
+ * Contains the SpanContext of the span to link to
+ */
+ context: SpanContextData;
+ /**
+ * A key-value pair with primitive values or an array of primitive values
+ */
+ attributes?: SpanLinkAttributes;
+}
+
+/**
+ * Link interface for the event envelope item. It's a flattened representation of `SpanLink`.
+ * Can include additional fields defined by OTel.
+ */
+export interface SpanLinkJSON extends Record<string, unknown> {
+ span_id: string;
+ trace_id: string;
+ sampled?: boolean;
+ attributes?: SpanLinkAttributes;
+}

packages/core/src/types-hoist/span.ts

@@ -1,3 +1,4 @@
+import type { SpanLink, SpanLinkJSON } from './link';
 import type { Measurements } from './measurement';
 import type { HrTime } from './opentelemetry';
 import type { SpanStatus } from './spanStatus';
@@ -50,6 +51,7 @@ export interface SpanJSON {
  measurements?: Measurements;
  is_segment?: boolean;
  segment_id?: string;
+ links?: SpanLinkJSON[];
 }
 
 // These are aligned with OpenTelemetry trace flags
@@ -249,14 +251,21 @@ export interface Span {
  addEvent(name: string, attributesOrStartTime?: SpanAttributes | SpanTimeInput, startTime?: SpanTimeInput): this;
 
  /**
- * NOT USED IN SENTRY, only added for compliance with OTEL Span interface
+ * Associates this span with a related span. Links can reference spans from the same or different trace
+ * and are typically used for batch operations, cross-trace scenarios, or scatter/gather patterns.
+ *
+ * Prefer setting links directly when starting a span (e.g. `Sentry.startSpan()`) as some context information is only available during span creation.
+ * @param link - The link containing the context of the span to link to and optional attributes
  */
- addLink(link: unknown): this;
+ addLink(link: SpanLink): this;
 
  /**
- * NOT USED IN SENTRY, only added for compliance with OTEL Span interface
+ * Associates this span with multiple related spans. See {@link addLink} for more details.
+ *
+ * Prefer setting links directly when starting a span (e.g. `Sentry.startSpan()`) as some context information is only available during span creation.
+ * @param links - Array of links to associate with this span
  */
- addLinks(links: unknown): this;
+ addLinks(links: SpanLink[]): this;
 
  /**
  * NOT USED IN SENTRY, only added for compliance with OTEL Span interface

packages/core/src/utils/spanUtils.ts

@@ -19,6 +19,7 @@ import type {
  SpanTimeInput,
  TraceContext,
 } from '../types-hoist';
+import type { SpanLink, SpanLinkJSON } from '../types-hoist/link';
 import { consoleSandbox } from '../utils-hoist/logger';
 import { addNonEnumerableProperty, dropUndefinedKeys } from '../utils-hoist/object';
 import { generateSpanId } from '../utils-hoist/propagationContext';
@@ -81,6 +82,25 @@ export function spanToTraceHeader(span: Span): string {
  return generateSentryTraceHeader(traceId, spanId, sampled);
 }
 
+/**
+ * Converts the span links array to a flattened version to be sent within an envelope.
+ *
+ * If the links array is empty, it returns `undefined` so the empty value can be dropped before it's sent.
+ */
+export function convertSpanLinksForEnvelope(links?: SpanLink[]): SpanLinkJSON[] | undefined {
+ if (links && links.length > 0) {
+ return links.map(({ context: { spanId, traceId, traceFlags, ...restContext }, attributes }) => ({
+ span_id: spanId,
+ trace_id: traceId,
+ sampled: traceFlags === TRACE_FLAG_SAMPLED,
+ attributes,
+ ...restContext,
+ }));
+ } else {
+ return undefined;
+ }
+}
+
 /**
  * Convert a span time input into a timestamp in seconds.
  */

packages/core/test/lib/utils/spanUtils.test.ts

@@ -7,14 +7,17 @@ import {
  SPAN_STATUS_UNSET,
  SentrySpan,
  TRACEPARENT_REGEXP,
+ convertSpanLinksForEnvelope,
  setCurrentClient,
  spanToTraceHeader,
  startInactiveSpan,
  startSpan,
  timestampInSeconds,
 } from '../../../src';
 import type { Span, SpanAttributes, SpanStatus, SpanTimeInput } from '../../../src/types-hoist';
+import type { SpanLink } from '../../../src/types-hoist/link';
 import type { OpenTelemetrySdkTraceBaseSpan } from '../../../src/utils/spanUtils';
+import { TRACE_FLAG_NONE, TRACE_FLAG_SAMPLED } from '../../../src/utils/spanUtils';
 import {
  getRootSpan,
  spanIsSampled,
@@ -156,6 +159,115 @@ describe('spanToTraceContext', () => {
  });
 });
 
+describe('convertSpanLinksForEnvelope', () => {
+ it('returns undefined for undefined input', () => {
+ expect(convertSpanLinksForEnvelope(undefined)).toBeUndefined();
+ });
+
+ it('returns undefined for empty array input', () => {
+ expect(convertSpanLinksForEnvelope([])).toBeUndefined();
+ });
+
+ it('converts a single span link to a flattened envelope item', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ ]);
+ });
+
+ it('converts multiple span links to a flattened envelope item', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ {
+ context: {
+ spanId: 'span2',
+ traceId: 'trace2',
+ traceFlags: TRACE_FLAG_NONE,
+ },
+ attributes: {
+ 'sentry.link.type': 'another_trace',
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ {
+ span_id: 'span2',
+ trace_id: 'trace2',
+ sampled: false,
+ attributes: {
+ 'sentry.link.type': 'another_trace',
+ },
+ },
+ ]);
+ });
+
+ it('handles span links without attributes', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ },
+ ]);
+ });
+});
+
 describe('spanTimeInputToSeconds', () => {
  it('works with undefined', () => {
  const now = timestampInSeconds();

packages/core/src/index.ts

@@ -76,6 +76,7 @@ export { handleCallbackErrors } from './utils/handleCallbackErrors';
 export { parameterize } from './utils/parameterize';
 export { addAutoIpAddressToSession, addAutoIpAddressToUser } from './utils/ipAddress';
 export {
+ convertSpanLinksForEnvelope,
  spanToTraceHeader,
  spanToJSON,
  spanIsSampled,

packages/core/src/tracing/sentryNonRecordingSpan.ts

@@ -69,24 +69,12 @@ export class SentryNonRecordingSpan implements Span {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but we need it for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLink(_link: unknown): this {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but we need it for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLinks(_links: unknown[]): this {
  return this;
  }

packages/core/src/tracing/sentrySpan.ts

@@ -109,24 +109,12 @@ export class SentrySpan implements Span {
  }
  }
 
- /**
- * This should generally not be used,
- * but it is needed for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLink(_link: unknown): this {
  return this;
  }
 
- /**
- * This should generally not be used,
- * but it is needed for being compliant with the OTEL Span interface.
- *
- * @hidden
- * @internal
- */
+ /** @inheritDoc */
  public addLinks(_links: unknown[]): this {
  return this;
  }

packages/core/src/types-hoist/link.ts

@@ -0,0 +1,30 @@
+import type { SpanAttributeValue, SpanContextData } from './span';
+
+type SpanLinkAttributes = {
+ /**
+ * Setting the link type to 'previous_trace' helps the Sentry product linking to the previous trace
+ */
+ 'sentry.link.type'?: string | 'previous_trace';
+} & Record<string, SpanAttributeValue | undefined>;
+
+export interface SpanLink {
+ /**
+ * Contains the SpanContext of the span to link to
+ */
+ context: SpanContextData;
+ /**
+ * A key-value pair with primitive values or an array of primitive values
+ */
+ attributes?: SpanLinkAttributes;
+}
+
+/**
+ * Link interface for the event envelope item. It's a flattened representation of `SpanLink`.
+ * Can include additional fields defined by OTel.
+ */
+export interface SpanLinkJSON extends Record<string, unknown> {
+ span_id: string;
+ trace_id: string;
+ sampled?: boolean;
+ attributes?: SpanLinkAttributes;
+}

packages/core/src/types-hoist/span.ts

@@ -1,3 +1,4 @@
+import type { SpanLink, SpanLinkJSON } from './link';
 import type { Measurements } from './measurement';
 import type { HrTime } from './opentelemetry';
 import type { SpanStatus } from './spanStatus';
@@ -50,6 +51,7 @@ export interface SpanJSON {
  measurements?: Measurements;
  is_segment?: boolean;
  segment_id?: string;
+ links?: SpanLinkJSON[];
 }
 
 // These are aligned with OpenTelemetry trace flags
@@ -249,14 +251,21 @@ export interface Span {
  addEvent(name: string, attributesOrStartTime?: SpanAttributes | SpanTimeInput, startTime?: SpanTimeInput): this;
 
  /**
- * NOT USED IN SENTRY, only added for compliance with OTEL Span interface
+ * Associates this span with a related span. Links can reference spans from the same or different trace
+ * and are typically used for batch operations, cross-trace scenarios, or scatter/gather patterns.
+ *
+ * Prefer setting links directly when starting a span (e.g. `Sentry.startSpan()`) as some context information is only available during span creation.
+ * @param link - The link containing the context of the span to link to and optional attributes
  */
- addLink(link: unknown): this;
+ addLink(link: SpanLink): this;
 
  /**
- * NOT USED IN SENTRY, only added for compliance with OTEL Span interface
+ * Associates this span with multiple related spans. See {@link addLink} for more details.
+ *
+ * Prefer setting links directly when starting a span (e.g. `Sentry.startSpan()`) as some context information is only available during span creation.
+ * @param links - Array of links to associate with this span
  */
- addLinks(links: unknown): this;
+ addLinks(links: SpanLink[]): this;
 
  /**
  * NOT USED IN SENTRY, only added for compliance with OTEL Span interface

packages/core/src/utils/spanUtils.ts

@@ -19,6 +19,7 @@ import type {
  SpanTimeInput,
  TraceContext,
 } from '../types-hoist';
+import type { SpanLink, SpanLinkJSON } from '../types-hoist/link';
 import { consoleSandbox } from '../utils-hoist/logger';
 import { addNonEnumerableProperty, dropUndefinedKeys } from '../utils-hoist/object';
 import { generateSpanId } from '../utils-hoist/propagationContext';
@@ -81,6 +82,25 @@ export function spanToTraceHeader(span: Span): string {
  return generateSentryTraceHeader(traceId, spanId, sampled);
 }
 
+/**
+ * Converts the span links array to a flattened version to be sent within an envelope.
+ *
+ * If the links array is empty, it returns `undefined` so the empty value can be dropped before it's sent.
+ */
+export function convertSpanLinksForEnvelope(links?: SpanLink[]): SpanLinkJSON[] | undefined {
+ if (links && links.length > 0) {
+ return links.map(({ context: { spanId, traceId, traceFlags, ...restContext }, attributes }) => ({
+ span_id: spanId,
+ trace_id: traceId,
+ sampled: traceFlags === TRACE_FLAG_SAMPLED,
+ attributes,
+ ...restContext,
+ }));
+ } else {
+ return undefined;
+ }
+}
+
 /**
  * Convert a span time input into a timestamp in seconds.
  */

packages/core/test/lib/utils/spanUtils.test.ts

@@ -7,14 +7,17 @@ import {
  SPAN_STATUS_UNSET,
  SentrySpan,
  TRACEPARENT_REGEXP,
+ convertSpanLinksForEnvelope,
  setCurrentClient,
  spanToTraceHeader,
  startInactiveSpan,
  startSpan,
  timestampInSeconds,
 } from '../../../src';
 import type { Span, SpanAttributes, SpanStatus, SpanTimeInput } from '../../../src/types-hoist';
+import type { SpanLink } from '../../../src/types-hoist/link';
 import type { OpenTelemetrySdkTraceBaseSpan } from '../../../src/utils/spanUtils';
+import { TRACE_FLAG_NONE, TRACE_FLAG_SAMPLED } from '../../../src/utils/spanUtils';
 import {
  getRootSpan,
  spanIsSampled,
@@ -156,6 +159,115 @@ describe('spanToTraceContext', () => {
  });
 });
 
+describe('convertSpanLinksForEnvelope', () => {
+ it('returns undefined for undefined input', () => {
+ expect(convertSpanLinksForEnvelope(undefined)).toBeUndefined();
+ });
+
+ it('returns undefined for empty array input', () => {
+ expect(convertSpanLinksForEnvelope([])).toBeUndefined();
+ });
+
+ it('converts a single span link to a flattened envelope item', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ ]);
+ });
+
+ it('converts multiple span links to a flattened envelope item', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ {
+ context: {
+ spanId: 'span2',
+ traceId: 'trace2',
+ traceFlags: TRACE_FLAG_NONE,
+ },
+ attributes: {
+ 'sentry.link.type': 'another_trace',
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ attributes: {
+ 'sentry.link.type': 'previous_trace',
+ },
+ },
+ {
+ span_id: 'span2',
+ trace_id: 'trace2',
+ sampled: false,
+ attributes: {
+ 'sentry.link.type': 'another_trace',
+ },
+ },
+ ]);
+ });
+
+ it('handles span links without attributes', () => {
+ const links: SpanLink[] = [
+ {
+ context: {
+ spanId: 'span1',
+ traceId: 'trace1',
+ traceFlags: TRACE_FLAG_SAMPLED,
+ },
+ },
+ ];
+
+ const result = convertSpanLinksForEnvelope(links);
+
+ result?.forEach(item => expect(item).not.toHaveProperty('context'));
+ expect(result).toEqual([
+ {
+ span_id: 'span1',
+ trace_id: 'trace1',
+ sampled: true,
+ },
+ ]);
+ });
+});
+
 describe('spanTimeInputToSeconds', () => {
  it('works with undefined', () => {
  const now = timestampInSeconds();