From ce064c585173da8b010da151e476a1e78c6f1133 Mon Sep 17 00:00:00 2001
From: Emily Stolfo <emily.stolfo@elastic.co>
Date: Tue, 20 Jul 2021 11:25:26 -0400
Subject: [PATCH] Update description of span duration and composite sum

---
 docs/spec/v2/span.json         | 4 ++--
 model/modeldecoder/v2/model.go | 7 +++----
 2 files changed, 5 insertions(+), 6 deletions(-)

diff --git a/docs/spec/v2/span.json b/docs/spec/v2/span.json
index 5e7d6a60348..99f5ea6d792 100644
--- a/docs/spec/v2/span.json
+++ b/docs/spec/v2/span.json
@@ -39,7 +39,7 @@
           "minimum": 2
         },
         "sum": {
-          "description": "Sum is the durations of all compressed spans this composite span represents in milliseconds. Thus sum is the net duration of all the compressed spans while duration is the gross duration, including \"whitespace\" between the spans.",
+          "description": "Sum is the durations of all compressed spans this composite span represents in milliseconds.",
           "type": "number",
           "minimum": 0
         }
@@ -504,7 +504,7 @@
       }
     },
     "duration": {
-      "description": "Duration of the span in milliseconds",
+      "description": "Duration of the span in milliseconds. When the span is a composite one, duration is the gross duration, including \"whitespace\" in between spans.",
       "type": "number",
       "minimum": 0
     },
diff --git a/model/modeldecoder/v2/model.go b/model/modeldecoder/v2/model.go
index 7f9679fb069..f3217305c72 100644
--- a/model/modeldecoder/v2/model.go
+++ b/model/modeldecoder/v2/model.go
@@ -609,7 +609,8 @@ type span struct {
 	Composite spanComposite `json:"composite"`
 	// Context holds arbitrary contextual information for the event.
 	Context spanContext `json:"context"`
-	// Duration of the span in milliseconds
+	// Duration of the span in milliseconds. When the span is a composite one,
+	// duration is the gross duration, including "whitespace" in between spans.
 	Duration nullable.Float64 `json:"duration" validate:"required,min=0"`
 	// ID holds the hex encoded 64 random bits ID of the event.
 	ID nullable.String `json:"id" validate:"required,maxLength=1024"`
@@ -775,9 +776,7 @@ type spanComposite struct {
 	// The minimum count is 2, as a composite span represents at least two spans.
 	Count nullable.Int `json:"count" validate:"required,min=2"`
 	// Sum is the durations of all compressed spans this composite span
-	// represents in milliseconds. Thus sum is the net duration of all the
-	// compressed spans while duration is the gross duration, including
-	// "whitespace" between the spans.
+	// represents in milliseconds.
 	Sum nullable.Float64 `json:"sum" validate:"required,min=0"`
 	// A string value indicating which compression strategy was used. The valid
 	// values are `exact_match` and `same_kind`.