Update span.json

Signed-off-by: Adam Gregory <pladamgregory@gmail.com>

objects/span.json

@@ -5,40 +5,40 @@
   "name": "span",
   "attributes": {
     "duration": {
-      "description": "The span duration, the amount of time the span covers from <code>start_time</code> to <code>end_time</code> in milliseconds.",
+      "description": "The total time, in seconds, that the span represents, calculated as the difference between start_time and end_time. It reflects the operation's performance and latency, independent of event timestamps, and accounts for normalized times used by observability tools to ensure consistency across distributed systems.",
+      "requirement": "optional"
+    },
+    "end_time": {
+      "description": "The end timestamp of the trace, essential for identifying latency and performance bottlenecks. Like the start time, this timestamp is normalized across the trace system to ensure consistency, even when events are recorded across distributed services with unsynchronized clocks. Normalized time allows for accurate duration calculations and helps observability tools track performance across services, regardless of the individual system time settings.",
+      "requirement": "required"
+    },
+    "message": {
+      "description": "The message in a span (often refered to as a span event) serves as a way to record significant moments or occurrences during the span's lifecycle. This content typically manifests as log entries, annotations, or semi-structured events as a string, providing additional granularity and context about what happens at specific points during the execution of an operation.",
       "requirement": "optional"
     },
     "operation": {
       "description": "Describes an action performed in a span, such as API requests, database queries, or computations.",
       "requirement": "optional"
     },
     "parent_uid": {
-      "description": "The parent span id of this span object.",
+      "description": "The ID of the parent span for this span object, establishing its relationship in the trace hierarchy.",
       "requirement": "optional"
     },
     "service": {
-      "description": "Identifies the service or component creating the span, which helps track its path through a distributed system.",
+      "description": "Identifies the service or component that generates the span, helping trace its path through the distributed system.",
       "requirement": "optional"
     },
+    "start_time": {
+      "description": "The start timestamp of the trace, essential for identifying latency and performance bottlenecks. This timestamp is normalized across the trace system, ensuring consistency even when events occur across distributed services with potentially unsynchronized clocks. By using normalized time, observability tools can provide accurate, uniform measurements of operation performance and latency, regardless of where or when the events actually occur.",
+      "requirement": "required"
+    },
     "status_code": {
-      "description": "Indicates whether the operations in the span were successful, failed, or had an error, aiding in pinpointing issues.",
+      "description": "Indicates the outcome of the operation in the span, such as success, failure, or error. Issues in a span typically refer to problems such as failed operations, timeouts, service unavailability, or errors in processing that can negatively impact the performance or reliability of the system. Tracking the `status_code` helps pinpoint these issues, enabling quicker identification and resolution of system inefficiencies or faults.",
       "requirement": "optional"
     },
     "uid": {
-      "description": "The unique identifier of the span used in distributed systems and microservices architecture to track and correlate requests across various components of an application.",
+      "description": "The unique identifier for the span, used in distributed systems and microservices architectures to track and correlate requests across different components of an application. It enables tracing the flow of a request through various services.",
       "requirement": "required"
-    },
-    "start_time": {
-      "description": "The start timestamp of the trace, essential for identifying latency and performance bottlenecks.",
-      "requirement": "optional"
-    },
-    "end_time": {
-      "description": "The end timestamp of the trace, essential for identifying latency and performance bottlenecks.",
-      "requirement": "optional"
-    },
-    "duration": {
-      "description": "The trace duration, the amount of time the trace covers from <code>start_time</code> to <code>end_time</code> in milliseconds.",
-      "requirement": "optional"
     }
   }
 }