feat: implement Span Links API

model/model.go

@@ -281,6 +281,9 @@ type Transaction struct {
 
 	// FAAS holds Function-as-a-Service properties for the transaction.
 	FAAS *FAAS `json:"faas,omitempty"`
+
+	// Links holds a list of spans linked to the transaction.
+	Links []SpanLink `json:"links,omitempty"`
 }
 
 // OTel holds bridged OpenTelemetry information.
@@ -379,6 +382,9 @@ type Span struct {
 	// aggregated set of spans as defined by `composite.compression_strategy`.
 	Composite *CompositeSpan `json:"composite,omitempty"`
 
+	// Links holds a list of spans linked to the span.
+	Links []SpanLink `json:"links,omitempty"`
+
 	// OTel holds information bridged from OpenTelemetry.
 	OTel *OTel `json:"otel,omitempty"`
 }
@@ -402,6 +408,12 @@ type SpanContext struct {
 	Tags IfaceMap `json:"tags,omitempty"`
 }
 
+// SpanLink holds the information of a linked span.
+type SpanLink struct {
+	TraceID TraceID `json:"trace_id"`
+	SpanID  SpanID  `json:"span_id"`
+}
+
 // DestinationSpanContext holds contextual information about the destination
 // for a span that relates to an operation involving an external service.
 type DestinationSpanContext struct {

modelwriter.go

@@ -124,6 +124,9 @@ func (w *modelWriter) buildModelTransaction(out *model.Transaction, tx *Transact
 	out.SpanCount.Started = td.spansCreated
 	out.SpanCount.Dropped = td.spansDropped
 	out.OTel = td.Context.otel
+	for _, sl := range td.links {
+		out.Links = append(out.Links, model.SpanLink{TraceID: model.TraceID(sl.Trace), SpanID: model.SpanID(sl.Span)})
+	}
 	if dss := buildDroppedSpansStats(td.droppedSpansStats); len(dss) > 0 {
 		out.DroppedSpansStats = dss
 	}
@@ -152,6 +155,9 @@ func (w *modelWriter) buildModelSpan(out *model.Span, span *Span, sd *SpanData)
 	out.Outcome = normalizeOutcome(sd.Outcome)
 	out.Context = sd.Context.build()
 	out.OTel = sd.Context.otel
+	for _, sl := range sd.links {
+		out.Links = append(out.Links, model.SpanLink{TraceID: model.TraceID(sl.Trace), SpanID: model.SpanID(sl.Span)})
+	}
 	if sd.composite.count > 1 {
 		out.Composite = sd.composite.build()
 	}

span.go

@@ -219,6 +219,9 @@ type SpanOptions struct {
 	// transaction timestamp. Calculating the timstamp in this way will ensure
 	// monotonicity of events within a transaction.
 	Start time.Time
+
+	// Links, if non-nil, holds a list of spans linked to the span.
+	Links []SpanLink
 }
 
 func (t *Tracer) startSpan(name, spanType string, transactionID SpanID, opts SpanOptions) *Span {
@@ -233,6 +236,7 @@ func (t *Tracer) startSpan(name, spanType string, transactionID SpanID, opts Spa
 	span.transactionID = transactionID
 	span.timestamp = opts.Start
 	span.Type = spanType
+	span.links = opts.Links
 	if dot := strings.IndexRune(spanType, '.'); dot != -1 {
 		span.Type = spanType[:dot]
 		span.Subtype = spanType[dot+1:]
@@ -578,6 +582,8 @@ type SpanData struct {
 	// Context describes the context in which span occurs.
 	Context SpanContext
 
+	links []SpanLink
+
 	mu            sync.Mutex
 	stacktrace    []stacktrace.Frame
 	errorCaptured bool

span_test.go

@@ -118,6 +118,37 @@ func TestSpanParentID(t *testing.T) {
 	assert.Equal(t, model.SpanID(parentID), payloads.Spans[0].ParentID)
 }
 
+func TestSpanLink(t *testing.T) {
+	tracer := apmtest.NewRecordingTracer()
+	defer tracer.Close()
+
+	links := []apm.SpanLink{
+		{Trace: apm.TraceID{1}, Span: apm.SpanID{1}},
+		{Trace: apm.TraceID{2}, Span: apm.SpanID{2}},
+	}
+
+	tx := tracer.StartTransaction("name", "type")
+	span := tx.StartSpanOptions("name", "type", apm.SpanOptions{
+		Links: links,
+	})
+
+	span.End()
+	tx.End()
+
+	tracer.Flush(nil)
+
+	payloads := tracer.Payloads()
+	require.Len(t, payloads.Spans, 1)
+	require.Len(t, payloads.Spans[0].Links, len(links))
+
+	// Assert span links are identical.
+	expectedLinks := []model.SpanLink{
+		{TraceID: model.TraceID{1}, SpanID: model.SpanID{1}},
+		{TraceID: model.TraceID{2}, SpanID: model.SpanID{2}},
+	}
+	assert.Equal(t, expectedLinks, payloads.Spans[0].Links)
+}
+
 func TestSpanTiming(t *testing.T) {
 	var spanStart, spanEnd time.Time
 	txStart := time.Now()

tracecontext.go

@@ -138,6 +138,12 @@ func (id SpanID) MarshalText() ([]byte, error) {
 	return text, nil
 }
 
+// SpanLink describes a linked span.
+type SpanLink struct {
+	Trace TraceID
+	Span  SpanID
+}
+
 // TraceOptions describes the options for a trace.
 type TraceOptions uint8
 

transaction.go

@@ -147,6 +147,7 @@ func (t *Tracer) StartTransactionOptions(name, transactionType string, opts Tran
 	if tx.timestamp.IsZero() {
 		tx.timestamp = time.Now()
 	}
+	tx.links = opts.Links
 	return tx
 }
 
@@ -163,6 +164,9 @@ type TransactionOptions struct {
 	// Start is the start time of the transaction. If this has the
 	// zero value, time.Now() will be used instead.
 	Start time.Time
+
+	// Links, if non-nil, holds a list of spans linked to the transaction.
+	Links []SpanLink
 }
 
 // Transaction describes an event occurring in the monitored service.
@@ -374,6 +378,7 @@ type TransactionData struct {
 	propagateLegacyHeader   bool
 	timestamp               time.Time
 
+	links             []SpanLink
 	mu                sync.Mutex
 	errorCaptured     bool
 	spansCreated      int

transaction_test.go

@@ -371,6 +371,31 @@ func TestTransactionSampleRateOmission(t *testing.T) {
 	}
 }
 
+func TestTransactionSpanLink(t *testing.T) {
+	tracer := apmtest.NewRecordingTracer()
+	defer tracer.Close()
+
+	links := []apm.SpanLink{
+		{Trace: apm.TraceID{1}, Span: apm.SpanID{1}},
+		{Trace: apm.TraceID{2}, Span: apm.SpanID{2}},
+	}
+
+	tx := tracer.StartTransactionOptions("name", "type", apm.TransactionOptions{Links: links})
+	tx.End()
+
+	tracer.Flush(nil)
+
+	payloads := tracer.Payloads()
+	assert.Len(t, payloads.Transactions, 1)
+
+	// Assert span links are identical.
+	expectedLinks := []model.SpanLink{
+		{TraceID: model.TraceID{1}, SpanID: model.SpanID{1}},
+		{TraceID: model.TraceID{2}, SpanID: model.SpanID{2}},
+	}
+	assert.Equal(t, expectedLinks, payloads.Transactions[0].Links)
+}
+
 func TestTransactionDiscard(t *testing.T) {
 	tracer, transport := transporttest.NewRecorderTracer()
 	defer tracer.Close()