pkg/trace/api: add support for OpenTelemetry Span Links.

pkg/trace/api/otlp.go

@@ -398,6 +398,54 @@ func marshalEvents(events ptrace.SpanEventSlice) string {
 	return str.String()
 }
 
+// marshalLinks marshals span links into JSON.
+func marshalLinks(links ptrace.SpanLinkSlice) string {
+	var str strings.Builder
+	str.WriteString("[")
+	for i := 0; i < links.Len(); i++ {
+		l := links.At(i)
+		if i > 0 {
+			str.WriteString(",")
+		}
+		t := l.TraceID()
+		str.WriteString(`{"trace_id":"`)
+		str.WriteString(hex.EncodeToString(t[:]))
+		s := l.SpanID()
+		str.WriteString(`","span_id":"`)
+		str.WriteString(hex.EncodeToString(s[:]))
+		str.WriteString(`"`)
+		if ts := l.TraceState().AsRaw(); len(ts) > 0 {
+			str.WriteString(`,"trace_state":"`)
+			str.WriteString(ts)
+			str.WriteString(`"`)
+		}
+		if l.Attributes().Len() > 0 {
+			str.WriteString(`,"attributes":{`)
+			b := false
+			l.Attributes().Range(func(k string, v pcommon.Value) bool {
+				if b {
+					str.WriteString(",")
+				}
+				b = true
+				str.WriteString(`"`)
+				str.WriteString(k)
+				str.WriteString(`":"`)
+				str.WriteString(v.AsString())
+				str.WriteString(`"`)
+				return true
+			})
+			str.WriteString("}")
+		}
+		if l.DroppedAttributesCount() > 0 {
+			str.WriteString(`,"dropped_attributes_count":`)
+			str.WriteString(strconv.FormatUint(uint64(l.DroppedAttributesCount()), 10))
+		}
+		str.WriteString("}")
+	}
+	str.WriteString("]")
+	return str.String()
+}
+
 // setMetaOTLP sets the k/v OTLP attribute pair as a tag on span s.
 func setMetaOTLP(s *pb.Span, k, v string) {
 	switch k {
@@ -457,6 +505,9 @@ func (o *OTLPReceiver) convertSpan(rattr map[string]string, lib pcommon.Instrume
 	if in.Events().Len() > 0 {
 		setMetaOTLP(span, "events", marshalEvents(in.Events()))
 	}
+	if in.Links().Len() > 0 {
+		setMetaOTLP(span, "_dd.span_links", marshalLinks(in.Links()))
+	}
 	if svc, ok := in.Attributes().Get(semconv.AttributePeerService); ok {
 		// the span attribute "peer.service" takes precedence over any resource attributes,
 		// in the same way that "service.name" does as part of setMetaOTLP

pkg/trace/api/otlp_test.go

@@ -61,6 +61,42 @@ var otlpTestSpanConfig = &testutil.OTLPSpan{
 			Dropped: 2,
 		},
 	},
+	Links: []testutil.OTLPSpanLink{
+		{
+			TraceID:    "fedcba98765432100123456789abcdef",
+			SpanID:     "abcdef0123456789",
+			TraceState: "dd=asdf256,ee=jkl;128",
+			Attributes: map[string]interface{}{
+				"a1": "v1",
+				"a2": "v2",
+			},
+			Dropped: 24,
+		},
+		{
+			TraceID:    "abcdef0123456789abcdef0123456789",
+			SpanID:     "fedcba9876543210",
+			TraceState: "",
+			Attributes: map[string]interface{}{
+				"a3": "v2",
+				"a4": "v4",
+			},
+			Dropped: 0,
+		},
+		{
+			TraceID:    "abcdef0123456789abcdef0123456789",
+			SpanID:     "fedcba9876543210",
+			TraceState: "",
+			Attributes: map[string]interface{}{},
+			Dropped:    2,
+		},
+		{
+			TraceID:    "abcdef0123456789abcdef0123456789",
+			SpanID:     "fedcba9876543210",
+			TraceState: "",
+			Attributes: map[string]interface{}{},
+			Dropped:    0,
+		},
+	},
 	StatusMsg:  "Error",
 	StatusCode: ptrace.StatusCodeError,
 }
@@ -825,6 +861,7 @@ func TestOTLPConvertSpan(t *testing.T) {
 					"w3c.tracestate":          "state",
 					"version":                 "v1.2.3",
 					"events":                  `[{"time_unix_nano":123,"name":"boom","attributes":{"key":"Out of memory","accuracy":"2.4"},"dropped_attributes_count":2},{"time_unix_nano":456,"name":"exception","attributes":{"exception.message":"Out of memory","exception.type":"mem","exception.stacktrace":"1/2/3"},"dropped_attributes_count":2}]`,
+					"_dd.span_links":          `[{"trace_id":"fedcba98765432100123456789abcdef","span_id":"abcdef0123456789","trace_state":"dd=asdf256,ee=jkl;128", "attributes":{"a1":"v1","a2":"v2"},"dropped_attributes_count":24},{"trace_id":"abcdef0123456789abcdef0123456789","span_id":"fedcba9876543210","attributes":{"a3":"v2","a4":"v4"}},{"trace_id":"abcdef0123456789abcdef0123456789","span_id":"fedcba9876543210","dropped_attributes_count":2},{"trace_id":"abcdef0123456789abcdef0123456789","span_id":"fedcba9876543210"}]`,
 					"error.msg":               "Out of memory",
 					"error.type":              "mem",
 					"error.stack":             "1/2/3",
@@ -881,6 +918,42 @@ func TestOTLPConvertSpan(t *testing.T) {
 						Dropped: 2,
 					},
 				},
+				Links: []testutil.OTLPSpanLink{
+					{
+						TraceID:    "fedcba98765432100123456789abcdef",
+						SpanID:     "abcdef0123456789",
+						TraceState: "dd=asdf256,ee=jkl;128",
+						Attributes: map[string]interface{}{
+							"a1": "v1",
+							"a2": "v2",
+						},
+						Dropped: 24,
+					},
+					{
+						TraceID:    "abcdef0123456789abcdef0123456789",
+						SpanID:     "fedcba9876543210",
+						TraceState: "",
+						Attributes: map[string]interface{}{
+							"a3": "v2",
+							"a4": "v4",
+						},
+						Dropped: 0,
+					},
+					{
+						TraceID:    "abcdef0123456789abcdef0123456789",
+						SpanID:     "fedcba9876543210",
+						TraceState: "",
+						Attributes: map[string]interface{}{},
+						Dropped:    2,
+					},
+					{
+						TraceID:    "abcdef0123456789abcdef0123456789",
+						SpanID:     "fedcba9876543210",
+						TraceState: "",
+						Attributes: map[string]interface{}{},
+						Dropped:    0,
+					},
+				},
 				StatusMsg:  "Error",
 				StatusCode: ptrace.StatusCodeError,
 			}),
@@ -907,6 +980,7 @@ func TestOTLPConvertSpan(t *testing.T) {
 					"w3c.tracestate":          "state",
 					"version":                 "v1.2.3",
 					"events":                  "[{\"time_unix_nano\":123,\"name\":\"boom\",\"attributes\":{\"message\":\"Out of memory\",\"accuracy\":\"2.4\"},\"dropped_attributes_count\":2},{\"time_unix_nano\":456,\"name\":\"exception\",\"attributes\":{\"exception.message\":\"Out of memory\",\"exception.type\":\"mem\",\"exception.stacktrace\":\"1/2/3\"},\"dropped_attributes_count\":2}]",
+					"_dd.span_links":          `[{"trace_id":"fedcba98765432100123456789abcdef","span_id":"abcdef0123456789","trace_state":"dd=asdf256,ee=jkl;128","attributes":{"a1":"v1","a2":"v2"},"dropped_attributes_count":24},{"trace_id":"abcdef0123456789abcdef0123456789","span_id":"fedcba9876543210","attributes":{"a3":"v2","a4":"v4"}},{"trace_id":"abcdef0123456789abcdef0123456789","span_id":"fedcba9876543210","dropped_attributes_count":2},{"trace_id":"abcdef0123456789abcdef0123456789","span_id":"fedcba9876543210"}]`,
 					"error.msg":               "Out of memory",
 					"error.type":              "mem",
 					"error.stack":             "1/2/3",
@@ -966,6 +1040,42 @@ func TestOTLPConvertSpan(t *testing.T) {
 						Dropped: 2,
 					},
 				},
+				Links: []testutil.OTLPSpanLink{
+					{
+						TraceID:    "fedcba98765432100123456789abcdef",
+						SpanID:     "abcdef0123456789",
+						TraceState: "dd=asdf256,ee=jkl;128",
+						Attributes: map[string]interface{}{
+							"a1": "v1",
+							"a2": "v2",
+						},
+						Dropped: 24,
+					},
+					{
+						TraceID:    "abcdef0123456789abcdef0123456789",
+						SpanID:     "fedcba9876543210",
+						TraceState: "",
+						Attributes: map[string]interface{}{
+							"a3": "v2",
+							"a4": "v4",
+						},
+						Dropped: 0,
+					},
+					{
+						TraceID:    "abcdef0123456789abcdef0123456789",
+						SpanID:     "fedcba9876543210",
+						TraceState: "",
+						Attributes: map[string]interface{}{},
+						Dropped:    2,
+					},
+					{
+						TraceID:    "abcdef0123456789abcdef0123456789",
+						SpanID:     "fedcba9876543210",
+						TraceState: "",
+						Attributes: map[string]interface{}{},
+						Dropped:    0,
+					},
+				},
 				StatusMsg:  "Error",
 				StatusCode: ptrace.StatusCodeError,
 			}),
@@ -991,6 +1101,7 @@ func TestOTLPConvertSpan(t *testing.T) {
 					"version":                 "v1.2.3",
 					"otel.trace_id":           "72df520af2bde7a5240031ead750e5f3",
 					"events":                  "[{\"time_unix_nano\":123,\"name\":\"boom\",\"attributes\":{\"message\":\"Out of memory\",\"accuracy\":\"2.4\"},\"dropped_attributes_count\":2},{\"time_unix_nano\":456,\"name\":\"exception\",\"attributes\":{\"exception.message\":\"Out of memory\",\"exception.type\":\"mem\",\"exception.stacktrace\":\"1/2/3\"},\"dropped_attributes_count\":2}]",
+					"_dd.span_links":          `[{"trace_id":"fedcba98765432100123456789abcdef","span_id":"abcdef0123456789","trace_state":"dd=asdf256,ee=jkl;128","attributes":{"a1":"v1","a2":"v2"},"dropped_attributes_count":24},{"trace_id":"abcdef0123456789abcdef0123456789","span_id":"fedcba9876543210","attributes":{"a3":"v2","a4":"v4"}},{"trace_id":"abcdef0123456789abcdef0123456789","span_id":"fedcba9876543210","dropped_attributes_count":2},{"trace_id":"abcdef0123456789abcdef0123456789","span_id":"fedcba9876543210"}]`,
 					"error.msg":               "Out of memory",
 					"error.type":              "mem",
 					"error.stack":             "1/2/3",
@@ -1084,6 +1195,17 @@ func TestOTLPConvertSpan(t *testing.T) {
 						t.Fatalf("(%d) Error unmarshalling: %v", i, err)
 					}
 					assert.Equal(wante, gote)
+				case "_dd.span_links":
+					// links contain maps with no guaranteed order of
+					// traversal; best to unpack to compare
+					var gotl, wantl []testutil.OTLPSpanLink
+					if err := json.Unmarshal([]byte(v), &wantl); err != nil {
+						t.Fatalf("(%d) Error unmarshalling: %v", i, err)
+					}
+					if err := json.Unmarshal([]byte(got.Meta[k]), &gotl); err != nil {
+						t.Fatalf("(%d) Error unmarshalling: %v", i, err)
+					}
+					assert.Equal(wantl, gotl)
 				case "_dd.container_tags":
 					// order not guaranteed, so we need to unpack and sort to compare
 					gott := strings.Split(got.Meta[tagContainersTags], ",")

pkg/trace/testutil/otlp.go

@@ -6,6 +6,7 @@
 package testutil
 
 import (
+	"encoding/hex"
 	"fmt"
 	"time"
 
@@ -29,6 +30,15 @@ type OTLPSpanEvent struct {
 	Dropped    uint32                 `json:"dropped_attributes_count"`
 }
 
+// OTLPSpanLink defines an OTLP test span link.
+type OTLPSpanLink struct {
+	TraceID    string                 `json:"trace_id"`
+	SpanID     string                 `json:"span_id"`
+	TraceState string                 `json:"trace_state"`
+	Attributes map[string]interface{} `json:"attributes"`
+	Dropped    uint32                 `json:"dropped_attributes_count"`
+}
+
 // OTLPSpan defines an OTLP test span.
 type OTLPSpan struct {
 	TraceID    [16]byte
@@ -40,6 +50,7 @@ type OTLPSpan struct {
 	Start, End uint64
 	Attributes map[string]interface{}
 	Events     []OTLPSpanEvent
+	Links      []OTLPSpanLink
 	StatusMsg  string
 	StatusCode ptrace.StatusCode
 }
@@ -87,6 +98,17 @@ func setOTLPSpan(span ptrace.Span, s *OTLPSpan) {
 		insertAttributes(ev.Attributes(), e.Attributes)
 		ev.SetDroppedAttributesCount(e.Dropped)
 	}
+	links := span.Links()
+	for _, l := range s.Links {
+		li := links.AppendEmpty()
+		bytes, _ := hex.DecodeString(l.TraceID)
+		li.SetTraceID(*(*pcommon.TraceID)(bytes))
+		bytes, _ = hex.DecodeString(l.SpanID)
+		li.SetSpanID(*(*pcommon.SpanID)(bytes))
+		li.TraceState().FromRaw(l.TraceState)
+		insertAttributes(li.Attributes(), l.Attributes)
+		li.SetDroppedAttributesCount(l.Dropped)
+	}
 	span.Status().SetCode(s.StatusCode)
 	span.Status().SetMessage(s.StatusMsg)
 }

releasenotes/notes/apm-span-links-support-78478b81bf08e26f.yaml

@@ -0,0 +1,11 @@
+# Each section from every releasenote are combined when the
+# CHANGELOG.rst is rendered. So the text needs to be worded so that
+# it does not depend on any information only available in another
+# section. This may mean repeating some details, but each section
+# must be readable independently of the other.
+#
+# Each section note must be formatted as reStructuredText.
+---
+enhancements:
+  - |
+    Adds support for OpenTelemetry span links to the Trace Agent OTLP endpoint when converting OTLP spans (span links are added as metadata to the converted span).