Minor comments fixes

src/opencensus/proto/trace/v1/trace.proto

@@ -26,23 +26,32 @@ option java_outer_classname = "TraceProto";
 option go_package = "github.com/census-instrumentation/opencensus-proto/gen-go/trace/v1";
 
 // A span represents a single operation within a trace. Spans can be
-// nested to form a trace tree. Often, a trace contains a root span
-// that describes the end-to-end latency, and one or more subspans for
-// its sub-operations. A trace can also contain multiple root spans,
-// or none at all. Spans do not need to be contiguous - there may be
-// gaps or overlaps between spans in a trace.
+// nested to form a trace tree. Spans may also be linked to other spans
+// from the same or different trace. And form graphs. Often, a trace
+// contains a root span that describes the end-to-end latency, and one
+// or more subspans for its sub-operations. A trace can also contain
+// multiple root spans, or none at all. Spans do not need to be
+// contiguous - there may be gaps or overlaps between spans in a trace.
 //
 // The next id is 16.
 // TODO(bdrutu): Add an example.
 message Span {
   // A unique identifier for a trace. All spans from the same trace share
-  // the same `trace_id`. The ID is a 16-byte array.
+  // the same `trace_id`. The ID is a 16-byte array. An ID with all zeroes
+  // is considered invalid.
+  //
+  // This field is semantically required. Receiver should generate new
+  // random trace_id if empty or invalid trace_id was received.
   //
   // This field is required.
   bytes trace_id = 1;
 
   // A unique identifier for a span within a trace, assigned when the span
-  // is created. The ID is an 8-byte array.
+  // is created. The ID is an 8-byte array. An ID with all zeroes is considered
+  // invalid.
+  //
+  // This field is semantically required. Receiver should generate new
+  // random span_id if empty or invalid span_id was received.
   //
   // This field is required.
   bytes span_id = 2;
@@ -82,6 +91,11 @@ message Span {
   // the same display name at the same call point in an application.
   // This makes it easier to correlate spans in different traces.
   //
+  // This field is semantically required to be set to non-empty string.
+  // When null or empty string received - receiver may use string "name"
+  // as a replacement. There might be smarted algorithms implemented by
+  // receiver to fix the empty span name.
+  //
   // This field is required.
   TruncatableString name = 4;
 
@@ -101,8 +115,8 @@ message Span {
   }
 
   // Distinguishes between spans generated in a particular context. For example,
-  // two spans with the same name may be distinguished using `CLIENT`
-  // and `SERVER` to identify queueing latency associated with the span.
+  // two spans with the same name may be distinguished using `CLIENT` (caller)
+  // and `SERVER` (callee) to identify queueing latency associated with the span.
   SpanKind kind = 14;
 
   // The start time of the span. On the client side, this is the time kept by
@@ -117,13 +131,14 @@ message Span {
 
   // A set of attributes, each with a key and a value.
   message Attributes {
-    // The set of attributes. The value can be a string, an integer, or the
-    // Boolean values `true` and `false`. For example:
+    // The set of attributes. The value can be a string, an integer, a double
+    // or the Boolean values `true` or `false`. Note, global attributes like 
+    // server name can be set as tags using resource API. Examples of attributes:
     //
-    //     "/instance_id": "my-instance"
-    //     "/http/user_agent": ""
+    //     "/http/user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36"
     //     "/http/server_latency": 300
     //     "abc.com/myattribute": true
+    //     "abc.com/score": 10.239
     map<string, AttributeValue> attribute_map = 1;
 
     // The number of attributes that were discarded. Attributes can be discarded
@@ -217,12 +232,11 @@ message Span {
   // where a single batch handler processes multiple requests from different
   // traces or when the handler receives a request from a different project.
   message Link {
-    // A unique identifier for a trace. All spans from the same trace share
-    // the same `trace_id`. The ID is a 16-byte array.
+    // A unique identifier of a trace that this linked span is part of. The ID is a 
+    // 16-byte array.
     bytes trace_id = 1;
 
-    // A unique identifier for a span within a trace, assigned when the span
-    // is created. The ID is an 8-byte array.
+    // A unique identifier for the linked span. The ID is an 8-byte array.
     bytes span_id = 2;
 
     // The relationship of the current span relative to the linked span: child,
@@ -261,9 +275,11 @@ message Span {
   // An optional final status for this span.
   Status status = 11;
 
-  // A highly recommended but not required flag that identifies when a trace
-  // crosses a process boundary. True when the parent_span belongs to the
-  // same process as the current span.
+  // A highly recommended but not required flag that identifies when a
+  // trace crosses a process boundary. True when the parent_span belongs
+  // to the same process as the current span. This flag is most commonly
+  // used to indicate the need to adjust time as clocks in different
+  // processes may not be synchronized.
   google.protobuf.BoolValue same_process_as_parent_span = 12;
 
   // An optional number of child spans that were generated while this span