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

Author: s1gr1d

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/index.ts

@@ -113,6 +113,7 @@ export type {
   SpanContextData,
   TraceFlag,
 } from './span';
+export type { SpanLink, SpanLinkJSON } from './link';
 export type { SpanStatus } from './spanStatus';
 export type { TimedEvent } from './timedEvent';
 export type { StackFrame } from './stackframe';

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,19 @@ 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 during span creation when possible to support sampling decisions.
+   * @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.
+   * @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

@@ -14,6 +14,8 @@ import type {
   Span,
   SpanAttributes,
   SpanJSON,
+  SpanLink,
+  SpanLinkJSON,
   SpanOrigin,
   SpanStatus,
   SpanTimeInput,
@@ -81,6 +83,19 @@ 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
+ */
+export function convertSpanLinksForEnvelope(links: SpanLink[]): SpanLinkJSON[] {
+  return links.map(({ context: { spanId, traceId, traceFlags, ...restContext }, attributes }) => ({
+    span_id: spanId,
+    trace_id: traceId,
+    sampled: traceFlags === TRACE_FLAG_SAMPLED,
+    attributes,
+    ...restContext,
+  }));
+}
+
 /**
  * Convert a span time input into a timestamp in seconds.
  */
@@ -180,7 +195,7 @@ function spanIsSentrySpan(span: Span): span is SentrySpan {
  * However, this has a slightly different semantic, as it also returns false if the span is finished.
  * So in the case where this distinction is important, use this method.
  */
-export function spanIsSampled(span: Span): boolean {
+export function spanIsSampled(span: { spanContext: Span['spanContext'] }): boolean {
   // We align our trace flags with the ones OpenTelemetry use
   // So we also check for sampled the same way they do.
   const { traceFlags } = span.spanContext();