feat: Add types and rename fields for tracing

This overhauls the tracing-related types and their serialization to JSON. We rename Event.StartTimestamp, Span.StartTimestamp and Span.EndTimestamp to remove the "stamp" suffix in preparation to use StartTime and EndTime for spans when full tracing support is added. Preferring the shorter name because it is shorter and equally clear, and the type is time.Time. This is a breaking change, but should not affect most users, as those names were only used by the Sentry OpenTelemetry Exporter (we can update it) and are marked as experimental APIs.
getsentry · Dec 1, 2020 · 18aaf7e · 18aaf7e
1 parent 52d9d61
commit 18aaf7e
Show file tree

Hide file tree

Showing 7 changed files with 324 additions and 72 deletions.
diff --git a/interfaces.go b/interfaces.go
@@ -186,13 +186,19 @@ type Event struct {
 	Request     *Request               `json:"request,omitempty"`
 	Exception   []Exception            `json:"exception,omitempty"`
 
-	// Experimental: This is part of a beta feature of the SDK. The fields below
-	// are only relevant for transactions.
-	Type           string    `json:"type,omitempty"`
-	StartTimestamp time.Time `json:"start_timestamp"`
-	Spans          []*Span   `json:"spans,omitempty"`
+	// The fields below are only relevant for transactions.
+
+	Type      string    `json:"type,omitempty"`
+	StartTime time.Time `json:"start_timestamp"`
+	Spans     []*Span   `json:"spans,omitempty"`
 }
 
+// TODO: Event.Contexts map[string]interface{} => map[string]EventContext,
+// to prevent accidentally storing T when we mean *T.
+// For example, the TraceContext must be stored as *TraceContext to pick up the
+// MarshalJSON method (and avoid copying).
+// type EventContext interface{ EventContext() }
+
 // MarshalJSON converts the Event struct to JSON.
 func (e *Event) MarshalJSON() ([]byte, error) {
 	// We want to omit time.Time zero values, otherwise the server will try to
@@ -226,9 +232,9 @@ func (e *Event) defaultMarshalJSON() ([]byte, error) {
 		// be sent for transactions. They shadow the respective fields in Event
 		// and are meant to remain nil, triggering the omitempty behavior.
 
-		Type           json.RawMessage `json:"type,omitempty"`
-		StartTimestamp json.RawMessage `json:"start_timestamp,omitempty"`
-		Spans          json.RawMessage `json:"spans,omitempty"`
+		Type      json.RawMessage `json:"type,omitempty"`
+		StartTime json.RawMessage `json:"start_timestamp,omitempty"`
+		Spans     json.RawMessage `json:"spans,omitempty"`
 	}
 
 	x := errorEvent{event: (*event)(e)}
@@ -255,8 +261,8 @@ func (e *Event) transactionMarshalJSON() ([]byte, error) {
 		// The fields below shadow the respective fields in Event. They allow us
 		// to include timestamps when non-zero and omit them otherwise.
 
-		StartTimestamp json.RawMessage `json:"start_timestamp,omitempty"`
-		Timestamp      json.RawMessage `json:"timestamp,omitempty"`
+		StartTime json.RawMessage `json:"start_timestamp,omitempty"`
+		Timestamp json.RawMessage `json:"timestamp,omitempty"`
 	}
 
 	x := transactionEvent{event: (*event)(e)}
@@ -267,12 +273,12 @@ func (e *Event) transactionMarshalJSON() ([]byte, error) {
 		}
 		x.Timestamp = b
 	}
-	if !e.StartTimestamp.IsZero() {
-		b, err := e.StartTimestamp.MarshalJSON()
+	if !e.StartTime.IsZero() {
+		b, err := e.StartTime.MarshalJSON()
 		if err != nil {
 			return nil, err
 		}
-		x.StartTimestamp = b
+		x.StartTime = b
 	}
 	return json.Marshal(x)
 }
@@ -307,30 +313,3 @@ type EventHint struct {
 	Request            *http.Request
 	Response           *http.Response
 }
-
-// TraceContext describes the context of the trace.
-//
-// Experimental: This is part of a beta feature of the SDK.
-type TraceContext struct {
-	TraceID     string `json:"trace_id"`
-	SpanID      string `json:"span_id"`
-	Op          string `json:"op,omitempty"`
-	Description string `json:"description,omitempty"`
-	Status      string `json:"status,omitempty"`
-}
-
-// Span describes a timed unit of work in a trace.
-//
-// Experimental: This is part of a beta feature of the SDK.
-type Span struct {
-	TraceID        string                 `json:"trace_id"`
-	SpanID         string                 `json:"span_id"`
-	ParentSpanID   string                 `json:"parent_span_id,omitempty"`
-	Op             string                 `json:"op,omitempty"`
-	Description    string                 `json:"description,omitempty"`
-	Status         string                 `json:"status,omitempty"`
-	Tags           map[string]string      `json:"tags,omitempty"`
-	StartTimestamp time.Time              `json:"start_timestamp"`
-	EndTimestamp   time.Time              `json:"timestamp"`
-	Data           map[string]interface{} `json:"data,omitempty"`
-}
diff --git a/interfaces_test.go b/interfaces_test.go
@@ -44,22 +44,22 @@ func TestNewRequest(t *testing.T) {
 func TestEventMarshalJSON(t *testing.T) {
 	event := NewEvent()
 	event.Spans = []*Span{{
-		TraceID:        "d6c4f03650bd47699ec65c84352b6208",
-		SpanID:         "1cc4b26ab9094ef0",
-		ParentSpanID:   "442bd97bbe564317",
-		StartTimestamp: time.Unix(8, 0).UTC(),
-		EndTimestamp:   time.Unix(10, 0).UTC(),
-		Status:         "ok",
+		TraceID:      TraceIDFromHex("d6c4f03650bd47699ec65c84352b6208"),
+		SpanID:       SpanIDFromHex("1cc4b26ab9094ef0"),
+		ParentSpanID: SpanIDFromHex("442bd97bbe564317"),
+		StartTime:    time.Unix(8, 0).UTC(),
+		EndTime:      time.Unix(10, 0).UTC(),
+		Status:       SpanStatusOK,
 	}}
-	event.StartTimestamp = time.Unix(7, 0).UTC()
+	event.StartTime = time.Unix(7, 0).UTC()
 	event.Timestamp = time.Unix(14, 0).UTC()
 
 	got, err := json.Marshal(event)
 	if err != nil {
 		t.Fatal(err)
 	}
 
-	// Non transaction event should not have fields Spans and StartTimestamp
+	// Non-transaction event should not have fields Spans and StartTime
 	want := `{"sdk":{},"user":{},"timestamp":"1970-01-01T00:00:14Z"}`
 
 	if diff := cmp.Diff(want, string(got)); diff != "" {
@@ -69,18 +69,18 @@ func TestEventMarshalJSON(t *testing.T) {
 
 func TestStructSnapshots(t *testing.T) {
 	testSpan := &Span{
-		TraceID:      "d6c4f03650bd47699ec65c84352b6208",
-		SpanID:       "1cc4b26ab9094ef0",
-		ParentSpanID: "442bd97bbe564317",
+		TraceID:      TraceIDFromHex("d6c4f03650bd47699ec65c84352b6208"),
+		SpanID:       SpanIDFromHex("1cc4b26ab9094ef0"),
+		ParentSpanID: SpanIDFromHex("442bd97bbe564317"),
 		Description:  `SELECT * FROM user WHERE "user"."id" = {id}`,
 		Op:           "db.sql",
 		Tags: map[string]string{
 			"function_name":  "get_users",
 			"status_message": "MYSQL OK",
 		},
-		StartTimestamp: time.Unix(0, 0).UTC(),
-		EndTimestamp:   time.Unix(5, 0).UTC(),
-		Status:         "ok",
+		StartTime: time.Unix(0, 0).UTC(),
+		EndTime:   time.Unix(5, 0).UTC(),
+		Status:    SpanStatusOK,
 		Data: map[string]interface{}{
 			"related_ids":  []uint{12312342, 76572, 4123485},
 			"aws_instance": "ca-central-1",
@@ -134,17 +134,17 @@ func TestStructSnapshots(t *testing.T) {
 		{
 			testName: "transaction_event",
 			sentryStruct: &Event{
-				Type:           transactionType,
-				Spans:          []*Span{testSpan},
-				StartTimestamp: time.Unix(3, 0).UTC(),
-				Timestamp:      time.Unix(5, 0).UTC(),
+				Type:      transactionType,
+				Spans:     []*Span{testSpan},
+				StartTime: time.Unix(3, 0).UTC(),
+				Timestamp: time.Unix(5, 0).UTC(),
 				Contexts: map[string]interface{}{
-					"trace": TraceContext{
-						TraceID:     "90d57511038845dcb4164a70fc3a7fdb",
-						SpanID:      "f7f3fd754a9040eb",
+					"trace": &TraceContext{
+						TraceID:     TraceIDFromHex("90d57511038845dcb4164a70fc3a7fdb"),
+						SpanID:      SpanIDFromHex("f7f3fd754a9040eb"),
 						Op:          "http.GET",
 						Description: "description",
-						Status:      "ok",
+						Status:      SpanStatusOK,
 					},
 				},
 			},

diff --git a/marshal_test.go b/marshal_test.go
@@ -89,14 +89,14 @@ func TestErrorEventMarshalJSON(t *testing.T) {
 func TestTransactionEventMarshalJSON(t *testing.T) {
 	tests := []*Event{
 		{
-			Type:           transactionType,
-			StartTimestamp: goReleaseDate.Add(-time.Minute),
-			Timestamp:      goReleaseDate,
+			Type:      transactionType,
+			StartTime: goReleaseDate.Add(-time.Minute),
+			Timestamp: goReleaseDate,
 		},
 		{
-			Type:           transactionType,
-			StartTimestamp: goReleaseDate.Add(-time.Minute).In(utcMinusTwo),
-			Timestamp:      goReleaseDate.In(utcMinusTwo),
+			Type:      transactionType,
+			StartTime: goReleaseDate.Add(-time.Minute).In(utcMinusTwo),
+			Timestamp: goReleaseDate.In(utcMinusTwo),
 		},
 		{
 			Type: transactionType,

diff --git a/testdata/span.golden b/testdata/span.golden
@@ -1,7 +1,6 @@
 {
     "trace_id": "d6c4f03650bd47699ec65c84352b6208",
     "span_id": "1cc4b26ab9094ef0",
-    "parent_span_id": "442bd97bbe564317",
     "op": "db.sql",
     "description": "SELECT * FROM user WHERE \"user\".\"id\" = {id}",
     "status": "ok",
@@ -18,5 +17,6 @@
             76572,
             4123485
         ]
-    }
+    },
+    "parent_span_id": "442bd97bbe564317"
 }
diff --git a/testdata/transaction_event.golden b/testdata/transaction_event.golden
@@ -15,7 +15,6 @@
         {
             "trace_id": "d6c4f03650bd47699ec65c84352b6208",
             "span_id": "1cc4b26ab9094ef0",
-            "parent_span_id": "442bd97bbe564317",
             "op": "db.sql",
             "description": "SELECT * FROM user WHERE \"user\".\"id\" = {id}",
             "status": "ok",
@@ -32,7 +31,8 @@
                     76572,
                     4123485
                 ]
-            }
+            },
+            "parent_span_id": "442bd97bbe564317"
         }
     ],
     "start_timestamp": "1970-01-01T00:00:03Z",